@camstack/types 1.2.406 → 1.2.407

package/dist/capabilities/running-state.cap.d.ts

@@ -14,7 +14,7 @@ export declare const RunningStateStatusSchema: z.ZodObject<{
         native: "native";
     }>;
     phase: z.ZodNullable<z.ZodString>;
-    lastFetchedAt: z.ZodNumber;
+    lastFetchedAt: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type RunningStateStatus = z.infer<typeof RunningStateStatusSchema>;
 export declare const runningStateCapability: {
@@ -22,7 +22,7 @@ export declare const runningStateCapability: {
     readonly scope: 'device';
     readonly deviceNative: true;
     readonly mode: 'singleton';
-    readonly deviceTypes: DeviceType[];
+    readonly deviceTypes: readonly DeviceType[];
     readonly methods: {};
     readonly events: {
         readonly onStarted: {
@@ -49,7 +49,7 @@ export declare const runningStateCapability: {
                 native: "native";
             }>;
             phase: z.ZodNullable<z.ZodString>;
-            lastFetchedAt: z.ZodNumber;
+            lastFetchedAt: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>;
         readonly kind: 'push';
     };
@@ -61,7 +61,7 @@ export declare const runningStateCapability: {
             native: "native";
         }>;
         phase: z.ZodNullable<z.ZodString>;
-        lastFetchedAt: z.ZodNumber;
+        lastFetchedAt: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strip>;
     readonly durability: 'restored';
     readonly history: {
@@ -72,5 +72,69 @@ export declare const runningStateCapability: {
         };
     };
     readonly volatileStateFields: readonly ["lastFetchedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly targets: readonly [{
+            readonly id: 'running';
+            readonly cardinality: 'scalar';
+            readonly vocabulary: {
+                readonly cap: 'running-state';
+                readonly stateField: 'running';
+            };
+            readonly deviceTypes: readonly [DeviceType.Dishwasher, DeviceType.Vacuum, DeviceType.LawnMower, DeviceType.MediaPlayer, DeviceType.WaterHeater, DeviceType.Humidifier, DeviceType.Fan, DeviceType.Climate, DeviceType.Thermostat, DeviceType.PetFeeder];
+            readonly apply: 'add-or-replace';
+            readonly path: 'running';
+            readonly sources: readonly [{
+                readonly kind: 'switch';
+                readonly transforms: readonly [{
+                    readonly kind: 'identity';
+                }];
+            }, {
+                readonly kind: 'binary';
+                readonly transforms: readonly [{
+                    readonly kind: 'identity';
+                }, {
+                    readonly kind: 'invert';
+                }];
+            }, {
+                readonly kind: 'numeric';
+                readonly requiredUnit: 'W';
+                readonly transforms: readonly [{
+                    readonly kind: 'threshold';
+                    readonly comparison: 'gte';
+                    readonly defaultThreshold: 5;
+                    readonly defaultStartDwellMs: 30000;
+                    readonly defaultStopDwellMs: 180000;
+                    readonly thresholdUnit: 'W';
+                }];
+            }];
+            readonly companions: readonly [{
+                readonly kind: 'constant';
+                readonly path: 'source';
+                readonly value: 'assigned';
+                readonly when: 'always';
+            }, {
+                readonly kind: 'constant';
+                readonly path: 'phase';
+                readonly value: null;
+                readonly when: 'always';
+            }, {
+                readonly kind: 'clock';
+                readonly path: 'lastFetchedAt';
+                readonly when: 'always';
+            }, {
+                readonly kind: 'transition-time';
+                readonly path: 'since';
+                readonly sourceChangedAt: 'prefer';
+            }];
+            readonly sourceReport: {
+                readonly status: 'assignment-status';
+                readonly runtimeField: 'source';
+                readonly nativeValue: 'native';
+                readonly assignedValue: 'assigned';
+            };
+            readonly advancedExpression: true;
+        }];
+    };
 };
 export type IRunningStateProvider = InferProvider<typeof runningStateCapability>;

package/dist/catalogs/sensor-active-state.d.ts

@@ -5,7 +5,7 @@
  * ONE table for everyone who asks "is this device HIGH?": the
  * recorder's `RecordingTriggers.sensorDeviceIds` trigger, the post-analysis
  * sensor markers, the orchestrator's camera-sensors bridge and
- * the sources of a composite doorbell (`doorbellFeatureSources`, D671).
+ * the sources of a pulse (`compilePulseOverride`, D936).
  * A second copy would diverge at the first cap added, and the symptom — "the
  * sensor rings the doorbell but does not record" — is exactly D62.
  *

package/dist/client.js

