@camstack/types 1.2.417 → 1.2.418

package/dist/composition/composition.d.ts

@@ -19,6 +19,7 @@
  */
 import { z } from 'zod';
 import { DeviceRole, DeviceType } from '../device/device-type.js';
+import { type CompositionSourceRef } from './source-ref.js';
 /** The owner of every composed device: the `composer` builtin. */
 export declare const COMPOSER_ADDON_ID = "composer";
 /**
@@ -34,11 +35,7 @@ export declare const MAX_COMPOSITION_FEATURES = 16;
 export declare const MAX_COMPOSITION_FIELDS_PER_FEATURE = 32;
 /** Longest snippet a `code` source may carry (slice 4). */
 export declare const MAX_COMPOSITION_CODE_LENGTH = 20000;
-export declare const CompositionSourceRefSchema: z.ZodObject<{
-    addonId: z.ZodString;
-    stableId: z.ZodString;
-}, z.core.$strip>;
-export type CompositionSourceRef = z.infer<typeof CompositionSourceRefSchema>;
+export { CompositionSourceRefSchema, type CompositionSourceRef } from './source-ref.js';
 /** One field of one capability of one source device. */
 export declare const CompositionFieldReadSchema: z.ZodObject<{
     source: z.ZodObject<{
@@ -107,6 +104,43 @@ export declare const CompositionCodeSourceSchema: z.ZodObject<{
     code: z.ZodString;
 }, z.core.$strip>;
 export type CompositionCodeSource = z.infer<typeof CompositionCodeSourceSchema>;
+/**
+ * `aggregate`: a group reducer. Offline and unknown reads are excluded, not
+ * folded in as 0 or false (D944). Free expressions stay `expression` so a
+ * stale member is still included there.
+ */
+export declare const CompositionAggregateSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"aggregate">;
+    reducer: z.ZodEnum<{
+        all: "all";
+        any: "any";
+        max: "max";
+        mean: "mean";
+        median: "median";
+        min: "min";
+        sum: "sum";
+    }>;
+    reads: z.ZodArray<z.ZodObject<{
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>>;
+    publish: z.ZodEnum<{
+        excluded: "excluded";
+        included: "included";
+        total: "total";
+        value: "value";
+    }>;
+    empty: z.ZodEnum<{
+        null: "null";
+        offline: "offline";
+        omit: "omit";
+    }>;
+}, z.core.$strip>;
+export type CompositionAggregateSource = z.infer<typeof CompositionAggregateSourceSchema>;
 export declare const CompositionFieldSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     source: z.ZodObject<{
         addonId: z.ZodString;
@@ -133,6 +167,36 @@ export declare const CompositionFieldSourceSchema: z.ZodDiscriminatedUnion<[z.Zo
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"code">;
     code: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"aggregate">;
+    reducer: z.ZodEnum<{
+        all: "all";
+        any: "any";
+        max: "max";
+        mean: "mean";
+        median: "median";
+        min: "min";
+        sum: "sum";
+    }>;
+    reads: z.ZodArray<z.ZodObject<{
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>>;
+    publish: z.ZodEnum<{
+        excluded: "excluded";
+        included: "included";
+        total: "total";
+        value: "value";
+    }>;
+    empty: z.ZodEnum<{
+        null: "null";
+        offline: "offline";
+        omit: "omit";
+    }>;
 }, z.core.$strip>], "kind">;
 export type CompositionFieldSource = z.infer<typeof CompositionFieldSourceSchema>;
 /** `forward`: RESERVED for slice 3. Argument mapping arrives there as an additive optional `args`. */
@@ -197,6 +261,36 @@ export declare const CompositionItemEntrySchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"aggregate">;
+        reducer: z.ZodEnum<{
+            all: "all";
+            any: "any";
+            max: "max";
+            mean: "mean";
+            median: "median";
+            min: "min";
+            sum: "sum";
+        }>;
+        reads: z.ZodArray<z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>>;
+        publish: z.ZodEnum<{
+            excluded: "excluded";
+            included: "included";
+            total: "total";
+            value: "value";
+        }>;
+        empty: z.ZodEnum<{
+            null: "null";
+            offline: "offline";
+            omit: "omit";
+        }>;
     }, z.core.$strip>], "kind">>;
 }, z.core.$strip>;
 export type CompositionItemEntry = z.infer<typeof CompositionItemEntrySchema>;
