@camstack/types 1.2.421 → 1.2.423

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;

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

@@ -0,0 +1,71 @@
+/**
+ * The range a statistics or integral helper asks history for (D944).
+ *
+ * Calendar edges are the hub's timezone, never UTC midnight: a day is 23, 24
+ * or 25 hours across a DST change. A tier is eligible only when its retention
+ * is strictly longer than the longest that range can be. Forever qualifies.
+ * Equal to a tier's retention is a refusal, not a short answer.
+ */
+import { z } from 'zod';
+export declare const MINUTE_MS: number;
+export declare const HOUR_MS: number;
+export declare const DAY_MS: number;
+export declare const ROLLING_SPANS: readonly ['1h', '24h', '2d', '7d', '30d', 'custom'];
+export type RollingSpan = (typeof ROLLING_SPANS)[number];
+export declare const CALENDAR_PERIODS: readonly ['today', 'yesterday', 'this-week', 'this-month'];
+export type CalendarPeriod = (typeof CALENDAR_PERIODS)[number];
+export declare const HISTORY_TIERS: readonly ['raw', '5m', '1h', '1d'];
+export type HistoryTier = (typeof HISTORY_TIERS)[number];
+export declare const RESET_PERIODS: readonly ['never', 'daily', 'weekly', 'monthly'];
+export type ResetPeriod = (typeof RESET_PERIODS)[number];
+export declare const MIN_CUSTOM_MINUTES: number;
+/** Faster than this is not a history query. Rolling windows at most this often. */
+export declare const HISTORY_FAST_MS: number;
+export declare const HISTORY_SLOW_MS: number;
+export interface HistoryRetention {
+    readonly rawMs: number;
+    readonly fiveMinuteMs: number;
+    readonly hourMs: number;
+    /** `null` keeps the daily tier forever. */
+    readonly dayMs: number | null;
+}
+/** The device-history defaults: raw 7 d, 5 m 30 d, 1 h 365 d, 1 d forever. */
+export declare const DEFAULT_HISTORY_RETENTION: HistoryRetention;
+export type RollingWindow = {
+    readonly kind: 'rolling';
+    readonly span: RollingSpan;
+    readonly customMinutes?: number;
+};
+export declare const RollingWindowSchema: z.ZodType<RollingWindow>;
+export type CalendarWindow = {
+    readonly kind: 'calendar';
+    readonly period: CalendarPeriod;
+};
+export declare const CalendarWindowSchema: z.ZodType<CalendarWindow>;
+export type StatisticWindow = RollingWindow | CalendarWindow;
+export declare const StatisticWindowSchema: z.ZodType<StatisticWindow>;
+export interface OpenRange {
+    readonly from: number;
+    readonly to: number;
+}
+export interface HistoryTierReady {
+    readonly ok: true;
+    readonly tier: HistoryTier;
+    readonly maxDurationMs: number;
+}
+export interface HistoryTierRefused {
+    readonly ok: false;
+    readonly reason: string;
+}
+export type HistoryTierPlan = HistoryTierReady | HistoryTierRefused;
+export declare function rollingDurationMs(window: RollingWindow): number | null;
+/** Longest the window can be. Calendar periods use their full length, not the elapsed part. */
+export declare function maxDurationMs(window: StatisticWindow): number | null;
+export declare function planStatisticTier(window: StatisticWindow, retention: HistoryRetention): HistoryTierPlan;
+export declare function planResetTier(reset: ResetPeriod, retention: HistoryRetention): HistoryTierPlan;
+export declare function openStatistic(window: StatisticWindow, now: number, timeZone: string): OpenRange | null;
+export declare function openReset(reset: ResetPeriod, now: number, timeZone: string): OpenRange | null;
+/** The next hub-local midnight, strictly after `now`. Monday is one of these. */
+export declare function nextLocalMidnight(now: number, timeZone: string): number | null;
+export declare function statisticCadenceMs(window: StatisticWindow): number;
+export declare function integralCadenceMs(tier: HistoryTier): number;

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

