@camstack/addon-training 0.1.108 → 0.1.109

package/dist/{dist-B8XLeyRL.js → dist-BkNG49yZ.js}

@@ -15885,6 +15885,478 @@ object({
 		path: ["expr"]
 	});
 });
+/**
+* Identity envelope for a device's upstream-system metadata.
+*
+* Two jobs:
+*
+*   1. **Dispatch key.** `id` is the natural identifier the SOURCE system
+*      uses to address this device (HA `entity_id`, Reolink MAC, ONVIF
+*      WS-Discovery endpoint UUID, …). Provider code keeps a
+*      `Map<sourceInfo.id, IDevice>` to route inbound push events in O(1)
+*      without round-tripping through `stableId` / `id` mappings.
+*
+*   2. **Stability bridge.** `uniqueId` is the *immutable* upstream id when
+*      one exists (HA `entity.unique_id`, Reolink MAC again — same as `id`
+*      for vendors where MAC is the natural key). For systems where the
+*      live dispatch key can be renamed (HA `entity_id` can be edited),
+*      providers detect renames by matching `uniqueId` and patch `id`
+*      in-place so dispatch keeps working.
+*
+* **Display unit and precision are NOT stored here.** They are a read-time
+* preference (D944). A polymorphic reading stores its `quantity` here once,
+* at adopt, and a date/time value stores `dateTimeShape` the same way —
+* neither is repeated on each sample. The `device_class` tag is an
+* HA-specific input consumed at the discovery boundary (`ha-domain-mapping`)
+* to derive the CamStack `DeviceRole`; it is never stored after that point.
+*
+* The `raw` escape hatch carries provider-specific attributes that don't
+* fit the structured slots (HA `attributes` whitelist, Reolink `deviceCache`
+* details, …). Providers control what lands here.
+*/
+var SourceInfoSchema = object({
+	/** Live dispatch key — mutable when the source system allows rename. */
+	id: string(),
+	/** Source system tag — e.g. 'homeassistant' | 'reolink' | 'onvif'. */
+	system: string(),
+	/** Immutable upstream identifier when available (HA `unique_id`, … ).
+	*  Used to detect rename when `id` changes. */
+	uniqueId: string().optional(),
+	/** Quantity of a polymorphic reading, written once at adopt (D944). */
+	quantity: ReadingQuantitySchema.optional(),
+	/** Date / time / datetime shape of a string reading, written once at adopt. */
+	dateTimeShape: _enum([
+		"date",
+		"time",
+		"datetime"
+	]).optional(),
+	/** Provider-specific extras that don't fit the structured slots.
+	*  Whitelist what goes here per provider — do NOT dump entire HA
+	*  attribute blobs (would explode the meta JSON column). */
+	raw: record(string(), unknown()).optional()
+});
+/**
+* Frozen unit → spec table. `•` in the doc marks each dimension's canonical
+* unit (`factor: 1, offset: 0`). °F derives from `°C = (°F − 32) × 5/9` ⇒
+* `factor = 5/9`, `offset = -160/9` (kept as exact expressions, not rounded
+* decimals). K derives from `°C = K − 273.15`.
+*/
+var UNIT_TABLE = {
+	"°C": {
+		dimension: "temperature",
+		factor: 1,
+		offset: 0
+	},
+	"°F": {
+		dimension: "temperature",
+		factor: 5 / 9,
+		offset: -160 / 9
+	},
+	K: {
+		dimension: "temperature",
+		factor: 1,
+		offset: -273.15
+	},
+	hPa: {
+		dimension: "pressure",
+		factor: 1,
+		offset: 0
+	},
+	kPa: {
+		dimension: "pressure",
+		factor: 10,
+		offset: 0
+	},
+	Pa: {
+		dimension: "pressure",
+		factor: .01,
+		offset: 0
+	},
+	mbar: {
+		dimension: "pressure",
+		factor: 1,
+		offset: 0
+	},
+	bar: {
+		dimension: "pressure",
+		factor: 1e3,
+		offset: 0
+	},
+	inHg: {
+		dimension: "pressure",
+		factor: 33.8639,
+		offset: 0
+	},
+	mmHg: {
+		dimension: "pressure",
+		factor: 1.33322,
+		offset: 0
+	},
+	psi: {
+		dimension: "pressure",
+		factor: 68.9476,
+		offset: 0
+	},
+	"m/s": {
+		dimension: "speed",
+		factor: 1,
+		offset: 0
+	},
+	"km/h": {
+		dimension: "speed",
+		factor: 1 / 3.6,
+		offset: 0
+	},
+	mph: {
+		dimension: "speed",
+		factor: .44704,
+		offset: 0
+	},
+	kn: {
+		dimension: "speed",
+		factor: .514444,
+		offset: 0
+	},
+	"mm/h": {
+		dimension: "precipitation-rate",
+		factor: 1,
+		offset: 0
+	},
+	"in/h": {
+		dimension: "precipitation-rate",
+		factor: 25.4,
+		offset: 0
+	},
+	m: {
+		dimension: "length",
+		factor: 1,
+		offset: 0
+	},
+	mm: {
+		dimension: "length",
+		factor: .001,
+		offset: 0
+	},
+	cm: {
+		dimension: "length",
+		factor: .01,
+		offset: 0
+	},
+	km: {
+		dimension: "length",
+		factor: 1e3,
+		offset: 0
+	},
+	in: {
+		dimension: "length",
+		factor: .0254,
+		offset: 0
+	},
+	ft: {
+		dimension: "length",
+		factor: .3048,
+		offset: 0
+	},
+	mi: {
+		dimension: "length",
+		factor: 1609.344,
+		offset: 0
+	},
+	"m²": {
+		dimension: "area",
+		factor: 1,
+		offset: 0
+	},
+	lx: {
+		dimension: "illuminance",
+		factor: 1,
+		offset: 0
+	},
+	"W/m²": {
+		dimension: "irradiance",
+		factor: 1,
+		offset: 0
+	},
+	W: {
+		dimension: "power",
+		factor: 1,
+		offset: 0
+	},
+	kW: {
+		dimension: "power",
+		factor: 1e3,
+		offset: 0
+	},
+	VA: {
+		dimension: "apparent-power",
+		factor: 1,
+		offset: 0
+	},
+	Wh: {
+		dimension: "energy",
+		factor: 1,
+		offset: 0
+	},
+	kWh: {
+		dimension: "energy",
+		factor: 1e3,
+		offset: 0
+	},
+	MWh: {
+		dimension: "energy",
+		factor: 1e6,
+		offset: 0
+	},
+	V: {
+		dimension: "voltage",
+		factor: 1,
+		offset: 0
+	},
+	mV: {
+		dimension: "voltage",
+		factor: .001,
+		offset: 0
+	},
+	A: {
+		dimension: "current",
+		factor: 1,
+		offset: 0
+	},
+	mA: {
+		dimension: "current",
+		factor: .001,
+		offset: 0
+	},
+	ppm: {
+		dimension: "concentration-volume",
+		factor: 1,
+		offset: 0
+	},
+	ppb: {
+		dimension: "concentration-volume",
+		factor: .001,
+		offset: 0
+	},
+	"µg/m³": {
+		dimension: "concentration-mass",
+		factor: 1,
+		offset: 0
+	},
+	"mg/m³": {
+		dimension: "concentration-mass",
+		factor: 1e3,
+		offset: 0
+	},
+	kg: {
+		dimension: "mass",
+		factor: 1,
+		offset: 0
+	},
+	g: {
+		dimension: "mass",
+		factor: .001,
+		offset: 0
+	},
+	lb: {
+		dimension: "mass",
+		factor: .453592,
+		offset: 0
+	},
+	oz: {
+		dimension: "mass",
+		factor: .0283495,
+		offset: 0
+	},
+	"%": {
+		dimension: "percentage",
+		factor: 1,
+		offset: 0
+	},
+	L: {
+		dimension: "volume",
+		factor: 1,
+		offset: 0
+	},
+	mL: {
+		dimension: "volume",
+		factor: .001,
+		offset: 0
+	},
+	gal: {
+		dimension: "volume",
+		factor: 3.785411784,
+		offset: 0
+	},
+	s: {
+		dimension: "duration",
+		factor: 1,
+		offset: 0
+	},
+	ms: {
+		dimension: "duration",
+		factor: .001,
+		offset: 0
+	},
+	min: {
+		dimension: "duration",
+		factor: 60,
+		offset: 0
+	},
+	h: {
+		dimension: "duration",
+		factor: 3600,
+		offset: 0
+	},
+	d: {
+		dimension: "duration",
+		factor: 86400,
+		offset: 0
+	},
+	B: {
+		dimension: "information",
+		factor: 1,
+		offset: 0
+	},
+	KiB: {
+		dimension: "information",
+		factor: 1024,
+		offset: 0
+	},
+	MiB: {
+		dimension: "information",
+		factor: 1024 ** 2,
+		offset: 0
+	},
+	GiB: {
+		dimension: "information",
+		factor: 1024 ** 3,
+		offset: 0
+	},
+	TiB: {
+		dimension: "information",
+		factor: 1024 ** 4,
+		offset: 0
+	},
+	kB: {
+		dimension: "information",
+		factor: 1e3,
+		offset: 0
+	},
+	MB: {
+		dimension: "information",
+		factor: 1e6,
+		offset: 0
+	},
+	GB: {
+		dimension: "information",
+		factor: 1e9,
+		offset: 0
+	},
+	"°": {
+		dimension: "angle",
+		factor: 1,
+		offset: 0
+	},
+	dBFS: {
+		dimension: "sound-level",
+		factor: 1,
+		offset: 0
+	},
+	dBm: {
+		dimension: "signal-level",
+		factor: 1,
+		offset: 0
+	},
+	mired: {
+		dimension: "colour-temperature",
+		factor: 1,
+		offset: 0
+	},
+	kbps: {
+		dimension: "bitrate",
+		factor: 1,
+		offset: 0
+	},
+	Mbps: {
+		dimension: "bitrate",
+		factor: 1e3,
+		offset: 0
+	},
+	fps: {
+		dimension: "rate",
+		factor: 1,
+		offset: 0
+	}
+};
+/** Resolve a unit's `UnitSpec`, or `undefined` when the spelling is unknown. */
+function specFor(unit) {
+	return Object.hasOwn(UNIT_TABLE, unit) ? UNIT_TABLE[unit] : void 0;
+}
+/** Value in `spec`'s unit → its dimension's canonical unit. */
+function toCanonical(value, spec) {
+	return value * spec.factor + spec.offset;
+}
+/** Canonical-unit value → the unit described by `spec`. */
+function fromCanonical(canonical, spec) {
+	return (canonical - spec.offset) / spec.factor;
+}
+/**
+* Graceful variant for the render path: returns the converted value, or
+* `undefined` when the conversion is refused (unknown unit / cross-dimension).
+* Never throws — a render caller falls back to the raw value + source unit.
+*/
+function tryConvertUnit(value, from, to) {
+	if (from === to) return value;
+	const fromSpec = specFor(from);
+	if (!fromSpec) return void 0;
+	const toSpec = specFor(to);
+	if (!toSpec) return void 0;
+	if (fromSpec.dimension !== toSpec.dimension) return void 0;
+	return fromCanonical(toCanonical(value, fromSpec), toSpec);
+}
+/**
+* A number a person types for a physical quantity — the input side of the
+* value + unit contract (D972).
+*
+* Readings are stored in the base unit of their quantity (D944); a cap method
+* param is stored in the unit its input schema DECLARES (`paramMeta`). The
+* wire pair {@link QuantityValue} says "this number is expressed in this
+* unit"; {@link convertQuantityInput} brings it to the stored unit and refuses,
+* with a typed {@link QuantityUnitError}, a unit that cannot be that quantity.
+*/
+/** A unit that cannot be applied to the number it was given with. */
+var QuantityUnitError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(`[${code}] ${message}`);
+		this.name = "QuantityUnitError";
+		this.code = code;
+	}
+};
+/** The wire pair: `value` is expressed in `unit`. */
+var QuantityValueSchema = object({
+	value: number(),
+	unit: string().min(1)
+});
+/**
+* Zod `.meta()` bag for a cap METHOD param that is a physical quantity — the
+* input-side twin of `readingMeta`. The value is carried in `unit` (a gram
+* portion stays in grams); the unit must belong to the quantity, checked once
+* when the cap is declared.
+*/
+function paramMeta(declared) {
+	const base = baseUnitOf(declared.quantity);
+	if (base === void 0) throw new QuantityUnitError("unknown-unit", `quantity "${declared.quantity}" has no unit`);
+	if (tryConvertUnit(1, declared.unit, base) === void 0) throw new QuantityUnitError("cross-dimension", `"${declared.unit}" is not a unit of ${declared.quantity}`);
+	return {
+		quantity: declared.quantity,
+		unit: declared.unit
+	};
+}
+object({
+	quantity: ReadingQuantitySchema,
+	unit: string().min(1)
+});
 /** How a leaf compares a device field to a value. Derived from the field's
 *  `kind` in `deviceManager.getWireableFields`, never hand-maintained. */
 var AutomationConditionOperatorSchema = _enum([
@@ -15907,8 +16379,10 @@ var AutomationConditionLeafSchema = object({
 		string(),
 		number(),
 		boolean(),
-		array(union([string(), number()]))
-	])
+		array(union([string(), number()])),
+		QuantityValueSchema
+	]),
+	unit: string().min(1).optional()
 });
 var AutomationConditionStationaryPresentSchema = object({
 	kind: literal("stationary-present"),
@@ -16061,7 +16535,13 @@ var AutomationCapStepSchema = object({
 	/** Values may carry `{{vars.x}}` slots, or be exactly `{ $var: 'name' }`, which
 	*  SUBSTITUTE and do not evaluate (§3.2.3). Anything beyond substitution is
 	*  the expression leaf. */
-	args: record(string(), unknown()).optional()
+	args: record(string(), unknown()).optional(),
+	/**
+	* The unit the person picked per arg (display only). `args` always hold the
+	* value in the unit the method's input DECLARES (`paramMeta`); on a write an
+	* arg may be a {@link QuantityValue}, which the save boundary converts.
+	*/
+	argUnits: record(string(), string().min(1)).optional()
 });
 /**
 * The steps an internal Action may contain: cap and wait, and nothing that can
@@ -16441,6 +16921,16 @@ object({
 	lastRunAt: number().nullable(),
 	lastError: string().nullable()
 });
+/** A bare number accepted as a base unit — the save succeeded, say so. */
+var UnitWarningSchema = object({
+	/** Where in the saved record, e.g. `conditions.children.0` or `steps.2.args.grams`. */
+	path: string(),
+	deviceId: number().int().optional(),
+	field: string(),
+	value: number(),
+	assumedUnit: string(),
+	message: string()
+});
 /**
 * notification-output — canonical, capability-gated notification delivery.
 *
@@ -21785,56 +22275,6 @@ var DeviceAdminLinkSchema = object({
 });
 method(object({ deviceId: number().int().nonnegative() }), DeviceAdminLinkSchema.nullable(), { auth: "admin" });
 /**
-* Identity envelope for a device's upstream-system metadata.
-*
-* Two jobs:
-*
-*   1. **Dispatch key.** `id` is the natural identifier the SOURCE system
-*      uses to address this device (HA `entity_id`, Reolink MAC, ONVIF
-*      WS-Discovery endpoint UUID, …). Provider code keeps a
-*      `Map<sourceInfo.id, IDevice>` to route inbound push events in O(1)
-*      without round-tripping through `stableId` / `id` mappings.
-*
-*   2. **Stability bridge.** `uniqueId` is the *immutable* upstream id when
-*      one exists (HA `entity.unique_id`, Reolink MAC again — same as `id`
-*      for vendors where MAC is the natural key). For systems where the
-*      live dispatch key can be renamed (HA `entity_id` can be edited),
-*      providers detect renames by matching `uniqueId` and patch `id`
-*      in-place so dispatch keeps working.
-*
-* **Display unit and precision are NOT stored here.** They are a read-time
-* preference (D944). A polymorphic reading stores its `quantity` here once,
-* at adopt, and a date/time value stores `dateTimeShape` the same way —
-* neither is repeated on each sample. The `device_class` tag is an
-* HA-specific input consumed at the discovery boundary (`ha-domain-mapping`)
-* to derive the CamStack `DeviceRole`; it is never stored after that point.
-*
-* The `raw` escape hatch carries provider-specific attributes that don't
-* fit the structured slots (HA `attributes` whitelist, Reolink `deviceCache`
-* details, …). Providers control what lands here.
-*/
-var SourceInfoSchema = object({
-	/** Live dispatch key — mutable when the source system allows rename. */
-	id: string(),
-	/** Source system tag — e.g. 'homeassistant' | 'reolink' | 'onvif'. */
-	system: string(),
-	/** Immutable upstream identifier when available (HA `unique_id`, … ).
-	*  Used to detect rename when `id` changes. */
-	uniqueId: string().optional(),
-	/** Quantity of a polymorphic reading, written once at adopt (D944). */
-	quantity: ReadingQuantitySchema.optional(),
-	/** Date / time / datetime shape of a string reading, written once at adopt. */
-	dateTimeShape: _enum([
-		"date",
-		"time",
-		"datetime"
-	]).optional(),
-	/** Provider-specific extras that don't fit the structured slots.
-	*  Whitelist what goes here per provider — do NOT dump entire HA
-	*  attribute blobs (would explode the meta JSON column). */
-	raw: record(string(), unknown()).optional()
-});
-/**
 * device-discovery — device-scoped capability for parents that host /
 * enumerate child devices (Reolink Hub / NVR, ONVIF gateway, future
 * integrations). The parent advertises a list of discoverable children,
@@ -57841,13 +58281,19 @@ method(object({}), array(ActionEntrySchema), { auth: "admin" }), method(object({
 }), method(ActionIdInput, _void(), {
 	kind: "mutation",
 	auth: "admin"
-}), method(ActionIdInput, object({ traces: array(AutomationRunTraceSchema) }), { auth: "admin" }), method(object({ action: ActionInputSchema }), object({ action: ActionEntrySchema }), {
+}), method(ActionIdInput, object({ traces: array(AutomationRunTraceSchema) }), { auth: "admin" }), method(object({ action: ActionInputSchema }), object({
+	action: ActionEntrySchema,
+	warnings: array(UnitWarningSchema).optional()
+}), {
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
 	actionId: string().min(1),
 	action: ActionInputSchema.partial()
-}), object({ action: ActionEntrySchema }), {
+}), object({
+	action: ActionEntrySchema,
+	warnings: array(UnitWarningSchema).optional()
+}), {
 	kind: "mutation",
 	auth: "admin"
 }), method(ActionIdInput, _void(), {
@@ -62494,6 +62940,14 @@ var PetFeederDeviceStatusSchema = _enum([
 	"on_batteries"
 ]);
 var gramsPortion = number().int().min(4).max(200);
+/** A portion REQUESTED of the feeder is a mass the method takes in GRAMS (the
+*  hardware's own unit). The bounds are grams; a caller entering another unit
+*  converts to grams first (`paramMeta`, D972). The STATUS fields above stay
+*  plain grams — they are not readings in the kilogram base. */
+var gramsParam = gramsPortion.meta(paramMeta({
+	quantity: "mass",
+	unit: "g"
+}));
 object({
 	/** Food in the TANK (hopper), as the feeder's own sensor reports it
 	*  (`state.food`). A coarse level code, not grams — `0` is empty. The
@@ -62568,9 +63022,9 @@ object({
 });
 DeviceType.PetFeeder, method(object({
 	deviceId: number().int().nonnegative(),
-	grams: gramsPortion.optional(),
-	hopper1: gramsPortion.optional(),
-	hopper2: gramsPortion.optional()
+	grams: gramsParam.optional(),
+	hopper1: gramsParam.optional(),
+	hopper2: gramsParam.optional()
 }), _void(), {
 	kind: "mutation",
 	auth: "protected"
@@ -79271,7 +79725,8 @@ var APPLIANCE_CAP_VOCABULARY = {
 						min: 4,
 						max: 200,
 						step: 1,
-						unit: "g"
+						unit: "g",
+						quantity: "mass"
 					},
 					optional: true
 				}]
@@ -79290,7 +79745,8 @@ var APPLIANCE_CAP_VOCABULARY = {
 						min: 4,
 						max: 200,
 						step: 1,
-						unit: "g"
+						unit: "g",
+						quantity: "mass"
 					},
 					optional: true
 				}, {
@@ -79301,7 +79757,8 @@ var APPLIANCE_CAP_VOCABULARY = {
 						min: 4,
 						max: 200,
 						step: 1,
-						unit: "g"
+						unit: "g",
+						quantity: "mass"
 					},
 					optional: true
 				}]