@@ -230,6 +324,36 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"aggregate">;
+        reducer: z.ZodEnum<{
+            all: "all";
+            any: "any";
+            max: "max";
+            mean: "mean";
+            median: "median";
+            min: "min";
+            sum: "sum";
+        }>;
+        reads: z.ZodArray<z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>>;
+        publish: z.ZodEnum<{
+            excluded: "excluded";
+            included: "included";
+            total: "total";
+            value: "value";
+        }>;
+        empty: z.ZodEnum<{
+            null: "null";
+            offline: "offline";
+            omit: "omit";
+        }>;
     }, z.core.$strip>], "kind">>;
     items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         label: z.ZodString;
@@ -259,6 +383,36 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"code">;
             code: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"aggregate">;
+            reducer: z.ZodEnum<{
+                all: "all";
+                any: "any";
+                max: "max";
+                mean: "mean";
+                median: "median";
+                min: "min";
+                sum: "sum";
+            }>;
+            reads: z.ZodArray<z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>>;
+            publish: z.ZodEnum<{
+                excluded: "excluded";
+                included: "included";
+                total: "total";
+                value: "value";
+            }>;
+            empty: z.ZodEnum<{
+                null: "null";
+                offline: "offline";
+                omit: "omit";
+            }>;
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>;
     commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -316,6 +470,36 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"aggregate">;
+        reducer: z.ZodEnum<{
+            all: "all";
+            any: "any";
+            max: "max";
+            mean: "mean";
+            median: "median";
+            min: "min";
+            sum: "sum";
+        }>;
+        reads: z.ZodArray<z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>>;
+        publish: z.ZodEnum<{
+            excluded: "excluded";
+            included: "included";
+            total: "total";
+            value: "value";
+        }>;
+        empty: z.ZodEnum<{
+            null: "null";
+            offline: "offline";
+            omit: "omit";
+        }>;
     }, z.core.$strip>], "kind">>;
     items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         label: z.ZodString;
@@ -345,6 +529,36 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"code">;
             code: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"aggregate">;
+            reducer: z.ZodEnum<{
+                all: "all";
+                any: "any";
+                max: "max";
+                mean: "mean";
+                median: "median";
+                min: "min";
+                sum: "sum";
+            }>;
+            reads: z.ZodArray<z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>>;
+            publish: z.ZodEnum<{
+                excluded: "excluded";
+                included: "included";
+                total: "total";
+                value: "value";
+            }>;
+            empty: z.ZodEnum<{
+                null: "null";
+                offline: "offline";
+                omit: "omit";
+            }>;
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>;
     commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -444,6 +658,36 @@ export declare const CompositionSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"code">;
             code: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"aggregate">;
+            reducer: z.ZodEnum<{
+                all: "all";
+                any: "any";
+                max: "max";
+                mean: "mean";
+                median: "median";
+                min: "min";
+                sum: "sum";
+            }>;
+            reads: z.ZodArray<z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>>;
+            publish: z.ZodEnum<{
+                excluded: "excluded";
+                included: "included";
+                total: "total";
+                value: "value";
+            }>;
+            empty: z.ZodEnum<{
+                null: "null";
+                offline: "offline";
+                omit: "omit";
+            }>;
         }, z.core.$strip>], "kind">>;
         items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             label: z.ZodString;
@@ -473,6 +717,36 @@ export declare const CompositionSchema: z.ZodObject<{
             }, z.core.$strip>, z.ZodObject<{
                 kind: z.ZodLiteral<"code">;
                 code: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"aggregate">;
+                reducer: z.ZodEnum<{
+                    all: "all";
+                    any: "any";
+                    max: "max";
+                    mean: "mean";
+                    median: "median";
+                    min: "min";
+                    sum: "sum";
+                }>;
+                reads: z.ZodArray<z.ZodObject<{
+                    source: z.ZodObject<{
+                        addonId: z.ZodString;
+                        stableId: z.ZodString;
+                    }, z.core.$strip>;
+                    cap: z.ZodString;
+                    fieldPath: z.ZodString;
+                }, z.core.$strip>>;
+                publish: z.ZodEnum<{
+                    excluded: "excluded";
+                    included: "included";
+                    total: "total";
+                    value: "value";
+                }>;
+                empty: z.ZodEnum<{
+                    null: "null";
+                    offline: "offline";
+                    omit: "omit";
+                }>;
             }, z.core.$strip>], "kind">>;
         }, z.core.$strip>>>;
         commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -496,6 +770,12 @@ export declare const CompositionSchema: z.ZodObject<{
             stableId: z.ZodString;
         }, z.core.$strip>;
     }, z.core.$strip>], "kind">>;