@@ -3,6 +3,10 @@ export { type AggregateCounts, type AggregateEmpty, type AggregateOutcome, type
 export { APPLIANCE_DEFAULTS, APPLIANCE_KINDS, APPLIANCE_TEMPLATE_ID, type ApplianceDefaults, type ApplianceKind, applianceDeviceType, isApplianceKind, sourcePickForAppliance, } from './appliance.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 { declaredSeriesKind, integralDraft, statisticDraft } from './compile-history.js';
+export { KWH_PER_WATT_MS, wattMillisecondsToKwh } from './energy.js';
+export { type HistoryValue, type IntegralScale, type SeriesBefore, type SeriesKind, type SeriesPoint, type SeriesRead, STATISTIC_STATS, SERIES_KINDS, evaluateStatistic, integrateReading, } from './history-math.js';
+export { type CalendarPeriod, type CalendarWindow, type HistoryRetention, type HistoryTier, type HistoryTierPlan, type OpenRange, type ResetPeriod, type RollingSpan, type RollingWindow, type StatisticWindow, CALENDAR_PERIODS, CalendarWindowSchema, DAY_MS, DEFAULT_HISTORY_RETENTION, HISTORY_FAST_MS, HISTORY_SLOW_MS, HISTORY_TIERS, HOUR_MS, MINUTE_MS, MIN_CUSTOM_MINUTES, RESET_PERIODS, ROLLING_SPANS, RollingWindowSchema, StatisticWindowSchema, integralCadenceMs, maxDurationMs, nextLocalMidnight, openReset, openStatistic, planResetTier, planStatisticTier, rollingDurationMs, statisticCadenceMs, } from './history-window.js';
 export { type HelperMemberFact, helperSaveProblems, } from './save.js';
-export { type SourcePick, type SourcePickAccept, type SourcePickHistory, type SourcePickRequest, sourcePickForTemplate, } from './source-pick.js';
-export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ApplianceHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, NUMERIC_AGGREGATES, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ApplianceHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type NumericAggregate, } from './spec.js';
+export { type SourcePick, type SourcePickAccept, type SourcePickHistory, type SourcePickRequest, sourcePickForHistory, sourcePickForTemplate, } from './source-pick.js';
+export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ApplianceHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, INTEGRAL_OUTPUTS, IntegralHelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, NUMERIC_AGGREGATES, StatisticHelperSpecSchema, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ApplianceHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type IntegralHelperSpec, type IntegralOutput, type NumericAggregate, type StatisticHelperSpec, type StatisticStat, } from './spec.js';

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

@@ -38,3 +38,5 @@ export interface SourcePick {
 }
 /** What the member step asks the selector for this template. */
 export declare function sourcePickForTemplate(template: GroupTemplate): SourcePickRequest;
+/** A statistic or integral reads one field that declares history. */
+export declare function sourcePickForHistory(kind: 'statistic' | 'integral'): SourcePickRequest;

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

@@ -4,6 +4,8 @@
  */
 import { z } from 'zod';
 import { APPLIANCE_TEMPLATE_ID } from './appliance.js';
+import { STATISTIC_STATS } from './history-math.js';
+import { type ResetPeriod, type StatisticWindow } from './history-window.js';
 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;
@@ -28,10 +30,7 @@ export declare const HelperMemberSchema: z.ZodObject<{
     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.
- */
+/** A group, a statistic, or an integral (D944). The composer runs all three. */
 export declare const GroupHelperSpecSchema: z.ZodObject<{
     kind: z.ZodLiteral<'group'>;
     templateId: typeof GroupTemplateIdSchema;
@@ -54,10 +53,24 @@ export declare const ApplianceHelperSpecSchema: z.ZodObject<{
     member: typeof HelperMemberSchema;
 }>;
 export type ApplianceHelperSpec = z.infer<typeof ApplianceHelperSpecSchema>;
-export declare const HelperSpecSchema: z.ZodDiscriminatedUnion<[
-    typeof GroupHelperSpecSchema,
-    typeof ApplianceHelperSpecSchema
-], 'kind'>;
-export type HelperSpec = z.infer<typeof HelperSpecSchema>;
-/** Every member a helper reads. An appliance has one. */
+export type StatisticStat = (typeof STATISTIC_STATS)[number];
+export type StatisticHelperSpec = {
+    readonly kind: 'statistic';
+    readonly stat: StatisticStat;
+    readonly window: StatisticWindow;
+    readonly source: HelperMember;
+};
+export declare const StatisticHelperSpecSchema: z.ZodType<StatisticHelperSpec>;
+export declare const INTEGRAL_OUTPUTS: readonly ['energy', 'meter'];
+export type IntegralOutput = (typeof INTEGRAL_OUTPUTS)[number];
+export type IntegralHelperSpec = {
+    readonly kind: 'integral';
+    readonly reset: ResetPeriod;
+    readonly output: IntegralOutput;
+    readonly source: HelperMember;
+};
+export declare const IntegralHelperSpecSchema: z.ZodType<IntegralHelperSpec>;
+export type HelperSpec = GroupHelperSpec | ApplianceHelperSpec | StatisticHelperSpec | IntegralHelperSpec;
+export declare const HelperSpecSchema: z.ZodType<HelperSpec>;
+/** Every member a helper reads. A group has many; the others have one. */
 export declare function helperMembers(spec: HelperSpec): readonly HelperMember[];