@@ -909,7 +909,7 @@ zod.z.object({
 * ONE table for everyone who asks "is this device HIGH?": the
 * recorder's `RecordingTriggers.sensorDeviceIds` trigger, the post-analysis
 * sensor markers, the orchestrator's camera-sensors bridge and
-* the sources of a composite doorbell (`doorbellFeatureSources`, D671).
+* the sources of a pulse (`compilePulseOverride`, D936).
 * A second copy would diverge at the first cap added, and the symptom — "the
 * sensor rings the doorbell but does not record" — is exactly D62.
 *

package/dist/client.mjs

@@ -908,7 +908,7 @@ z.object({
 * ONE table for everyone who asks "is this device HIGH?": the
 * recorder's `RecordingTriggers.sensorDeviceIds` trigger, the post-analysis
 * sensor markers, the orchestrator's camera-sensors bridge and
-* the sources of a composite doorbell (`doorbellFeatureSources`, D671).
+* the sources of a pulse (`compilePulseOverride`, D936).
 * A second copy would diverge at the first cap added, and the symptom — "the
 * sensor rings the doorbell but does not record" — is exactly D62.
 *

package/dist/composition/customize/__fixtures__/refs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Source devices the generic compiler fixtures name. Not a new catalogue.
+ */
+import type { CompositionSourceRef } from '../../composition.js';
+export interface FixtureFieldRead {
+    readonly source: CompositionSourceRef;
+    readonly cap: string;
+    readonly fieldPath: string;
+    readonly valueKind: 'boolean' | 'number' | 'string';
+}
+export declare const FEEDER: CompositionSourceRef;
+export declare const BATTERY_NUMBER: FixtureFieldRead;
+export declare const DESICCANT_STRING: FixtureFieldRead;
+export declare const DISHWASHER: CompositionSourceRef;
+export declare const SWITCH_REF: CompositionSourceRef;
+export declare const CAMERA_615: CompositionSourceRef;
+export declare const DOORBELL_SWITCH: CompositionSourceRef;
+export declare const PIR_SENSOR: {
+    readonly addonId: 'provider-homeassistant';
+    readonly stableId: 'ha:pir';
+    readonly mode: 'in-addition';
+};
+export declare const GATE_SENSOR: {
+    readonly addonId: 'provider-zigbee';
+    readonly stableId: 'z:gate';
+    readonly mode: 'confirm';
+};

package/dist/composition/customize/__fixtures__/stored-cases.d.ts

@@ -0,0 +1,13 @@
+import type { ScalarCompileInput } from '../scalar-compile.js';
+import type { CustomizeStored } from '../stored.js';
+export interface CustomizeStoredCase {
+    readonly id: string;
+    readonly input: ScalarCompileInput;
+    readonly stored: CustomizeStored;
+}
+export declare const CUSTOMIZE_STORED_CASES: readonly CustomizeStoredCase[];
+export interface NoncanonicalCustomizeStored {
+    readonly id: string;
+    readonly stored: CustomizeStored;
+}
+export declare const NONCANONICAL_CUSTOMIZE_STORED: readonly NoncanonicalCustomizeStored[];

package/dist/composition/customize/event-compile.d.ts

@@ -0,0 +1,20 @@
+import type { CompositionFieldsFeature, CompositionSourceRef } from '../composition.js';
+import { type CameraSensorsConfig } from '../../pipeline/camera-sensors.js';
+import type { PulseOverrideDraft, SpanOverrideDraft } from './override-draft.js';
+import type { CustomizeRoundTrip } from './stored.js';
+export interface PulseCompileInput {
+    readonly draft: PulseOverrideDraft;
+    readonly device: CompositionSourceRef;
+    readonly changedAtFields: readonly string[];
+}
+export interface SpanCompiled {
+    readonly config: CameraSensorsConfig | null;
+    readonly timeoutMs: number;
+    readonly cooldownMs: number | undefined;
+}
+export interface SpanCompileInput {
+    readonly draft: SpanOverrideDraft;
+    readonly device: CompositionSourceRef;
+}
+export declare function compilePulseOverride(input: PulseCompileInput): CustomizeRoundTrip<CompositionFieldsFeature>;
+export declare function compileSpanOverride(input: SpanCompileInput): CustomizeRoundTrip<SpanCompiled>;

package/dist/composition/customize/event-decode.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Recover a pulse draft only when compiling it again reproduces the stored
+ * feature. Anything else is another formula.
+ */
+import type { CompositionFieldsFeature, CompositionSourceRef } from '../composition.js';
+import type { PulseOverrideDraft } from './override-draft.js';
+export interface PulseDecoded {
+    readonly draft: PulseOverrideDraft;
+    readonly changedAtFields: readonly string[];
+}
+export interface PulseDecodeInput {
+    readonly feature: CompositionFieldsFeature;
+    readonly device: CompositionSourceRef;
+    readonly cap: string;
+    readonly targetId: string;
+    readonly timestampPath: string;
+    readonly counterPath: string;
+}
+export declare function decodePulseOverride(input: PulseDecodeInput): PulseDecoded | null;

package/dist/composition/customize/event-eval.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pulse and span edges for Customize preview (D936 §5.5).
+ *
+ * An unread sample is not a level. It does not arm, start, end or count
+ * (D49): a failed read must not look like a falling edge.
+ */
+export type LevelSample = {
+    readonly kind: 'unread';
+} | {
+    readonly kind: 'level';
+    readonly active: boolean;
+    readonly changedAt: number | null;
+};
+export interface PulseState {
+    readonly priorActive: boolean | undefined;
+    readonly lastPressedAt: number | null;
+    readonly count: number;
+    readonly acceptedAt: number | null;
+}
+export interface SpanState {
+    readonly open: boolean;
+    readonly startedAt: number | null;
+    readonly endedAt: number | null;
+    readonly quietUntil: number | null;
+    readonly priorActive: boolean | undefined;
+}
+export interface SpanTiming {
+    readonly timeoutMs: number;
+    readonly cooldownMs: number;
+    readonly nowMs: number;
+}
+export declare const INITIAL_PULSE: PulseState;
+export declare const INITIAL_SPAN: SpanState;
+export declare function stepPulse(state: PulseState, sample: LevelSample, debounceMs: number): PulseState;
+export declare function stepSpan(state: SpanState, sample: LevelSample, timing: SpanTiming): SpanState;

package/dist/composition/customize/event-status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Assignment status for a pulse feature and a span's camera-sensors
+ * authority (D936, D315, D49). Pending and unreadable are not an empty list.
+ */
+import type { CompositionFieldsFeature, CompositionSourceRef } from '../composition.js';
+import type { CameraSensorAttachment, CameraSensorMode, CameraSensorsStatus } from '../../pipeline/camera-sensors.js';
+import type { CustomizeAssignmentStatus } from './override-draft.js';
+import type { ScalarRead, ScalarSourcePresence } from './scalar-status.js';
+export interface PulseStatusInput {
+    readonly cap: string;
+    readonly targetId: string;
+    readonly device: CompositionSourceRef;
+    readonly timestampPath: string;
+    readonly counterPath: string;
+    readonly apply: 'add' | 'replace';
+    readonly stored: ScalarRead<CompositionFieldsFeature | null>;
+    readonly sourcePresence: ScalarSourcePresence;
+    readonly sourceUnknownReason: string | null;
+}
+export interface PulseAssignmentProjection {
+    readonly text: string;
+    readonly status: CustomizeAssignmentStatus;
+}
+export interface SpanSensorRow {
+    readonly key: string;
+    readonly addonId: string;
+    readonly stableId: string;
+    readonly name: string;
+    readonly mode: CameraSensorMode;
+    readonly state: CameraSensorAttachment['state'];
+    readonly reason: string | null;
+}
+export interface SpanAssignmentProjection {
+    readonly text: string;
+    readonly writable: boolean;
+    readonly rows: readonly SpanSensorRow[];
+    readonly status: CustomizeAssignmentStatus;
+}
+export type SpanRead = {
+    readonly kind: 'pending';
+} | {
+    readonly kind: 'unknown';
+    readonly reason: string | null;
+} | {
+    readonly kind: 'known';
+    readonly value: CameraSensorsStatus;
+};
+export declare function projectPulseAssignment(input: PulseStatusInput): PulseAssignmentProjection;
+export declare function projectSpanAssignment(targetId: string, stored: SpanRead): SpanAssignmentProjection;

package/dist/composition/customize/field-source.d.ts

@@ -0,0 +1,5 @@
+import type { CompositionExpressionSource, CompositionFieldSource, CompositionFromSource, CompositionSourceRef } from '../composition.js';
+export declare function fromRead(source: CompositionSourceRef, cap: string, fieldPath: string): CompositionFromSource;
+export declare function expression(expr: string, bindings: CompositionExpressionSource['bindings']): CompositionFieldSource;
+export declare function literal(expr: string): CompositionFieldSource;
+export declare function isLiteral(source: CompositionFieldSource | undefined, expr: string): boolean;

package/dist/composition/customize/keyed-array-compile.d.ts

@@ -0,0 +1,26 @@
+import { type CompositionFieldsFeature, type CompositionSourceRef } from '../composition.js';
+import type { KeyedArrayOverrideDraft } from './override-draft.js';
+import type { CustomizeRoundTrip } from './stored.js';
+export type KeyedSourceValueKind = 'boolean' | 'number' | 'string' | 'enum';
+export interface KeyedArrayLiteral {
+    readonly path: string;
+    readonly value: string;
+}
+export interface KeyedArrayItemCompile {
+    readonly draft: KeyedArrayOverrideDraft;
+    readonly sourceValueKind: KeyedSourceValueKind;
+    readonly sourceUnit: string | null;
+    readonly literals: readonly KeyedArrayLiteral[];
+}
+export interface KeyedArrayCompileInput {
+    readonly cap: string;
+    readonly targetId: string;
+    readonly device: CompositionSourceRef;
+    readonly apply: 'add' | 'replace';
+    readonly items: readonly KeyedArrayItemCompile[];
+}
+export declare function compileKeyedArrayOverride(input: KeyedArrayCompileInput): CustomizeRoundTrip<CompositionFieldsFeature>;
+/** Put one compiled item into an existing feature. Other items stay as stored. */
+export declare function mergeKeyedArrayItem(current: CompositionFieldsFeature | null, compiled: CompositionFieldsFeature, key: string): CompositionFieldsFeature | null;
+/** The feature without item `key`. Null when that item was the last one. */
+export declare function withoutKeyedArrayItem(feature: CompositionFieldsFeature, key: string): CompositionFieldsFeature | null;

package/dist/composition/customize/keyed-array-decode.d.ts

@@ -0,0 +1,20 @@
+import type { CompositionFieldsFeature, CompositionSourceRef } from '../composition.js';
+import { type KeyedArrayItemCompile } from './keyed-array-compile.js';
+export interface KeyedArrayItemView {
+    readonly key: string;
+    readonly label: string;
+    readonly recognized: boolean;
+    readonly compile: KeyedArrayItemCompile | null;
+}
+export interface KeyedArrayRead {
+    readonly canonical: boolean;
+    readonly apply: 'add' | 'replace';
+    readonly items: readonly KeyedArrayItemView[];
+}
+export declare function readKeyedArrayItems(feature: CompositionFieldsFeature, cap: string, targetId: string): KeyedArrayRead | null;
+export declare function decodeKeyedArrayOverride(input: {
+    readonly feature: CompositionFieldsFeature;
+    readonly device: CompositionSourceRef;
+    readonly cap: string;
+    readonly targetId: string;
+}): KeyedArrayRead | null;

package/dist/composition/customize/keyed-array-expr.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical expression text for one keyed-array transform. The decoder reads
+ * only this spelling.
+ */
+import type { CustomizeTransformDraft } from './override-draft.js';
+export declare function enumMapExpr(mapping: Readonly<Record<string, string | null>>): string | null;
+export declare function parseEnumMap(expr: string): Readonly<Record<string, string | null>> | null;
+export declare function enumMapDraft(mapping: Readonly<Record<string, string | null>>): Extract<CustomizeTransformDraft, {
+    kind: 'enum-map';
+}>;

package/dist/composition/customize/keyed-array-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Assignment-status projection for one keyed-array target (D936). Pending and
+ * unknown are unanswered reads. A confirmed-gone source leaves an added array
+ * assigned: the native rows are a different authority.
+ */
+import type { CompositionFieldsFeature, CompositionSourceRef } from '../composition.js';
+import type { CustomizeAssignmentStatus } from './override-draft.js';
+import type { ScalarRead, ScalarSourcePresence } from './scalar-status.js';
+export interface KeyedArrayStatusInput {
+    readonly cap: string;
+    readonly targetId: string;
+    readonly device: CompositionSourceRef;
+    readonly stored: ScalarRead<CompositionFieldsFeature | null>;
+    readonly sourcePresence: ScalarSourcePresence;
+    readonly sourceUnknownReason: string | null;
+}
+export interface KeyedArrayAssignmentProjection {
+    readonly text: string;
+    readonly assignedCount: number;
+    readonly status: CustomizeAssignmentStatus;
+}
+export declare function projectKeyedArrayAssignment(input: KeyedArrayStatusInput): KeyedArrayAssignmentProjection;

package/dist/composition/customize/normalize.d.ts

@@ -0,0 +1,4 @@
+import type { CustomizeStored } from './stored.js';
+/** Key order is not part of the stored contract. Array order is. */
+export declare function normalizeStored(stored: CustomizeStored): unknown;
+export declare function sameStored(a: CustomizeStored, b: CustomizeStored): boolean;