+    helper: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<'group'>;
+        templateId: typeof import("./index.js").GroupTemplateIdSchema;
+        aggregate: typeof import("./index.js").AggregateReducerSchema;
+        members: z.ZodArray<typeof import("./index.js").HelperMemberSchema>;
+    }, z.core.$strip>], "kind">>;
 }, z.core.$strip>;
 export type Composition = z.infer<typeof CompositionSchema>;
 export declare function compositionSourceKey(ref: CompositionSourceRef): string;

package/dist/composition/helpers/aggregate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A group reducer (D944). Offline and unknown members are excluded and
+ * counted. They are never passed in as 0 or false (D393). A free expression
+ * does not use this — `avg` / `any` still include a stale value.
+ */
+import type { ExpressionValue } from '../../expression/ast.js';
+import type { AggregateReducer } from './spec.js';
+export interface AggregateReadResult {
+    readonly state: 'fresh' | 'stale' | 'unavailable';
+    readonly value?: ExpressionValue;
+    /** Set when `state` is `unavailable` and the source is gone. */
+    readonly fatal?: boolean;
+    readonly reason?: string;
+}
+export interface AggregateCounts {
+    readonly included: number;
+    readonly excluded: number;
+    readonly total: number;
+}
+export type AggregatePublish = 'value' | 'included' | 'excluded' | 'total';
+export type AggregateEmpty = 'null' | 'omit' | 'offline';
+export interface EvaluateAggregateInput {
+    readonly reducer: AggregateReducer;
+    readonly members: readonly AggregateReadResult[];
+    readonly publish: AggregatePublish;
+    readonly empty: AggregateEmpty;
+}
+export interface AggregateValue {
+    readonly kind: 'value';
+    readonly value: number | boolean | null;
+    readonly counts: AggregateCounts;
+}
+export interface AggregateUnavailable {
+    readonly kind: 'unavailable';
+    readonly fatal: boolean;
+    readonly reason: string;
+    readonly counts: AggregateCounts;
+}
+export type AggregateOutcome = AggregateValue | AggregateUnavailable;
+/** Pure. `members` is not mutated. An empty included set is null or unavailable, never 0 or false. */
+export declare function evaluateAggregate(input: EvaluateAggregateInput): AggregateOutcome;

package/dist/composition/helpers/catalog.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One catalog row per base reading a group helper can build (D944 §3).
+ * Data, not a form default written into the block.
+ */
+import { DeviceRole, DeviceType } from '../../device/device-type.js';
+import { type ReadingQuantity } from '../../units/quantity.js';
+import type { AggregateEmpty } from './aggregate.js';
+import { type AggregateReducer, type GroupTemplateId } from './spec.js';
+export interface HelperAccept {
+    readonly cap: string;
+    readonly fieldPath: string;
+}
+export interface HelperCompanion {
+    readonly fieldPath: string;
+    readonly expr: string;
+}
+export interface GroupTemplate {
+    readonly id: GroupTemplateId;
+    readonly family: 'numeric' | 'binary';
+    readonly summary: string;
+    readonly deviceType: DeviceType;
+    readonly role: DeviceRole;
+    /** Members are this one device type. */
+    readonly memberDeviceType: DeviceType;
+    readonly outputCap: string;
+    readonly outputField: string;
+    /** Quantity of the output reading. `device` is chosen per numeric sensor. */
+    readonly quantity: ReadingQuantity;
+    readonly baseUnit: string | undefined;
+    readonly aggregates: readonly AggregateReducer[];
+    readonly defaultAggregate: AggregateReducer;
+    /**
+     * No included member: `null` writes null and stays online; `omit` leaves an
+     * optional key out and stays online; `offline` takes the device offline
+     * rather than publishing false (D393).
+     */
+    readonly empty: AggregateEmpty;
+    readonly accept: readonly HelperAccept[];
+    readonly companions: readonly HelperCompanion[];
+}
+export declare const GROUP_TEMPLATES: readonly GroupTemplate[];
+export declare function groupTemplate(id: GroupTemplateId): GroupTemplate | null;

