@camstack/addon-model-studio 1.1.326 → 1.1.327

package/dist/model-studio.addon.mjs

@@ -5824,7 +5824,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-63gM_1JR.mjs
+//#region ../types/dist/sleep-CeyhrcOk.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -7891,6 +7891,7 @@ var BaseAddon = class {
 	* a warning and falls back rather than crashing boot.
 	*/
 	state(key, schema, fallback) {
+		this._declaredStateKeys.add(key);
 		return createDurableState({
 			key,
 			schema,
@@ -7906,6 +7907,96 @@ var BaseAddon = class {
 			} })
 		});
 	}
+	/** Durable-state keys this process registered through {@link state}. */
+	_declaredStateKeys = /* @__PURE__ */ new Set();
+	/**
+	* Stale-data audit: every global-settings key this addon still declares —
+	* constructor defaults, settings-schema fields (layout containers included),
+	* durable-state keys and the root of each `secretStatePaths` entry. Answered
+	* here, in the addon's own process, so the hub keeps no copy of it.
+	*/
+	async getDeclaredSettingsKeys() {
+		return { keys: [...this.declaredKeySet()].toSorted() };
+	}
+	declaredKeySet() {
+		const keys = new Set(Object.keys(this.defaults));
+		const schema = this.globalSettingsSchema();
+		if (schema) for (const section of schema.sections) for (const key of collectFieldKeys(section.fields)) keys.add(key);
+		for (const key of this._declaredStateKeys) keys.add(key);
+		for (const path of this.secretStatePaths) {
+			const root = path.split(/[.[]/, 1)[0];
+			if (root) keys.add(root);
+		}
+		return keys;
+	}
+	/**
+	* Stale-data audit: remove stored global-settings keys the addon no longer
+	* declares, and clear the keychain values their markers held — except a value
+	* a surviving key still points at. A declared or absent key is refused.
+	*/
+	async unsetStoredSettingsKeys(keys) {
+		const settings = this._ctx?.settings;
+		const raw = this.rawSettings();
+		if (!settings || !raw) return {
+			removed: [],
+			refused: keys.map((key) => ({
+				key,
+				reason: "no settings store"
+			})),
+			secretsCleared: 0
+		};
+		let stored;
+		try {
+			stored = await raw.readAddonStore();
+		} catch (error) {
+			const reason = `store unreadable: ${error instanceof Error ? error.message : "unknown"}`;
+			return {
+				removed: [],
+				refused: keys.map((key) => ({
+					key,
+					reason
+				})),
+				secretsCleared: 0
+			};
+		}
+		const declared = this.declaredKeySet();
+		const removed = [];
+		const refused = [];
+		for (const key of keys) {
+			const base = key.split("@", 1)[0] ?? key;
+			if (declared.has(base)) refused.push({
+				key,
+				reason: "still declared by the addon"
+			});
+			else if (!(key in stored)) refused.push({
+				key,
+				reason: "not stored"
+			});
+			else removed.push(key);
+		}
+		if (removed.length === 0) return {
+			removed,
+			refused,
+			secretsCleared: 0
+		};
+		const kept = /* @__PURE__ */ new Set();
+		const held = /* @__PURE__ */ new Set();
+		for (const [key, value] of Object.entries(stored)) {
+			const target = removed.includes(key) ? held : kept;
+			for (const ref of collectSecretMarkerRefs(value)) target.add(ref);
+		}
+		const refsToClear = [...held].filter((ref) => !kept.has(ref));
+		const patch = {};
+		for (const key of removed) patch[key] = void 0;
+		await settings.writeAddonStore(patch);
+		const secretsCleared = refsToClear.length > 0 && this._ctx?.secrets ? await this._ctx.secrets.delete(refsToClear) : 0;
+		await this.resolveConfig();
+		return {
+			removed,
+			refused,
+			secretsCleared
+		};
+	}
 	/** Per-device variant of {@link state}, backed by the per-device store. */
 	deviceState(deviceId, key, schema, fallback) {
 		return createDurableState({
@@ -8176,6 +8267,21 @@ function dropPerNodeFields(fields) {
 	}
 	return kept;
 }
+function collectFieldKeys(fields) {
+	const collected = [];
+	for (const field of fields) {
+		if (field.type === "group") {
+			collected.push(...collectFieldKeys(field.fields));
+			continue;
+		}
+		if (field.type === "sub-tabs") {
+			for (const tab of field.tabs) collected.push(...collectFieldKeys(tab.fields));
+			continue;
+		}
+		if ("key" in field && typeof field.key === "string") collected.push(field.key);
+	}
+	return collected;
+}
 function collectPerNodeFieldKeys(fields) {
 	const collected = [];
 	for (const field of fields) {
@@ -16521,8 +16627,172 @@ 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. */
+new Set([
+	{
+		id: "person",
+		name: "Person"
+	},
+	{
+		id: "vehicle",
+		name: "Vehicle"
+	},
+	{
+		id: "animal",
+		name: "Animal"
+	},
+	{
+		id: "package",
+		name: "Package"
+	}
+].map((l) => l.id));
+var COCO_TO_MACRO = {
+	mapping: {
+		person: "person",
+		bicycle: "vehicle",
+		car: "vehicle",
+		motorcycle: "vehicle",
+		airplane: "vehicle",
+		bus: "vehicle",
+		train: "vehicle",
+		truck: "vehicle",
+		boat: "vehicle",
+		bird: "animal",
+		cat: "animal",
+		dog: "animal",
+		horse: "animal",
+		sheep: "animal",
+		cow: "animal",
+		elephant: "animal",
+		bear: "animal",
+		zebra: "animal",
+		giraffe: "animal",
+		suitcase: "package",
+		backpack: "package",
+		handbag: "package"
+	},
+	preserveOriginal: false
+};
+/**
+* WHAT a detection-shaped leaf is about: one MACRO class (person, vehicle,
+* animal, package) plus an OPTIONAL label that narrows it.
+*
+* The taxonomy is `COCO_TO_MACRO` (and `CLASS_MAP_MACRO_TARGETS`) — never a
+* second list. The label that fits depends on the macro class:
+*
+*  - `animal`  → a sub-class (`dog`, `cat`, …);
+*  - `person`  → a known face (an identity of the `face-gallery`);
+*  - `vehicle` → a plate (its text) or a sub-class (`car`, `truck`, …);
+*  - `package` → a sub-class.
+*
+* `other` exists only so a class the taxonomy does not know (a custom model's
+* `forklift`) survives the conversion of a stored recipe without widening.
+*
+* A label is decided LATE (D683): face recognition and LPR land after the
+* detection starts. The track-lifecycle `update` event carries the newly
+* resolved `label` / `plateText`, which is why a leaf with a label fires when
+* the subject GETS it — not at the first detection.
+*/
+var SubClassLabelSchema = object({
+	kind: literal("sub-class"),
+	className: string().min(1)
+});
+var IdentityLabelSchema = object({
+	kind: literal("identity"),
+	/** The `face-gallery` identity id (stable across a rename). */
+	identityId: string().min(1),
+	/** The identity's name — what a track-lifecycle event carries as `label`. */
+	name: string().min(1)
+});
+var PlateLabelSchema = object({
+	kind: literal("plate"),
+	text: string().min(1)
+});
+function macroOf$1(className) {
+	return COCO_TO_MACRO.mapping[className.toLowerCase()] ?? className.toLowerCase();
+}
+/** A sub-class label must belong to the macro it is under. */
+function subClassBelongs(macro, label) {
+	return label === void 0 || macroOf$1(label.className) === macro;
+}
+var subClassOf = (macro) => SubClassLabelSchema.refine((l) => subClassBelongs(macro, l), { message: `that class is not a kind of ${macro} in the detection taxonomy` });
+var DetectionSubjectSchema = discriminatedUnion("macro", [
+	object({
+		macro: literal("animal"),
+		label: subClassOf("animal").optional()
+	}),
+	object({
+		macro: literal("person"),
+		label: IdentityLabelSchema.optional()
+	}),
+	object({
+		macro: literal("vehicle"),
+		label: discriminatedUnion("kind", [SubClassLabelSchema.refine((l) => subClassBelongs("vehicle", l), { message: "that class is not a kind of vehicle in the detection taxonomy" }), PlateLabelSchema]).optional()
+	}),
+	object({
+		macro: literal("package"),
+		label: subClassOf("package").optional()
+	}),
+	object({
+		macro: literal("other"),
+		className: string().min(1)
+	})
+]);
+/**
+* The subject of a PARKED object. The stationary registry's event carries a
+* class and a zone, no face and no plate — an identity or plate label there
+* could never match, so the schema refuses it instead of letting it sit dead.
+*/
+var StationarySubjectSchema = DetectionSubjectSchema.refine((s) => s.macro === "other" || s.label === void 0 || s.label.kind === "sub-class", { message: "a parked object carries no face or plate — only a class can narrow it" });
+/**
+* A stored class string as a subject: a macro name stays a macro; a raw class
+* the taxonomy files under a macro becomes that macro plus the sub-class label
+* (`dog` → animal / dog); anything else is `other`, kept verbatim.
+*/
+function subjectFromClassName(className) {
+	const name = className.trim().toLowerCase();
+	const macro = COCO_TO_MACRO.mapping[name];
+	if (new Set(Object.values(COCO_TO_MACRO.mapping)).has(name)) return macroOnly(name);
+	if (macro === void 0) return {
+		macro: "other",
+		className
+	};
+	const label = {
+		kind: "sub-class",
+		className: name
+	};
+	switch (macro) {
+		case "animal": return {
+			macro: "animal",
+			label
+		};
+		case "vehicle": return {
+			macro: "vehicle",
+			label
+		};
+		case "package": return {
+			macro: "package",
+			label
+		};
+		default: return {
+			macro: "other",
+			className
+		};
+	}
+}
+function macroOnly(macro) {
+	switch (macro) {
+		case "animal": return { macro: "animal" };
+		case "person": return { macro: "person" };
+		case "vehicle": return { macro: "vehicle" };
+		case "package": return { macro: "package" };
+		default: return {
+			macro: "other",
+			className: macro
+		};
+	}
+}
+/** How a state leaf compares a device field to a value. Derived from the
+*  field's `kind` in `deviceManager.getWireableFields`, never hand-maintained. */
 var AutomationConditionOperatorSchema = _enum([
 	"eq",
 	"ne",
@@ -16533,12 +16803,76 @@ var AutomationConditionOperatorSchema = _enum([
 	"contains",
 	"in"
 ]);
-var AutomationConditionLeafSchema = object({
-	kind: literal("condition"),
+/**
+* D8 compliance, and it is the reason a "becomes" leaf is not merely an event
+* subscription: it evaluates against the **state mirror**, which is reconciled,
+* and an event only WAKES the evaluation. A dropped event therefore DELAYS a
+* fire; it does not lose it.
+*/
+var DeviceBecomesLeafSchema = object({
+	kind: literal("device-becomes"),
+	deviceId: number().int().nonnegative(),
+	cap: string().min(1),
+	fieldPath: string().min(1),
+	/** Fire when the field takes this value. Omit to fire on any change. */
+	becomes: union([
+		string(),
+		number(),
+		boolean()
+	]).optional(),
+	/** Only on a CHANGE of value, not on every re-report. */
+	edge: boolean().optional(),
+	/** The new value must hold this long before it counts. */
+	forMs: number().int().min(0).max(864e5).optional(),
+	/** Collapse a burst into one occurrence. */
+	debounceMs: number().int().min(0).max(6e5).optional()
+});
+var DeviceEventLeafSchema = object({
+	kind: literal("device-event"),
+	/** An `EventCategory` value. */
+	category: string().min(1),
+	deviceId: number().int().nonnegative().optional()
+});
+var ScheduleLeafSchema = object({
+	kind: literal("schedule"),
+	cron: string().min(1).max(120)
+});
+var ManualLeafSchema = object({ kind: literal("manual") });
+var IntervalLeafSchema = object({
+	kind: literal("interval"),
+	minutes: number().int().min(1).max(1440)
+});
+var DetectionLeafSchema = object({
+	kind: literal("detection"),
+	/** One macro class each, optionally narrowed by a label; a track of any listed subject fires. */
+	subjects: array(DetectionSubjectSchema).min(1),
+	deviceIds: array(number().int().nonnegative()).min(1),
+	/** The track must have visited at least one of these zones. */
+	zones: array(string().min(1)).min(1).optional(),
+	/** Best-so-far confidence the track must reach. */
+	minScore: number().min(0).max(1).optional()
+});
+var StationaryLeafSchema = object({
+	kind: literal("stationary"),
+	deviceIds: array(number().int().nonnegative()).min(1),
+	subjects: array(StationarySubjectSchema).min(1).optional(),
+	zones: array(string().min(1)).min(1).optional(),
+	/** `appeared`: it became parked. `departed`: the registry retired it. */
+	phase: _enum(["appeared", "departed"])
+});
+/** "is": one device field compared to one value, NOW. */
+var DeviceIsLeafSchema = object({
+	kind: literal("device-is"),
 	deviceId: number().int().nonnegative(),
 	cap: string().min(1),
 	fieldPath: string().min(1),
 	operator: AutomationConditionOperatorSchema,
+	/**
+	* The value. A number on a quantity field is stored in the field's base unit
+	* (D944); a quantity value is the WRITE form, which the save boundary
+	* replaces with the converted number and `unit`. A leaf that still carries
+	* one is never evaluated (it fails).
+	*/
 	value: union([
 		string(),
 		number(),
@@ -16546,24 +16880,26 @@ var AutomationConditionLeafSchema = object({
 		array(union([string(), number()])),
 		QuantityValueSchema
 	]),
+	/** The unit the person picked for `value` (display only; `value` is in the base unit). */
 	unit: string().min(1).optional()
 });
-var AutomationConditionStationaryPresentSchema = object({
+/**
+* True when the camera currently has a PARKED object matching `subjects` in at
+* least one of `zones`. Reads the zone-analytics snapshot through the same
+* mirror as every other state leaf, so a dropped event never decides it (D49).
+*/
+var StationaryPresentLeafSchema = object({
 	kind: literal("stationary-present"),
 	deviceId: number().int().nonnegative(),
-	/** Class names; a macro class matches every raw class that maps to it. */
-	classes: array(string().min(1)).min(1).optional(),
-	/** The parked object must be in at least one of these zones. */
+	subjects: array(StationarySubjectSchema).min(1).optional(),
 	zones: array(string().min(1)).min(1).optional()
 });
 /**
-* The expression leaf, declared as a plain object rather than an intersection
-* with {@link ExpressionSourceSchema}: a discriminated union has to be able to
-* read `kind` off each option, and an intersection hides it. The author-time
-* validation is the SAME function `ExpressionSourceSchema` runs, so the two
-* cannot drift — an expression that one accepts, the other accepts.
+* The escape hatch: the bounded expression engine over named device bindings.
+* Declared as a plain object so a discriminated union can read `kind`; the
+* author-time validation is the SAME function `ExpressionSourceSchema` runs.
 */
-var AutomationConditionExpressionSchema = object({
+var ExpressionLeafSchema = object({
 	kind: literal("expression"),
 	expr: string().min(1).max(MAX_EXPRESSION_SOURCE_LENGTH),
 	bindings: record(string().regex(EXPRESSION_IDENTIFIER_RE), ExpressionBindingSourceSchema)
@@ -16575,55 +16911,62 @@ var AutomationConditionExpressionSchema = object({
 		path: ["expr"]
 	});
 });
-var AutomationConditionSchema = lazy(() => discriminatedUnion("kind", [
+var AutomationWhenSchema = lazy(() => discriminatedUnion("kind", [
 	object({
 		kind: literal("all"),
-		children: array(AutomationConditionSchema)
+		children: array(AutomationWhenSchema)
 	}),
 	object({
 		kind: literal("any"),
-		children: array(AutomationConditionSchema)
+		children: array(AutomationWhenSchema)
 	}),
 	object({
 		kind: literal("not"),
-		child: AutomationConditionSchema
+		child: AutomationWhenSchema
 	}),
-	AutomationConditionLeafSchema,
-	AutomationConditionExpressionSchema,
-	AutomationConditionStationaryPresentSchema
+	DeviceBecomesLeafSchema,
+	DeviceEventLeafSchema,
+	ScheduleLeafSchema,
+	ManualLeafSchema,
+	IntervalLeafSchema,
+	DetectionLeafSchema,
+	StationaryLeafSchema,
+	DeviceIsLeafSchema,
+	StationaryPresentLeafSchema,
+	ExpressionLeafSchema
 ]));
 /**
-* What starts a run.
-*
-* D8 compliance, and it is the reason `device-state` is not merely an event
-* subscription: the trigger evaluates against the **state mirror**, which is
-* reconciled, and an event only WAKES the evaluation. A dropped event therefore
-* DELAYS a trigger; it does not lose it. `schedule` uses `croner` — the one
-* already in the repo — because `setInterval(24h)` drifts and "at 23:30" does
-* not.
-*/
-var AutomationTriggerSchema = discriminatedUnion("kind", [
+* The recipe shape before the single `when` tree: a flat list of triggers
+* (OR'd, each an instant) and an optional condition tree. Stored recipes —
+* the `AUTOMATION_RECIPE` literal of every block saved so far, and whatever an
+* older client still posts — are in this shape, so it stays READABLE here, and
+* {@link convertLegacyRecipe} turns it into the new one, losslessly and one
+* way. Nothing writes this shape any more.
+*
+*   `{ triggers: [t1…tn], conditions?: C }`
+*      → `when = all(any(t1…tn), C)`, or `any(t1…tn)` without `C`;
+*        a single trigger is not wrapped in `any`.
+*   a `condition` leaf → a `device-is` leaf (the "is" verb);
+*   a `device-state` trigger → a `device-becomes` leaf (the "becomes" verb);
+*   `classes: ['dog']` → the macro `animal` with the label `dog`.
+*/
+var LegacyTriggerSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("device-state"),
 		deviceId: number().int().nonnegative(),
 		cap: string().min(1),
 		fieldPath: string().min(1),
-		/** Fire when the field takes this value. Omit to fire on any change. */
 		becomes: union([
 			string(),
 			number(),
 			boolean()
 		]).optional(),
-		/** Only on a CHANGE of value, not on every re-report. */
 		edge: boolean().optional(),
-		/** The condition must hold this long before the run starts. */
 		forMs: number().int().min(0).max(864e5).optional(),
-		/** Collapse a burst into one run. */
 		debounceMs: number().int().min(0).max(6e5).optional()
 	}),
 	object({
 		kind: literal("device-event"),
-		/** An `EventCategory` value. */
 		category: string().min(1),
 		deviceId: number().int().nonnegative().optional()
 	}),
@@ -16634,25 +16977,16 @@ var AutomationTriggerSchema = discriminatedUnion("kind", [
 	object({ kind: literal("manual") }),
 	object({
 		kind: literal("detection"),
-		/** Class names. A macro class (`animal`, `vehicle`, `person`, `package`)
-		*  matches every raw class that maps to it; any other name matches
-		*  exactly. */
 		classes: array(string().min(1)).min(1),
 		deviceIds: array(number().int().nonnegative()).min(1),
-		/** The track must have visited at least one of these zones. */
 		zones: array(string().min(1)).min(1).optional(),
-		/** Best-so-far confidence the track must reach. */
 		minScore: number().min(0).max(1).optional()
 	}),
 	object({
 		kind: literal("stationary"),
 		deviceIds: array(number().int().nonnegative()).min(1),
-		/** Class names; a macro class matches like the detection trigger. */
 		classes: array(string().min(1)).min(1).optional(),
-		/** The parked object must be in at least one of these zones. */
 		zones: array(string().min(1)).min(1).optional(),
-		/** `appeared`: it became parked. `departed`: the registry retired it.
-		*  The vocabulary of `PipelineAnalyticsStationaryChanged`. */
 		phase: _enum(["appeared", "departed"])
 	}),
 	object({
@@ -16660,6 +16994,143 @@ var AutomationTriggerSchema = discriminatedUnion("kind", [
 		minutes: number().int().min(1).max(1440)
 	})
 ]);
+var LegacyConditionLeafSchema = object({
+	kind: literal("condition"),
+	deviceId: number().int().nonnegative(),
+	cap: string().min(1),
+	fieldPath: string().min(1),
+	operator: AutomationConditionOperatorSchema,
+	value: union([
+		string(),
+		number(),
+		boolean(),
+		array(union([string(), number()])),
+		QuantityValueSchema
+	]),
+	unit: string().min(1).optional()
+});
+var LegacyStationaryPresentSchema = object({
+	kind: literal("stationary-present"),
+	deviceId: number().int().nonnegative(),
+	classes: array(string().min(1)).min(1).optional(),
+	zones: array(string().min(1)).min(1).optional()
+});
+var LegacyExpressionSchema = object({
+	kind: literal("expression"),
+	expr: string().min(1).max(MAX_EXPRESSION_SOURCE_LENGTH),
+	bindings: record(string().regex(EXPRESSION_IDENTIFIER_RE), ExpressionBindingSourceSchema)
+}).superRefine((src, ctx) => {
+	const err = validateExpressionSource(src);
+	if (err !== null) ctx.addIssue({
+		code: "custom",
+		message: err,
+		path: ["expr"]
+	});
+});
+var LegacyConditionSchema = lazy(() => discriminatedUnion("kind", [
+	object({
+		kind: literal("all"),
+		children: array(LegacyConditionSchema)
+	}),
+	object({
+		kind: literal("any"),
+		children: array(LegacyConditionSchema)
+	}),
+	object({
+		kind: literal("not"),
+		child: LegacyConditionSchema
+	}),
+	LegacyConditionLeafSchema,
+	LegacyExpressionSchema,
+	LegacyStationaryPresentSchema
+]));
+function convertTrigger(trigger) {
+	switch (trigger.kind) {
+		case "device-state": return {
+			...trigger,
+			kind: "device-becomes"
+		};
+		case "detection": {
+			const { classes, ...rest } = trigger;
+			return {
+				...rest,
+				subjects: classes.map(subjectFromClassName)
+			};
+		}
+		case "stationary": {
+			const { classes, ...rest } = trigger;
+			return {
+				...rest,
+				...classes === void 0 ? {} : { subjects: classes.map(subjectFromClassName) }
+			};
+		}
+		default: return trigger;
+	}
+}
+/** An old condition tree as a `when` subtree: `condition` → "is", classes → subjects. */
+function convertLegacyCondition(condition) {
+	switch (condition.kind) {
+		case "condition": return {
+			...condition,
+			kind: "device-is"
+		};
+		case "stationary-present": {
+			const { classes, ...rest } = condition;
+			return {
+				...rest,
+				...classes === void 0 ? {} : { subjects: classes.map(subjectFromClassName) }
+			};
+		}
+		case "expression": return condition;
+		case "not": return {
+			kind: "not",
+			child: convertLegacyCondition(condition.child)
+		};
+		case "all":
+		case "any": return {
+			kind: condition.kind,
+			children: condition.children.map(convertLegacyCondition)
+		};
+	}
+}
+/** `all(any(t1…tn), C)`, or `any(t1…tn)`; a single trigger is not wrapped in `any`. */
+function convertLegacyWhen(half) {
+	const leaves = half.triggers.map(convertTrigger);
+	const first = leaves[0];
+	const triggers = leaves.length === 1 && first !== void 0 ? first : {
+		kind: "any",
+		children: leaves
+	};
+	if (half.conditions === void 0) return triggers;
+	return {
+		kind: "all",
+		children: [triggers, convertLegacyCondition(half.conditions)]
+	};
+}
+/**
+* The automation RECIPE — what a visually-authored automation is, before it
+* becomes code.
+*
+* This is the data half of `docs/design/2026-08-08-automation-scripts-custom-devices.md`
+* Phase 6. A recipe is not an engine and never evaluates anything: it is a
+* declarative description that {@link generateAutomationBlock} compiles to the
+* TypeScript of an ordinary core block. There is therefore no second rule
+* engine, no second store and no second runtime — the block runner is the
+* runtime, `core_blocks` is the store (§2.1).
+*
+* Two parts:
+*
+*  - **`when`** — ONE tree (`./when.ts`) of all/any/not over event leaves
+*    (instants) and state leaves (durations). It replaces the flat trigger list
+*    plus the separate condition tree; the firing rule is in that file and in
+*    ADR "one tree".
+*  - **Actions** — `NcRuleActionSchema`'s two steps, plus the `{kind:'code'}`
+*    fragment of §3.2.2. See {@link AutomationActionSchema} for the ONE place
+*    this had to diverge from "verbatim", and why.
+*
+* A recipe stored in the old shape (`triggers` + `conditions`) still LOADS:
+* {@link AutomationRecipeSchema} (the parse-anywhere schema) converts it on parse. Nothing writes it.
+*/
 /**
 * One action step.
 *
@@ -16762,69 +17233,49 @@ var AutomationRunModeSchema = discriminatedUnion("mode", [
 		minutes: number().int().min(1).max(1440)
 	})
 ]);
-var AutomationRecipeSchema = object({
-	triggers: array(AutomationTriggerSchema),
-	conditions: AutomationConditionSchema.optional(),
+var CurrentAutomationRecipeSchema = object({
+	when: AutomationWhenSchema,
 	actions: array(AutomationActionSchema),
 	runMode: AutomationRunModeSchema.optional(),
 	/** How many run traces the automation keeps (default {@link DEFAULT_TRACE_KEEP}). */
 	keepTraces: number().int().min(1).max(100).optional()
 });
-new Set([
-	{
-		id: "person",
-		name: "Person"
-	},
-	{
-		id: "vehicle",
-		name: "Vehicle"
-	},
-	{
-		id: "animal",
-		name: "Animal"
-	},
-	{
-		id: "package",
-		name: "Package"
-	}
-].map((l) => l.id));
-var COCO_TO_MACRO = {
-	mapping: {
-		person: "person",
-		bicycle: "vehicle",
-		car: "vehicle",
-		motorcycle: "vehicle",
-		airplane: "vehicle",
-		bus: "vehicle",
-		train: "vehicle",
-		truck: "vehicle",
-		boat: "vehicle",
-		bird: "animal",
-		cat: "animal",
-		dog: "animal",
-		horse: "animal",
-		sheep: "animal",
-		cow: "animal",
-		elephant: "animal",
-		bear: "animal",
-		zebra: "animal",
-		giraffe: "animal",
-		suitcase: "package",
-		backpack: "package",
-		handbag: "package"
-	},
-	preserveOriginal: false
-};
+/** A recipe as it was stored before the single tree. Read-only: nothing writes this. */
+var LegacyAutomationRecipeSchema = object({
+	triggers: array(LegacyTriggerSchema),
+	conditions: LegacyConditionSchema.optional(),
+	actions: array(AutomationActionSchema),
+	runMode: AutomationRunModeSchema.optional(),
+	keepTraces: number().int().min(1).max(100).optional()
+});
+/** The old shape as the new one, lossless. */
+function convertLegacyRecipe(legacy) {
+	const { triggers, conditions, ...rest } = legacy;
+	return {
+		when: convertLegacyWhen({
+			triggers,
+			conditions
+		}),
+		...rest
+	};
+}
+/**
+* Where recipes are PARSED (the core-blocks cap, the MCP tool, the literal a
+* saved block carries): the new shape as it is, or the old shape converted to
+* it. The output type is always the new one.
+*/
+var AutomationRecipeSchema = union([CurrentAutomationRecipeSchema, LegacyAutomationRecipeSchema.transform(convertLegacyRecipe)]);
 new Set(Object.values(COCO_TO_MACRO.mapping));
 /**
 * Run traces — what an automation (or, later, an Action run) DID, node by node,
 * so the editor can paint every block green or red with its reason.
 *
-* A trace is data, not a log: it covers the WHOLE tree — the trigger stage,
-* every condition node (containers and leaves, including the ones a
-* short-circuit never reached), the run-mode verdict and every action step —
-* each addressed by a stable path (`conditions.0.1`, `actions.2`, or `steps.N`
-* for an Action run). Skipped
+* A trace is data, not a log: it covers the WHOLE tree — the event leaf that
+* fired, every node of the `when` tree (containers and leaves, including the
+* ones a short-circuit never reached), the run-mode verdict and every action
+* step — each addressed by a stable path (`when.0.1`, `actions.2`, or `steps.N`
+* for an Action run). Traces written before the single tree carry
+* `conditions.*` paths and still parse. Skipped
 * evaluations are traced too, and identical consecutive skips collapse into a
 * repeat count so a trigger that fails every 5 minutes cannot flush real runs.
 *
@@ -16856,6 +17307,8 @@ var TraceNodeOutcomeSchema = _enum([
 ]);
 var AutomationTriggerTraceSchema = object({
 	kind: string().min(1),
+	/** The event leaf that fired (`when`, `when.0.1`); absent on traces written before the single tree. */
+	path: string().min(1).optional(),
 	outcome: _enum(["pass", "fail"]),
 	/** Why an event was rejected ("class person not in [dog]") or what fired. */
 	reason: string(),
@@ -16863,15 +17316,23 @@ var AutomationTriggerTraceSchema = object({
 	vars: record(string(), TraceValueSchema)
 });
 var AutomationConditionTraceNodeSchema = object({
-	/** `conditions` for the root, `conditions.<i>` for its i-th child, … */
+	/** `when` for the root, `when.<i>` for its i-th child, … (`conditions…` on an old trace). */
 	path: string().min(1),
 	kind: _enum([
 		"all",
 		"any",
 		"not",
 		"condition",
+		"device-is",
 		"expression",
-		"stationary-present"
+		"stationary-present",
+		"device-becomes",
+		"device-event",
+		"schedule",
+		"interval",
+		"manual",
+		"detection",
+		"stationary"
 	]),
 	outcome: TraceNodeOutcomeSchema,
 	reason: string(),
@@ -16905,6 +17366,12 @@ var AutomationStepTraceSchema = object({
 	deviceId: number().int().optional(),
 	startedAt: number().optional(),
 	endedAt: number().optional(),
+	/**
+	* The parameters the step SENT, after `{{vars.x}}` substitution — what the
+	* device was actually asked. Bounded like trigger `vars`; a secret parameter
+	* is shown as {@link REDACTED_ARG}. Absent on traces written before it existed.
+	*/
+	args: record(string(), TraceValueSchema).optional(),
 	outcome: _enum([
 		"ok",
 		"error",
@@ -17654,6 +18121,23 @@ method(object({
 	addonId: string(),
 	nodeId: string().optional()
 }), SettingsSchemaWithValuesSchema.nullable()), method(object({
+	addonId: string(),
+	nodeId: string().optional()
+}), object({ keys: array(string()) }).nullable(), { auth: "admin" }), method(object({
+	addonId: string(),
+	nodeId: string().optional(),
+	keys: array(string())
+}), object({
+	removed: array(string()),
+	refused: array(object({
+		key: string(),
+		reason: string()
+	})),
+	secretsCleared: number()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
 	addonId: string(),
 	deviceId: number(),
 	nodeId: string().optional()
@@ -21605,6 +22089,8 @@ var StorageKindSchema = object({
 		"orphaned",
 		"dropped"
 	]),
+	/** An owner declared this kind since the engine started. */
+	declaredThisBoot: boolean(),
 	/** `null` when the caller asked for no counts (`counts: false`). */
 	rows: number().int().nonnegative().nullable(),
 	/** Rows x the average size of a sample; null for an empty kind. */
@@ -21616,6 +22102,51 @@ var StorageKindSchema = object({
 	/** The whole declaration, secret paths and entry descriptor included (the entries service builds its handle from it). */
 	declaration: RecordKindDeclarationSchema
 });
+_enum([
+	"orphaned",
+	"stale",
+	"unknown"
+]);
+/** A record kind nobody declared since its owner started, or whose owner is gone. */
+var StaleKindFindingSchema = object({
+	owner: string(),
+	kind: string(),
+	/** `unknown`: the owner could not be judged (not running, or its state unreadable) - never dropped. */
+	verdict: _enum(["orphaned", "unknown"]),
+	reason: string(),
+	rows: number().int().nonnegative().nullable(),
+	/** local-auth's tables are never dropped by this audit. */
+	protected: boolean()
+});
+/** A stored global-settings key the running addon no longer declares. */
+var StaleSettingsKeyFindingSchema = object({
+	addonId: string(),
+	/** The stored key as written, a per-node `<key>@<nodeId>` suffix included. */
+	key: string(),
+	/**
+	* Keychain refs whose ONLY marker sits under this key: in use by stale data,
+	* not orphans yet. Removing the key releases them.
+	*/
+	secretRefs: array(string())
+});
+/** An addon the audit could not judge, with the reason. Never reported as stale. */
+var StaleUnknownSchema = object({
+	subject: string(),
+	reason: string()
+});
+var StaleDataReportSchema = object({
+	/** Epoch ms of the last finished scan; `null` before the first. */
+	scannedAt: number().nullable(),
+	scanning: boolean(),
+	trigger: _enum([
+		"boot",
+		"interval",
+		"manual"
+	]).nullable(),
+	kinds: array(StaleKindFindingSchema),
+	settingsKeys: array(StaleSettingsKeyFindingSchema),
+	unknown: array(StaleUnknownSchema)
+});
 method(object({ ownerPrefix: string().min(1).optional() }), object({ tables: array(StorageTableSchema) }), { auth: "admin" }), method(object({
 	owner: string().min(1).optional(),
 	/** `false` skips the per-kind row count (a catalog read only). Default true. */
@@ -21623,7 +22154,30 @@ method(object({ ownerPrefix: string().min(1).optional() }), object({ tables: arr
 }), object({ kinds: array(StorageKindSchema) }), { auth: "admin" }), method(RecordQueryInputSchema.extend({
 	owner: string().min(1),
 	kind: RecordKindNameSchema
-}), RecordQueryResultSchema, { auth: "admin" });
+}), RecordQueryResultSchema, { auth: "admin" }), method(object({}), StaleDataReportSchema, { auth: "admin" }), method(object({}), StaleDataReportSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	owner: string().min(1),
+	kind: RecordKindNameSchema
+}), object({
+	deleted: number().int().nonnegative(),
+	secretsReleased: number().int().nonnegative()
+}), {
+	kind: "mutation",
+	auth: "admin",
+	caller: "required"
+}), method(object({
+	addonId: string().min(1),
+	key: string().min(1)
+}), object({
+	removed: boolean(),
+	secretsCleared: number().int().nonnegative()
+}), {
+	kind: "mutation",
+	auth: "admin",
+	caller: "required"
+});
 /**
 * record-entries - the ONE admin surface for every list of user-created entries
 * (D881): notification targets, brokers, LLM profiles, anything an addon
@@ -21762,6 +22316,12 @@ method(object({
 }), method(object({ deviceId: number().int() }), object({ refs: array(string()).readonly() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({
+	refs: RefListSchema,
+	onBehalfOf: string().min(1)
+}), object({ released: number().int() }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(object({}), array(KeychainSecretMetaSchema).readonly(), { auth: "admin" }), method(object({}), KeychainStateSchema, { auth: "admin" });
 /**
 * device-history — the ONE mechanism for numeric history (D850).
@@ -22551,7 +23111,9 @@ var DiscoveredChildDeviceSchema = lazy(() => object({
 	/** Upstream-system identity + rendering hints for the candidate. */
 	sourceInfo: SourceInfoSchema.optional(),
 	/** Nested entity-children for accordion preview — integrations populate, Hubs omit. */
-	children: array(DiscoveredChildDeviceSchema).readonly().optional()
+	children: array(DiscoveredChildDeviceSchema).readonly().optional(),
+	/** `childNativeId` of the gateway candidate in the same list this device sits behind. */
+	parentStableId: string().optional()
 }));
 /**
 * Status block — populated by the integration after each
@@ -42866,6 +43428,79 @@ object({
 	metadata: record(string(), unknown()).optional()
 });
 /**
+* HOW a provider can be found on the network. The provider only DECLARES the
+* mode; the `local-network` scan engine runs it once for every provider that
+* asked (one multicast browse, one host sweep) and hands the raw hits back to
+* `classifyDiscoveryHits`. A provider never opens a discovery socket itself,
+* except through a `custom` mode.
+*/
+var DiscoveryModeSchema = discriminatedUnion("kind", [
+	object({
+		kind: literal("mdns"),
+		/** DNS-SD service type, e.g. `_esphomelib._tcp`. */
+		serviceType: string().min(1),
+		/** Regular expression an instance name must match (case-insensitive). */
+		instancePattern: string().optional()
+	}),
+	object({
+		kind: literal("ws-discovery"),
+		/** Probe types (e.g. `dn:NetworkVideoTransmitter`); omitted = any device. */
+		types: array(string()).optional()
+	}),
+	object({
+		kind: literal("ssdp"),
+		searchTarget: string().min(1)
+	}),
+	object({
+		kind: literal("udp-broadcast"),
+		port: number().int().min(1).max(65535),
+		payloadHex: string().regex(/^([0-9a-fA-F]{2})*$/),
+		/** Port replies arrive on, when the device answers somewhere other than the source port. */
+		listenPort: number().int().min(1).max(65535).optional()
+	}),
+	object({
+		kind: literal("http-probe"),
+		port: number().int().min(1).max(65535),
+		path: string().startsWith("/"),
+		method: _enum(["GET", "POST"]).default("GET"),
+		bodyText: string().optional(),
+		contentType: string().optional(),
+		tls: boolean().default(false),
+		/** Status codes that count as a hit. Omitted = any HTTP answer. */
+		acceptStatus: array(number().int()).optional()
+	}),
+	object({
+		kind: literal("custom"),
+		/** Why the engine cannot do it (an allowlisted exception, e.g. a vendor UDP protocol). */
+		reason: string().min(1)
+	})
+]);
+/** What the engine saw on the wire for ONE declared mode; the provider classifies it. */
+var DiscoveryHitSchema = object({
+	/** Index into the provider's own `getDiscoveryModes()` array. */
+	modeIndex: number().int().min(0),
+	host: string(),
+	port: number().int(),
+	http: object({
+		status: number().int(),
+		headers: record(string(), string()),
+		/** At most 16 KiB. */
+		bodyText: string()
+	}).optional(),
+	mdns: object({
+		instance: string(),
+		host: string(),
+		port: number().int(),
+		txt: record(string(), string())
+	}).optional(),
+	udp: object({ payloadHex: string() }).optional(),
+	wsd: object({
+		xaddrs: array(string()),
+		types: array(string()),
+		scopes: array(string())
+	}).optional()
+});
+/**
 * Candidate handed back from discovery and accepted by
 * `adoptDiscoveredDevice`. Shape mirrors the in-process
 * `DiscoveredDevice` interface used by `DeviceDiscovery`.
@@ -42900,7 +43535,17 @@ var DiscoveryCandidateSchema = object({
 	/** Numeric id of the device this candidate was matched to. Set with `alreadyOnboarded`. */
 	onboardedDeviceId: number().optional(),
 	/** Operator-facing name of the matched device, so the UI can say WHICH one it is. */
-	onboardedName: string().optional()
+	onboardedName: string().optional(),
+	/**
+	* This candidate is an INTEGRATION to set up (a gateway, a hub, a controller),
+	* not a device to adopt. Replaces the `prefilledConfig.setupIntegration` marker,
+	* which is still read for one release.
+	*/
+	setupIntegration: boolean().optional(),
+	/** `stableId` of the gateway candidate this device was found BEHIND. */
+	parentStableId: string().optional(),
+	/** `false` = shown for context but not pickable. Default true. */
+	selectable: boolean().optional()
 });
 /**
 * Flat device summary returned by `createDevice` / `adoptDiscoveredDevice`.
@@ -42953,6 +43598,12 @@ method(_void(), _void(), { kind: "mutation" }), method(_void(), _void(), { kind:
 }), method(object({}), boolean()), method(object({ params: record(string(), unknown()).optional() }), array(DiscoveryCandidateSchema), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), array(DiscoveryModeSchema)), method(object({
+	hits: array(DiscoveryHitSchema),
+	params: record(string(), unknown()).optional()
+}), array(DiscoveryCandidateSchema), {
+	kind: "mutation",
+	auth: "admin"
 }), method(object({}), CreationSchemaOutputSchema), method(object({}), object({ deviceType: _enum(DeviceType).nullable() })), method(object({ candidate: DiscoveryCandidateSchema }), DeviceSummarySchema, {
 	kind: "mutation",
 	auth: "admin"
@@ -43680,17 +44331,23 @@ method(object({
 }), method(object({}), object({ providers: array(object({
 	addonId: string(),
 	label: string()
-})).readonly() }), { auth: "admin" }), method(object({}), object({ groups: array(object({
-	addonId: string(),
-	label: string(),
-	candidates: array(DiscoveryCandidateSchema).readonly(),
-	error: string().nullable()
-})).readonly() }), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({
+})).readonly() }), { auth: "admin" }), method(
+	/** `subnets`: extra CIDRs for THIS scan, on top of the hub's own and the saved list. */
+	object({ subnets: array(string()).optional() }),
+	object({ groups: array(object({
+		addonId: string(),
+		label: string(),
+		candidates: array(DiscoveryCandidateSchema).readonly(),
+		error: string().nullable()
+	})).readonly() }),
+	{
+		kind: "mutation",
+		auth: "admin"
+	}
+), method(object({
 	addonId: string(),
-	params: record(string(), unknown()).optional()
+	params: record(string(), unknown()).optional(),
+	subnets: array(string()).optional()
 }), object({ candidates: array(DiscoveryCandidateSchema).readonly() }), {
 	kind: "mutation",
 	auth: "admin"
@@ -61316,7 +61973,9 @@ method(_void(), array(IntegrationWithStateSchema)), method(object({ id: string()
 	id: string(),
 	settings: record(string(), unknown()),
 	/** Keys the form's schema declares secret (by type) — keychain-stored (D787). */
-	secretKeys: array(string()).optional()
+	secretKeys: array(string()).optional(),
+	/** The integration's own addon applies the change in-process and asks the hub not to respawn it. */
+	skipRestart: boolean().optional()
 }), object({ success: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
@@ -61793,6 +62452,39 @@ var TlsStatusSchema = object({
 		hasCa: boolean()
 	}).nullable()
 });
+/** One provider's ask of the scan engine: the modes it declared. */
+var ScanRequestSchema = object({
+	providerId: string().min(1),
+	modes: array(DiscoveryModeSchema)
+});
+var ScanErrorSchema = object({
+	/** Absent for a failure that is the scan's own (a bad subnet, a socket that would not open). */
+	providerId: string().optional(),
+	/** The mode family that failed (`mdns`, `http-probe`, …). */
+	mode: string().optional(),
+	message: string()
+});
+/** What one scan did, per mode family; the engine logs the same numbers once. */
+var ScanStatsSchema = object({
+	hostsProbed: number().int(),
+	hits: number().int(),
+	timeouts: number().int(),
+	byMode: record(string(), object({
+		probed: number().int(),
+		hits: number().int(),
+		timeouts: number().int()
+	}))
+});
+var ScanNetworkResultSchema = object({
+	hits: array(object({
+		providerId: string(),
+		hit: DiscoveryHitSchema
+	})),
+	/** CIDRs actually covered: the hub's own /24s, the saved list and the per-call list. */
+	subnetsScanned: array(string()),
+	errors: array(ScanErrorSchema),
+	stats: ScanStatsSchema
+});
 method(_void(), ListResultSchema), method(_void(), PreferredSchema), method(object({
 	/**
 	* LEGACY HINT — do not send from new code. Kept optional so clients
@@ -61847,6 +62539,16 @@ method(_void(), ListResultSchema), method(_void(), PreferredSchema), method(obje
 }), method(_void(), object({ pem: string() })), method(_void(), TlsStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({
+	requests: array(ScanRequestSchema),
+	subnets: array(string()).optional()
+}), ScanNetworkResultSchema, {
+	kind: "mutation",
+	auth: "admin",
+	timeoutMs: 9e4
+}), method(_void(), object({ subnets: array(string()) }), { auth: "admin" }), method(object({ subnets: array(string()) }), object({ subnets: array(string()) }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(_void(), TlsStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
@@ -68786,6 +69488,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"addonSettings.getDeclaredSettingsKeys": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"addonSettings.getDeviceSettings": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -68807,6 +69516,13 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"addonSettings.unsetStoredSettingsKeys": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"addonSettings.updateDeviceSettings": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -71222,6 +71938,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"deviceProvider.classifyDiscoveryHits": {
+		capName: "device-provider",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"deviceProvider.createDevice": {
 		capName: "device-provider",
 		capScope: "system",
@@ -71250,6 +71973,13 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"deviceProvider.getDiscoveryModes": {
+		capName: "device-provider",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"deviceProvider.getDiscoveryParamsSchema": {
 		capName: "device-provider",
 		capScope: "system",
@@ -72027,6 +72757,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"keychain.releaseRecordRefs": {
+		capName: "keychain",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"keychain.resolve": {
 		capName: "keychain",
 		capScope: "system",
@@ -72447,6 +73184,13 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"localNetwork.getScanSubnets": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"localNetwork.getTlsStatus": {
 		capName: "local-network",
 		capScope: "system",
@@ -72496,6 +73240,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"localNetwork.scanNetwork": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"localNetwork.setAddressRole": {
 		capName: "local-network",
 		capScope: "system",
@@ -72517,6 +73268,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"localNetwork.setScanSubnets": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"localNetwork.setViewerEndpoints": {
 		capName: "local-network",
 		capScope: "system",
@@ -76738,6 +77496,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"storageAdmin.dropOrphanedKind": {
+		capName: "storage-admin",
+		capScope: "system",
+		addonId: null,
+		access: "delete",
+		role: "admin"
+	},
 	"storageAdmin.listKinds": {
 		capName: "storage-admin",
 		capScope: "system",
@@ -76759,6 +77524,27 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"storageAdmin.scanStaleData": {
+		capName: "storage-admin",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
+	"storageAdmin.staleDataReport": {
+		capName: "storage-admin",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
+	"storageAdmin.unsetStaleSettingsKey": {
+		capName: "storage-admin",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"storageEvictable.evict": {
 		capName: "storage-evictable",
 		capScope: "system",