@camstack/types 1.2.421 → 1.2.422

package/dist/capabilities/index.d.ts

@@ -198,6 +198,7 @@ export { type DeviceCodeSeverity, DeviceCodeSeveritySchema, type ILawnMowerContr
 export { type AdvertisedLocalPort, type ConnectionEndpoint, type HubAddressBook, type HubAddresses, HubAddressRoleSchema, type HubAddressRow, type HubAddressSnapshot, type ILocalNetworkProvider, type LocalInterface, localNetworkCapability, type NotificationEndpoint, } from './local-network.cap.js';
 export { type ILockControlProvider, type LockControlStatus, LockControlStatusSchema, type LockState, LockStateSchema, lockControlCapability, } from './lock-control.cap.js';
 export { type MaskGridDims, MaskGridDimsSchema, type MaskGridShape, MaskGridShapeSchema, type MaskLineShape, MaskLineShapeSchema, type MaskPoint, MaskPointSchema, type MaskPolygonShape, MaskPolygonShapeSchema, type MaskPolygonVertices, MaskPolygonVerticesSchema, type MaskRectShape, MaskRectShapeSchema, type MaskShape, type MaskShapeKind, MaskShapeKindSchema, MaskShapeSchema, } from './mask-shape.js';
+export { type MeterStatus, MeterStatusSchema, meterCapability, type IMeterProvider, } from './meter.cap.js';
 export { type IMediaPlayerProvider, type MediaInfo, type MediaPlayerRepeat, MediaPlayerRepeatSchema, type MediaPlayerState, MediaPlayerStateSchema, type MediaPlayerStatus, MediaPlayerStatusSchema, mediaPlayerCapability, } from './media-player.cap.js';
 export { type IMeshNetworkProvider, type MeshEndpoint, type MeshPeer, MeshPeerSchema, type MeshStatus, MeshStatusSchema, meshNetworkCapability, } from './mesh-network.cap.js';
 export { type IMotionProvider, MOTION_CLOSE_AFTER_MS, MOTION_SPAN_TIMEOUT_MS, type MotionOnMotionChangedData, MotionOnMotionChangedDataSchema, type MotionStatus, MotionStatusSchema, motionCapability, } from './motion.cap.js';
@@ -357,6 +358,7 @@ import type { logChannelsCapability } from './log-channels.cap.js';
 import type { logDestinationCapability } from './log-destination.cap.js';
 import type { loginMethodCapability } from './login-method.cap.js';
 import type { mediaPlayerCapability } from './media-player.cap.js';
+import type { meterCapability } from './meter.cap.js';
 import type { meshNetworkCapability } from './mesh-network.cap.js';
 import type { metricsProviderCapability } from './metrics-provider.cap.js';
 import type { modelConvertCapability } from './model-convert.cap.js';
@@ -441,6 +443,6 @@ import type { trainingProviderCapability } from './training-provider.cap.js';
 import type { zoneAnalyticsCapability } from './zone-analytics.cap.js';
 import type { zoneRulesCapability } from './zone-rules.cap.js';
 import type { zonesCapability } from './zones.cap.js';
-type AnyCapability = typeof streamSignalsCapability | typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageMigrationCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof storageOccupancyCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof databaseSnapshotCapability | typeof storageAdminCapability | typeof recordsCapability | typeof recordEntriesCapability | typeof deviceHistoryCapability | typeof keychainCapability | typeof keychainAdminCapability | typeof deviceCredentialsCapability | typeof nodeCertificatesCapability | typeof logChannelsCapability | typeof logDestinationCapability | typeof loadContributionCapability | typeof failureContributionCapability | typeof deviceRemovalHookCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceAdminLinkCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof calendarSourceCapability | typeof calendarsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof composerCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof navigationCapability | typeof consumablesCapability | typeof connectionTestCapability | typeof runningStateCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof trainingCapability | typeof trainingProviderCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof groupCommandsCapability | typeof groupStatusCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof heatingValveCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingArchiveCapability | typeof recordingExportCapability | typeof recordingSignalCapability | typeof deviceOpsCapability | typeof displayPaletteCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof oidcConnectionsCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof cameraGridLayoutCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof recordingOnboardCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof networkLinkCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability | typeof deviceExtensionCapability | typeof dishwasherCapability;
+type AnyCapability = typeof streamSignalsCapability | typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageMigrationCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof storageOccupancyCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof databaseSnapshotCapability | typeof storageAdminCapability | typeof recordsCapability | typeof recordEntriesCapability | typeof deviceHistoryCapability | typeof keychainCapability | typeof keychainAdminCapability | typeof deviceCredentialsCapability | typeof nodeCertificatesCapability | typeof logChannelsCapability | typeof logDestinationCapability | typeof loadContributionCapability | typeof failureContributionCapability | typeof deviceRemovalHookCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceAdminLinkCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof calendarSourceCapability | typeof calendarsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof composerCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof navigationCapability | typeof consumablesCapability | typeof connectionTestCapability | typeof runningStateCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof meterCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof trainingCapability | typeof trainingProviderCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof groupCommandsCapability | typeof groupStatusCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof heatingValveCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingArchiveCapability | typeof recordingExportCapability | typeof recordingSignalCapability | typeof deviceOpsCapability | typeof displayPaletteCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof oidcConnectionsCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof cameraGridLayoutCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof recordingOnboardCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof networkLinkCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability | typeof deviceExtensionCapability | typeof dishwasherCapability;
 export type CapabilityName = AnyCapability['name'];
 export type ITypedReadinessRegistry = IReadinessRegistry<CapabilityName>;

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+import { DeviceType } from '../device/device-type.js';
+/**
+ * A monotonic total between resets (D944). Energy uses `power-meter.kwhTotal`
+ * so dashboards keep one series; every other instantaneous reading lands here.
+ * `value` is the time integral in the source quantity's accumulated base
+ * (base-unit seconds, or kWh on the power meter). `null` is a gap, never zero.
+ */
+export declare const MeterStatusSchema: z.ZodObject<{
+    value: z.ZodNullable<z.ZodNumber>;
+    lastFetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type MeterStatus = z.infer<typeof MeterStatusSchema>;
+export declare const meterCapability: {
+    readonly name: 'meter';
+    readonly scope: 'device';
+    readonly deviceNative: true;
+    readonly mode: 'singleton';
+    readonly deviceTypes: readonly [DeviceType.Sensor];
+    readonly methods: {};
+    readonly status: {
+        readonly schema: z.ZodObject<{
+            value: z.ZodNullable<z.ZodNumber>;
+            lastFetchedAt: z.ZodNumber;
+        }, z.core.$strip>;
+        readonly kind: 'push';
+    };
+    readonly runtimeState: z.ZodObject<{
+        value: z.ZodNullable<z.ZodNumber>;
+        lastFetchedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    /**
+     * Runtime-state durability: **restored** — the total is a cache of the
+     * history integral. A restart shows it only until the history pass
+     * recomputes the open period; it is not an in-memory buffer.
+     *
+     * See `RuntimeStateDurability`. Enforced by
+     * `scripts/check-runtime-state-durability.ts`.
+     */
+    readonly durability: 'restored';
+    readonly history: {
+        readonly fields: {
+            readonly value: {
+                readonly kind: 'counter';
+                readonly deadband: 0.001;
+                readonly minIntervalMs: 60000;
+            };
+        };
+    };
+    readonly volatileStateFields: readonly ["lastFetchedAt"];
+};
+export type IMeterProvider = InferProvider<typeof meterCapability>;

package/dist/client.js

@@ -26886,6 +26886,7 @@ function createDeviceProxy(api, binding, opts) {
 		playMedia: (input) => dispatch("media-player", "mediaPlayer", "playMedia", "mutation", input),
 		getStatus: (input) => dispatch("media-player", "mediaPlayer", "getStatus", "query", input)
 	};
+	const meterInterface = { getStatus: (input) => dispatch("meter", "meter", "getStatus", "query", input) };
 	const motionInterface = {
 		isDetected: (input) => dispatch("motion", "motion", "isDetected", "query", input),
 		getStatus: (input) => dispatch("motion", "motion", "getStatus", "query", input)
@@ -27401,6 +27402,7 @@ function createDeviceProxy(api, binding, opts) {
 			lawnMowerControl: createSliceHandle(stateSource, binding.deviceId, "lawn-mower-control"),
 			lockControl: createSliceHandle(stateSource, binding.deviceId, "lock-control"),
 			mediaPlayer: createSliceHandle(stateSource, binding.deviceId, "media-player"),
+			meter: createSliceHandle(stateSource, binding.deviceId, "meter"),
 			motion: createSliceHandle(stateSource, binding.deviceId, "motion"),
 			motionTrigger: createSliceHandle(stateSource, binding.deviceId, "motion-trigger"),
 			motionZones: createSliceHandle(stateSource, binding.deviceId, "motion-zones"),
@@ -27486,6 +27488,7 @@ function createDeviceProxy(api, binding, opts) {
 		...bound("lawn-mower-control") ? { lawnMowerControl: lawnMowerControlInterface } : {},
 		...bound("lock-control") ? { lockControl: lockControlInterface } : {},
 		...bound("media-player") ? { mediaPlayer: mediaPlayerInterface } : {},
+		...bound("meter") ? { meter: meterInterface } : {},
 		...bound("motion") ? { motion: motionInterface } : {},
 		...bound("motion-detection") ? { motionDetection: motionDetectionInterface } : {},
 		...bound("motion-trigger") ? { motionTrigger: motionTriggerInterface } : {},

package/dist/client.mjs

@@ -26885,6 +26885,7 @@ function createDeviceProxy(api, binding, opts) {
 		playMedia: (input) => dispatch("media-player", "mediaPlayer", "playMedia", "mutation", input),
 		getStatus: (input) => dispatch("media-player", "mediaPlayer", "getStatus", "query", input)
 	};
+	const meterInterface = { getStatus: (input) => dispatch("meter", "meter", "getStatus", "query", input) };
 	const motionInterface = {
 		isDetected: (input) => dispatch("motion", "motion", "isDetected", "query", input),
 		getStatus: (input) => dispatch("motion", "motion", "getStatus", "query", input)
@@ -27400,6 +27401,7 @@ function createDeviceProxy(api, binding, opts) {
 			lawnMowerControl: createSliceHandle(stateSource, binding.deviceId, "lawn-mower-control"),
 			lockControl: createSliceHandle(stateSource, binding.deviceId, "lock-control"),
 			mediaPlayer: createSliceHandle(stateSource, binding.deviceId, "media-player"),
+			meter: createSliceHandle(stateSource, binding.deviceId, "meter"),
 			motion: createSliceHandle(stateSource, binding.deviceId, "motion"),
 			motionTrigger: createSliceHandle(stateSource, binding.deviceId, "motion-trigger"),
 			motionZones: createSliceHandle(stateSource, binding.deviceId, "motion-zones"),
@@ -27485,6 +27487,7 @@ function createDeviceProxy(api, binding, opts) {
 		...bound("lawn-mower-control") ? { lawnMowerControl: lawnMowerControlInterface } : {},
 		...bound("lock-control") ? { lockControl: lockControlInterface } : {},
 		...bound("media-player") ? { mediaPlayer: mediaPlayerInterface } : {},
+		...bound("meter") ? { meter: meterInterface } : {},
 		...bound("motion") ? { motion: motionInterface } : {},
 		...bound("motion-detection") ? { motionDetection: motionDetectionInterface } : {},
 		...bound("motion-trigger") ? { motionTrigger: motionTriggerInterface } : {},

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

@@ -21,6 +21,7 @@ export declare const CompositionProblemCodeSchema: z.ZodEnum<{
     "not-item-array": "not-item-array";
     "not-replaceable": "not-replaceable";
     "reserved-variant": "reserved-variant";
+    retention: "retention";
     "source-capability-missing": "source-capability-missing";
     "source-field-unknown": "source-field-unknown";
     "source-missing": "source-missing";
@@ -52,6 +53,7 @@ export declare const CompositionProblemSchema: z.ZodObject<{
         "not-item-array": "not-item-array";
         "not-replaceable": "not-replaceable";
         "reserved-variant": "reserved-variant";
+        retention: "retention";
         "source-capability-missing": "source-capability-missing";
         "source-field-unknown": "source-field-unknown";
         "source-missing": "source-missing";
@@ -192,6 +194,27 @@ export declare const CompositionFieldPlanSchema: z.ZodObject<{
             offline: "offline";
             omit: "omit";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"series">;
+        read: 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">;
     reads: z.ZodArray<z.ZodObject<{
         source: z.ZodObject<{
@@ -249,6 +272,7 @@ export declare const CompositionValidationSchema: z.ZodObject<{
             "not-item-array": "not-item-array";
             "not-replaceable": "not-replaceable";
             "reserved-variant": "reserved-variant";
+            retention: "retention";
             "source-capability-missing": "source-capability-missing";
             "source-field-unknown": "source-field-unknown";
             "source-missing": "source-missing";
@@ -348,6 +372,27 @@ export declare const CompositionValidationSchema: z.ZodObject<{
                 offline: "offline";
                 omit: "omit";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"series">;
+            read: 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">;
         reads: z.ZodArray<z.ZodObject<{
             source: z.ZodObject<{

package/dist/composition/composition.d.ts

@@ -141,6 +141,33 @@ export declare const CompositionAggregateSourceSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type CompositionAggregateSource = z.infer<typeof CompositionAggregateSourceSchema>;
+/**
+ * `series`: a statistics or integral field. The composer writes it from a
+ * history query. The live pass does not recompute it (D944).
+ */
+export declare const CompositionSeriesSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"series">;
+    read: 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 CompositionSeriesSource = z.infer<typeof CompositionSeriesSourceSchema>;
 export declare const CompositionFieldSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     source: z.ZodObject<{
         addonId: z.ZodString;
@@ -197,6 +224,27 @@ export declare const CompositionFieldSourceSchema: z.ZodDiscriminatedUnion<[z.Zo
         offline: "offline";
         omit: "omit";
     }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"series">;
+    read: 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`. */
@@ -291,6 +339,27 @@ export declare const CompositionItemEntrySchema: z.ZodObject<{
             offline: "offline";
             omit: "omit";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"series">;
+        read: 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>;
@@ -354,6 +423,27 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
             offline: "offline";
             omit: "omit";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"series">;
+        read: 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;
@@ -413,6 +503,27 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
                 offline: "offline";
                 omit: "omit";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"series">;
+            read: 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<{
@@ -500,6 +611,27 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             offline: "offline";
             omit: "omit";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"series">;
+        read: 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;
@@ -559,6 +691,27 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
                 offline: "offline";
                 omit: "omit";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"series">;
+            read: 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<{
@@ -688,6 +841,27 @@ export declare const CompositionSchema: z.ZodObject<{
                 offline: "offline";
                 omit: "omit";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"series">;
+            read: 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;
@@ -747,6 +921,27 @@ export declare const CompositionSchema: z.ZodObject<{
                     offline: "offline";
                     omit: "omit";
                 }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"series">;
+                read: 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<{
@@ -770,25 +965,7 @@ 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>;
-        active: z.ZodOptional<typeof import("./index.js").ActiveCriterionSchema>;
-    }, z.core.$strip>, z.ZodObject<{
-        kind: z.ZodLiteral<'appliance'>;
-        templateId: z.ZodLiteral<typeof import("./index.js").APPLIANCE_TEMPLATE_ID>;
-        appliance: z.ZodEnum<{
-            washer: 'washer';
-            dryer: 'dryer';
-            dishwasher: 'dishwasher';
-        }>;
-        thresholdWatts: z.ZodNumber;
-        startDwellMs: z.ZodNumber;
-        stopDwellMs: z.ZodNumber;
-        member: typeof import("./index.js").HelperMemberSchema;
-    }, z.core.$strip>], "kind">>;
+    helper: z.ZodOptional<z.ZodType<import("./index.js").HelperSpec, unknown, z.core.$ZodTypeInternals<import("./index.js").HelperSpec, unknown>>>;
 }, z.core.$strip>;
 export type Composition = z.infer<typeof CompositionSchema>;
 export declare function compositionSourceKey(ref: CompositionSourceRef): string;

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

@@ -0,0 +1,13 @@
+import type { CompositionProblem } from '../composition-report.js';
+import type { SeriesKind } from './history-math.js';
+import { type HistoryRetention } from './history-window.js';
+import type { HelperMember, IntegralHelperSpec, StatisticHelperSpec } from './spec.js';
+export declare function declaredSeriesKind(member: HelperMember): SeriesKind | 'enum' | null;
+export declare function statisticDraft(spec: StatisticHelperSpec, retention?: HistoryRetention): {
+    readonly draft: unknown;
+    readonly problems: readonly CompositionProblem[];
+};
+export declare function integralDraft(spec: IntegralHelperSpec, retention?: HistoryRetention): {
+    readonly draft: unknown;
+    readonly problems: readonly CompositionProblem[];
+};

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

@@ -5,6 +5,7 @@
 import { DeviceType } from '../../device/device-type.js';
 import { type Composition } from '../composition.js';
 import type { CompositionProblem } from '../composition-report.js';
+import { type HistoryRetention } from './history-window.js';
 import { type HelperSpec } from './spec.js';
 export interface HelperCompiled {
     readonly ok: true;
@@ -16,7 +17,7 @@ export interface HelperRefused {
 }
 export type HelperCompileResult = HelperCompiled | HelperRefused;
 /** Compile a helper template to a new-device composition. Refusals are named. */
-export declare function compileHelper(spec: HelperSpec): HelperCompileResult;
+export declare function compileHelper(spec: HelperSpec, retention?: HistoryRetention): 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/energy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Watts integrated over time, in kWh (D944).
+ *
+ * 1 kWh = 1 000 W × 3 600 000 ms. The history energy series uses the same
+ * factor (`tw_sum / 3.6e9`), so a chart and an integral helper cannot diverge.
+ */
+export declare const KWH_PER_WATT_MS: number;
+export declare function wattMillisecondsToKwh(wattMilliseconds: number): number;

package/dist/composition/helpers/history-math.d.ts

@@ -0,0 +1,39 @@
+import type { HistoryTier } from './history-window.js';
+export declare const STATISTIC_STATS: readonly ['min', 'max', 'mean', 'sum', 'count', 'change'];
+export type StatisticStat = (typeof STATISTIC_STATS)[number];
+export declare const SERIES_KINDS: readonly ['gauge', 'counter', 'boolean'];
+export type SeriesKind = (typeof SERIES_KINDS)[number];
+export interface SeriesPoint {
+    readonly t: number;
+    readonly value: number | null;
+    readonly twMean: number | null;
+    readonly twMs: number | null;
+    readonly min: number | null;
+    readonly max: number | null;
+    readonly last: number | null;
+    readonly delta: number | null;
+}
+export interface SeriesBefore {
+    readonly t: number;
+    readonly value: number | null;
+}
+export interface SeriesRead {
+    readonly kind: SeriesKind;
+    readonly tier: HistoryTier;
+    readonly from: number;
+    readonly to: number;
+    readonly before: SeriesBefore | null;
+    readonly points: readonly SeriesPoint[];
+    readonly truncated: boolean;
+}
+export interface HistoryValue {
+    /** `hold` keeps the last published number. `null` is a known gap (D393). */
+    readonly write: 'number' | 'null' | 'hold';
+    readonly value: number | null;
+    readonly included: number;
+    readonly excluded: number;
+    readonly reason: string | null;
+}
+export declare function evaluateStatistic(stat: StatisticStat, read: SeriesRead): HistoryValue;
+export type IntegralScale = 'energy-kwh' | 'per-second';
+export declare function integrateReading(read: SeriesRead, scale: IntegralScale): HistoryValue;