package/dist/composition/helpers/compile.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project a helper spec onto the composition the composer already runs (D944).
+ * Pure: it stores nothing. A group does not compile to `avg(...)` / `any(...)`.
+ */
+import { DeviceType } from '../../device/device-type.js';
+import { type Composition } from '../composition.js';
+import type { CompositionProblem } from '../composition-report.js';
+import { type HelperSpec } from './spec.js';
+export interface HelperCompiled {
+    readonly ok: true;
+    readonly composition: Composition;
+}
+export interface HelperRefused {
+    readonly ok: false;
+    readonly problems: readonly CompositionProblem[];
+}
+export type HelperCompileResult = HelperCompiled | HelperRefused;
+/** Compile a group template to a new-device composition. Refusals are named. */
+export declare function compileHelper(spec: HelperSpec): HelperCompileResult;
+/** The built body, ignoring `helper`, so a save can demand one writer. */
+export declare function sameHelperBody(stored: Composition, compiled: Composition): boolean;
+export declare function templateDeviceType(spec: HelperSpec): DeviceType | null;

package/dist/composition/helpers/index.d.ts

@@ -0,0 +1,6 @@
+export { type AggregateCounts, type AggregateEmpty, type AggregateOutcome, type AggregatePublish, type AggregateReadResult, type AggregateUnavailable, type AggregateValue, type EvaluateAggregateInput, evaluateAggregate, } from './aggregate.js';
+export { type GroupTemplate, type HelperAccept, type HelperCompanion, GROUP_TEMPLATES, groupTemplate, } from './catalog.js';
+export { type HelperCompileResult, type HelperCompiled, type HelperRefused, compileHelper, sameHelperBody, templateDeviceType, } from './compile.js';
+export { type HelperMemberFact, helperSaveProblems, } from './save.js';
+export { type SourcePick, type SourcePickAccept, type SourcePickHistory, type SourcePickRequest, sourcePickForTemplate, } from './source-pick.js';
+export { AGGREGATE_REDUCERS, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, MAX_HELPER_MEMBERS, NUMERIC_AGGREGATES, type AggregateReducer, type BinaryAggregate, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type NumericAggregate, } from './spec.js';

package/dist/composition/helpers/save.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Save-time checks a pure compile cannot make: the compiled features must be
+ * this spec's, and members that report a quantity must share one (D944 §4).
+ */
+import type { DeviceType } from '../../device/device-type.js';
+import type { ReadingQuantity } from '../../units/quantity.js';
+import { type Composition } from '../composition.js';
+import type { CompositionProblem } from '../composition-report.js';
+/** What a save learned about one member device. Absent keys were not read. */
+export interface HelperMemberFact {
+    readonly deviceType?: DeviceType;
+    readonly quantity?: ReadingQuantity;
+}
+/**
+ * Problems that refuse a save. No `helper` key means a free composition: this
+ * returns nothing, and expression semantics stay as they are.
+ */
+export declare function helperSaveProblems(composition: Composition, facts: ReadonlyMap<string, HelperMemberFact>): readonly CompositionProblem[];

package/dist/composition/helpers/source-pick.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The request the common source selector (#236) accepts for a helper (D944 §5).
+ * The selector's layout is not specified here. Groups ask for one device type
+ * and the catalog field; they do not opt into incompatible fields.
+ */
+import type { DeviceType } from '../../device/device-type.js';
+import type { CompositionSourceRef } from '../source-ref.js';
+import type { GroupTemplate } from './catalog.js';
+export interface SourcePickAccept {
+    readonly cap: string;
+    readonly fieldPath: string;
+    readonly valueKind: 'number' | 'boolean';
+}
+export interface SourcePickHistory {
+    readonly required: boolean;
+    readonly minRetentionMs: number | null;
+}
+export interface SourcePickRequest {
+    readonly purpose: 'member' | 'reading' | 'historised';
+    readonly multiple: boolean;
+    readonly max: number;
+    readonly deviceTypes: readonly DeviceType[];
+    readonly accept: readonly SourcePickAccept[];
+    readonly history: SourcePickHistory;
+    readonly mustBindCaps: readonly string[];
+    readonly exclude: readonly CompositionSourceRef[];
+}
+export interface SourcePick {
+    readonly source: CompositionSourceRef;
+    readonly deviceId: number;
+    readonly parentName: string | null;
+    readonly cap: string;
+    readonly fieldPath: string;
+    /** Current reading. `null` is unknown, never a stand-in 0. */
+    readonly current: number | boolean | string | null;
+    readonly compatibility: 'direct' | 'convert' | 'incompatible';
+    readonly history: 'recorded' | 'absent' | 'unknown';
+}
+/** What the member step asks the selector for this template. */
+export declare function sourcePickForTemplate(template: GroupTemplate): SourcePickRequest;

package/dist/composition/helpers/spec.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A helper spec is what the editor stores and reads back (D944). The compiled
+ * features are a projection; the editor never edits the expression.
+ */
+import { z } from 'zod';
+import { CompositionSourceRefSchema } from '../source-ref.js';
+/** A group may name more members than an expression call (the 16-arg cap). */
+export declare const MAX_HELPER_MEMBERS: number;
+export declare const GROUP_TEMPLATE_IDS: readonly ['temperature', 'humidity', 'pressure', 'illuminance', 'power', 'energy', 'battery', 'numeric', 'motion', 'contact', 'leak', 'smoke', 'occupancy', 'binary'];
+export type GroupTemplateId = (typeof GROUP_TEMPLATE_IDS)[number];
+export declare const NUMERIC_AGGREGATES: readonly ['mean', 'median', 'min', 'max', 'sum'];
+export type NumericAggregate = (typeof NUMERIC_AGGREGATES)[number];
+export declare const BINARY_AGGREGATES: readonly ['any', 'all'];
+export type BinaryAggregate = (typeof BINARY_AGGREGATES)[number];
+export declare const AGGREGATE_REDUCERS: readonly ['mean', 'median', 'min', 'max', 'sum', 'any', 'all'];
+export type AggregateReducer = (typeof AGGREGATE_REDUCERS)[number];
+export declare const GroupTemplateIdSchema: z.ZodType<GroupTemplateId>;
+export declare const AggregateReducerSchema: z.ZodType<AggregateReducer>;
+/** One member. The field is stored so occupancy can name motion or binary. */
+export declare const HelperMemberSchema: z.ZodObject<{
+    source: typeof CompositionSourceRefSchema;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+}>;
+export type HelperMember = z.infer<typeof HelperMemberSchema>;
+/**
+ * Phase 1a is groups only. Math, integral and statistics stay off this union
+ * until the composer can run them — a control must not save a spec it cannot.
+ */
+export declare const GroupHelperSpecSchema: z.ZodObject<{
+    kind: z.ZodLiteral<'group'>;
+    templateId: typeof GroupTemplateIdSchema;
+    aggregate: typeof AggregateReducerSchema;
+    members: z.ZodArray<typeof HelperMemberSchema>;
+}>;
+export type GroupHelperSpec = z.infer<typeof GroupHelperSpecSchema>;
+export declare const HelperSpecSchema: z.ZodDiscriminatedUnion<[typeof GroupHelperSpecSchema], 'kind'>;
+export type HelperSpec = z.infer<typeof HelperSpecSchema>;

package/dist/composition/index.d.ts

@@ -3,6 +3,7 @@
  * inside @camstack/types import the deep modules, never this file.
  */
 export * from './composable-caps.js';
+export * from './helpers/index.js';
 export * from './composition.js';
 export * from './composition-events.js';
 export * from './composition-graph.js';

package/dist/composition/source-ref.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A composition source identity: `(addonId, stableId)`, never a numeric device
+ * id. Split out so helper schemas can name it without a cycle through
+ * `composition.ts` (D659).
+ */
+import { z } from 'zod';
+export declare const CompositionSourceRefSchema: z.ZodObject<{
+    addonId: z.ZodString;
+    stableId: z.ZodString;
+}>;
+export type CompositionSourceRef = z.infer<typeof CompositionSourceRefSchema>;

package/dist/composition/validate-composition.d.ts

@@ -10,6 +10,7 @@
  */
 import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
 import type { DeviceType } from '../device/device-type.js';
+import type { ReadingQuantity } from '../units/quantity.js';
 import { type Composition, type CompositionSourceRef } from './composition.js';
 import { type CompositionPlanResult } from './plan-result.js';
 import { type CompositionPeer } from './composition-graph.js';
@@ -22,6 +23,10 @@ export interface CompositionSourceFound {
     readonly kind: 'found';
     readonly deviceId: number;
     readonly caps: ReadonlySet<string>;
+    /** Present when the row was read. A helper group requires this one type. */
+    readonly deviceType?: DeviceType;
+    /** Present when the device declares one. Mixed quantities are refused. */
+    readonly quantity?: ReadingQuantity;
 }
 export interface CompositionSourceAbsent {
     readonly kind: 'absent';