@camstack/types 1.2.50 → 1.2.51

package/dist/automation/codegen.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Recipe → TypeScript. The half that makes "a visual automation compiles to a
+ * block; it does not get an engine" true rather than aspirational
+ * (design decision 4, `docs/design/2026-08-08-automation-scripts-custom-devices.md`).
+ *
+ * **The generated source is derived, never authoritative.** It is regenerated on
+ * every compile and shown read-only; the RECIPE is what the operator edited.
+ * That resolves the open question §8.2 left to this phase ("is the generated
+ * code stored for audit, or regenerated?"): storing it creates a second copy
+ * that can disagree with the recipe, and a second copy that can disagree is the
+ * failure this whole chapter exists to avoid.
+ *
+ * The recipe travels INSIDE the generated file as `AUTOMATION_RECIPE`, a frozen
+ * JSON literal. That is deliberate and it is not a second store: there is still
+ * exactly one row in `core_blocks`, and the recipe is part of the one artefact
+ * that row holds. It is what lets the editor re-open a visually-authored
+ * automation without `CoreBlock.source` having shipped yet — and when the
+ * `source` union does ship, this literal becomes redundant and is dropped in the
+ * same change that starts persisting the recipe properly.
+ *
+ * Nothing here evaluates anything. The generated code is compiled by esbuild
+ * inside the block pipeline exactly like hand-written code — no `eval`, no
+ * `new Function`, no `vm`, which `scripts/check-no-dynamic-eval.ts` enforces
+ * repo-wide.
+ */
+import type { AutomationRecipe } from './recipe.js';
+export interface GenerateAutomationBlockInput {
+    /** The block's name — the ONE name for the artefact (§2.1). */
+    readonly name: string;
+    readonly recipe: AutomationRecipe;
+}
+/**
+ * Compile a recipe to the TypeScript of a core block.
+ *
+ * Throws when the recipe is out of bounds — generation is not the place to
+ * discover that, but it is the last place it can still be caught before code
+ * that the operator did not author starts running.
+ */
+export declare function generateAutomationBlock(input: GenerateAutomationBlockInput): string;

package/dist/automation/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Automation recipes — the declarative half of a visually-authored automation,
+ * and the generator that turns one into the TypeScript of an ordinary core
+ * block. There is no engine here and there must never be one: the block runner
+ * is the runtime and `core_blocks` is the store.
+ *
+ * This is the module barrel; leaf files inside @camstack/types MUST import from
+ * the deep modules (e.g. `../automation/recipe.js`), never through this file OR
+ * the root barrel (see biome-plugins/no-types-barrel-leaf-import.grit).
+ */
+export type { GenerateAutomationBlockInput } from './codegen.js';
+export { generateAutomationBlock } from './codegen.js';
+export type { AutomationAction, AutomationCondition, AutomationConditionAll, AutomationConditionAny, AutomationConditionExpression, AutomationConditionLeaf, AutomationConditionNot, AutomationConditionOperator, AutomationRecipe, AutomationTrigger, } from './recipe.js';
+export { AutomationActionSchema, AutomationConditionOperatorSchema, AutomationConditionSchema, AutomationRecipeSchema, AutomationTriggerSchema, conditionDepth, countConditionLeaves, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './recipe.js';

package/dist/automation/recipe.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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).
+ *
+ * Three vocabularies, each salvaged rather than invented:
+ *
+ *  - **Triggers** — the only genuinely new surface. Four members, none of which
+ *    touches notification delivery. The NC keeps its four *pipeline* triggers;
+ *    these are device/time triggers and the two sets do not overlap.
+ *  - **Conditions** — `ALL`/`ANY`/`NOT` over two leaf kinds, bounded. The
+ *    expression leaf is the bounded engine at `../expression/`, which is where
+ *    arithmetic between two device fields lives and the only place it lives.
+ *  - **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.
+ *
+ * Bounds are a guard, not a paragraph (§3.2.1): depth ≤ 3, ≤ 32 leaves. They are
+ * enforced by {@link validateRecipeBounds} AND by the schema, so a recipe that
+ * arrives over the wire cannot skip the check that the editor applies.
+ */
+import { z } from 'zod';
+import { type ExpressionBindingSource } from '../expression/binding-source.js';
+/**
+ * Depth of a condition tree, counting the root container as level 1.
+ *
+ * Three is enough and is not arbitrary: `NOT` over a group is always rewritable
+ * by De Morgan (`not(any(a,b))` ≡ `all(not a, not b)`), so the shapes that would
+ * need a fourth level have an equivalent at three. An editor that refuses depth
+ * 4 should offer that rewrite rather than refusing blankly.
+ */
+export declare const MAX_CONDITION_DEPTH = 3;
+/** Leaves per automation. A UI that grows without a bound becomes a language. */
+export declare const MAX_CONDITION_LEAVES = 32;
+/** How a leaf compares a device field to a value. Derived from the field's
+ *  `kind` in `deviceManager.getWireableFields`, never hand-maintained. */
+export declare const AutomationConditionOperatorSchema: z.ZodEnum<{
+    in: "in";
+    gte: "gte";
+    eq: "eq";
+    ne: "ne";
+    gt: "gt";
+    lt: "lt";
+    lte: "lte";
+    contains: "contains";
+}>;
+export type AutomationConditionOperator = z.infer<typeof AutomationConditionOperatorSchema>;
+/** A catalog leaf: one device field compared to one value. */
+export interface AutomationConditionLeaf {
+    readonly kind: 'condition';
+    readonly deviceId: number;
+    readonly cap: string;
+    readonly fieldPath: string;
+    readonly operator: AutomationConditionOperator;
+    readonly value: string | number | boolean | readonly (string | number)[];
+}
+/** The escape hatch: the bounded expression engine over named device bindings. */
+export interface AutomationConditionExpression {
+    readonly kind: 'expression';
+    readonly expr: string;
+    readonly bindings: Readonly<Record<string, ExpressionBindingSource>>;
+}
+export interface AutomationConditionAll {
+    readonly kind: 'all';
+    readonly children: readonly AutomationCondition[];
+}
+export interface AutomationConditionAny {
+    readonly kind: 'any';
+    readonly children: readonly AutomationCondition[];
+}
+export interface AutomationConditionNot {
+    readonly kind: 'not';
+    readonly child: AutomationCondition;
+}
+export type AutomationCondition = AutomationConditionAll | AutomationConditionAny | AutomationConditionNot | AutomationConditionLeaf | AutomationConditionExpression;
+export declare const AutomationConditionSchema: z.ZodType<AutomationCondition>;
+/**
+ * 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.
+ */
+export declare const AutomationTriggerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"device-state">;
+    deviceId: z.ZodNumber;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+    becomes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    edge: z.ZodOptional<z.ZodBoolean>;
+    forMs: z.ZodOptional<z.ZodNumber>;
+    debounceMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"device-event">;
+    category: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    cron: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+}, z.core.$strip>], "kind">;
+export type AutomationTrigger = z.infer<typeof AutomationTriggerSchema>;
+/**
+ * One action step.
+ *
+ * `wait` and `cap` are `NcRuleActionSchema`'s two members, kept structurally
+ * identical so `NcRuleActionRunner` runs them unchanged — its device-scope
+ * check, stop-at-first-failure and per-sequence throttle are the whole reason
+ * to reuse it, and none of them are re-implemented here.
+ *
+ * **The one divergence, and it is forced.** `NcRuleActionSchema.cap.deviceId` is
+ * a literal `z.number().int()`, and the NC runner's own `RunSequencesInput`
+ * documents its subject device as *"for the log tag, never for routing"*. So an
+ * NC action can never target the device that triggered it — which is fine for
+ * the NC (its rules already scope to a device) and fatal for an automation
+ * ("sound the siren of the camera that saw the person"). `deviceId` therefore
+ * also accepts `{ $var }`, resolved from the run's `vars` bag BEFORE the runner
+ * is called. The runner still receives a number and is untouched; the
+ * resolution is the recipe's job, not the runner's.
+ */
+export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"wait">;
+    seconds: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cap">;
+    deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        $var: z.ZodString;
+    }, z.core.$strip>]>;
+    cap: z.ZodString;
+    method: z.ZodString;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"code">;
+    code: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type AutomationAction = z.infer<typeof AutomationActionSchema>;
+export declare const AutomationRecipeSchema: z.ZodObject<{
+    triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"device-state">;
+        deviceId: z.ZodNumber;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+        becomes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        edge: z.ZodOptional<z.ZodBoolean>;
+        forMs: z.ZodOptional<z.ZodNumber>;
+        debounceMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"device-event">;
+        category: z.ZodString;
+        deviceId: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"schedule">;
+        cron: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"manual">;
+    }, z.core.$strip>], "kind">>;
+    conditions: z.ZodOptional<z.ZodType<AutomationCondition, unknown, z.core.$ZodTypeInternals<AutomationCondition, unknown>>>;
+    actions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"wait">;
+        seconds: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cap">;
+        deviceId: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            $var: z.ZodString;
+        }, z.core.$strip>]>;
+        cap: z.ZodString;
+        method: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"code">;
+        code: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type AutomationRecipe = z.infer<typeof AutomationRecipeSchema>;
+/** Depth of a tree, root container = 1. A bare leaf is depth 1. */
+export declare function conditionDepth(cond: AutomationCondition): number;
+/** Leaves only — containers do not count toward the leaf budget. */
+export declare function countConditionLeaves(cond: AutomationCondition): number;
+/**
+ * Author-time bounds check. Returns `null` when the recipe is legal, else a
+ * message naming the bound it broke — the editor shows it verbatim, so it has
+ * to read like something an operator can act on.
+ */
+export declare function validateRecipeBounds(recipe: AutomationRecipe): string | null;

package/dist/capabilities/core-blocks.cap.d.ts

@@ -30,6 +30,23 @@ import { type InferProvider } from './capability-definition.js';
  * too many — a drift would show as a logs pane that is simply always empty.
  */
 export declare const CORE_BLOCK_ADDON_PREFIX = "core-block-";
+/**
+ * The builtin's own addon id — and, because of that, the OWNER of the
+ * integration every block's devices hang from.
+ *
+ * A block cannot own one. Every integration read is gated on the installed-addon
+ * set (`addon-registry.service.ts` → `createFilteredRegistry`) and a block's
+ * `core-block-<uuid>` is never in it, so its `getIntegrationByAddonId` answers
+ * null forever while the write succeeds — one invisible, undeletable row per
+ * start. `core-blocks` IS installed, so it reconciles one shared integration and
+ * a block names it by id (`DeclaredDevicesSpec.integrationId`), minting nothing.
+ *
+ * Exported from the contract, next to the runner prefix and for the same reason:
+ * a block reads it as
+ * `ctx.api.integrations.getByAddonId.query({ addonId: CORE_BLOCKS_ADDON_ID })`,
+ * so a second copy of the string is a block that silently declares into nowhere.
+ */
+export declare const CORE_BLOCKS_ADDON_ID = "core-blocks";
 /** The addon/runner id a block's process runs under. */
 export declare function coreBlockAddonId(blockId: string): string;
 /** The block id behind a generated addon/runner id, or null when the id belongs

package/dist/capabilities/index.d.ts

@@ -38,7 +38,7 @@ export { cameraStreamsCapability, type ICameraStreamsProvider, type PickedCamStr
 export { extractNestedAddonId, isArrayOutputSchema, isCollectionArrayMethod, isObjectInput, isVoidInput, kebabToCamel, looseSchema, objectInputDeclaresAddonId, procedureAuthKey, } from './cap-router-predicates.js';
 export type { CapabilityDefinition, CapabilityEventSchema, CapabilityMethodAuth, CapabilityMethodCaller, CapabilityMethodKind, CapabilityMethodOptions, CapabilityMethodSchema, CapabilityMountHint, CapabilityMountKind, CapabilityStatusItemArray, CapabilityStatusKind, CapabilityStatusSchema, CapCaller, DeviceConfigDerivedFormUi, DeviceConfigSpec, DeviceConfigUiSpec, DeviceConfigWidgetUi, DeviceSettingsContribution, InferDeviceProxyCap, InferEvents, InferName, InferNativeProvider, InferProvider, InferRuntimeState, ProviderKind, UiContribution, UiContributionKind, UiContributionRemote, } from './capability-definition.js';
 export { DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, event, expandCapMethods, isDeviceConfigCap, method, resolveCapMount, } from './capability-definition.js';
-export { CORE_BLOCK_ADDON_PREFIX, type CoreBlock, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockInput, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockIdFromAddonId, coreBlocksCapability, type ICoreBlocksProvider, } from './core-blocks.cap.js';
+export { CORE_BLOCK_ADDON_PREFIX, CORE_BLOCKS_ADDON_ID, type CoreBlock, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockInput, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockIdFromAddonId, coreBlocksCapability, type ICoreBlocksProvider, } from './core-blocks.cap.js';
 export * from './custom-actions.js';
 export type { CustomModelDescriptor, ICustomModelRegistryProvider, } from './custom-model-registry.cap.js';
 export { CustomModelDescriptorSchema, customModelRegistryCapability, } from './custom-model-registry.cap.js';

package/dist/capabilities/mqtt-broker.cap.d.ts

@@ -149,4 +149,4 @@ export declare const mqttBrokerCapability: {
     };
 };
 export type IMqttBrokerProvider = InferProvider<typeof mqttBrokerCapability>;
-export { BrokerInfoSchema, BrokerConnectionDetailsSchema, AddBrokerInputSchema, StartEmbeddedInputSchema, StatusSchema as MqttBrokerStatusSchema, };
+export { AddBrokerInputSchema, BrokerConnectionDetailsSchema, BrokerInfoSchema, StartEmbeddedInputSchema, StatusSchema as MqttBrokerStatusSchema, };

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -403,6 +403,7 @@ declare const TrackSchema: z.ZodObject<{
         mediaKey: z.ZodString;
     }, z.core.$strip>>>;
     zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     totalDistance: z.ZodNumber;
     state: z.ZodEnum<{
@@ -1047,6 +1048,7 @@ declare const RecentTracksPageSchema: z.ZodObject<{
             mediaKey: z.ZodString;
         }, z.core.$strip>>>;
         zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
         totalDistance: z.ZodNumber;
         state: z.ZodEnum<{
@@ -1291,6 +1293,7 @@ export declare const pipelineAnalyticsCapability: {
                 mediaKey: z.ZodString;
             }, z.core.$strip>>>;
             zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             totalDistance: z.ZodNumber;
             state: z.ZodEnum<{
@@ -1382,6 +1385,7 @@ export declare const pipelineAnalyticsCapability: {
                 mediaKey: z.ZodString;
             }, z.core.$strip>>>;
             zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             totalDistance: z.ZodNumber;
             state: z.ZodEnum<{
@@ -1495,6 +1499,7 @@ export declare const pipelineAnalyticsCapability: {
                 mediaKey: z.ZodString;
             }, z.core.$strip>>>;
             zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             totalDistance: z.ZodNumber;
             state: z.ZodEnum<{
@@ -1604,6 +1609,7 @@ export declare const pipelineAnalyticsCapability: {
                     mediaKey: z.ZodString;
                 }, z.core.$strip>>>;
                 zonesVisited: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+                zoneNames: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
                 classes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
                 totalDistance: z.ZodNumber;
                 state: z.ZodEnum<{

package/dist/device/declared-device.d.ts

@@ -109,8 +109,29 @@ export interface DeviceDeclaration<T extends IDevice = IDevice> {
 /** Where the declaration is owned. */
 export type DeclarationPlacement = 'hub' | 'this-node';
 export interface DeclaredDevicesSpec {
-    /** Display name of the FIXED integration the devices hang from. */
+    /** Display name of the FIXED integration the devices hang from. Unused when
+     *  {@link integrationId} names an existing one. */
     readonly integrationName: string;
+    /**
+     * Hang the devices off an integration that ALREADY EXISTS, owned by somebody
+     * else. When set, nothing is minted and `fixed` is not re-asserted — the
+     * owner of that integration is responsible for both.
+     *
+     * This exists because a declarer is not always an installed addon. Every
+     * integration READ is filtered by `installedAddonIds`
+     * (`addon-registry.service.ts` → `createFilteredRegistry`), and a core
+     * block's addon id (`core-block-<uuid>`) is never in that set: its
+     * `getIntegration` answers null forever, so the mint branch runs on every
+     * start and leaks a row `listIntegrations` hides and `deleteIntegration`
+     * refuses to delete. Measured on the live hub, 2026-08-09 — two starts of one
+     * block left `int_0021` and `int_0022` orphaned and unreachable.
+     *
+     * A block therefore hangs its devices off the integration the `core-blocks`
+     * builtin owns. Ownership of the DEVICE is unaffected: that is
+     * `(addonId, stableId)`, and `listOwnDevices` stays addon-scoped, which is
+     * what keeps one block's withdrawal sweep away from another's devices.
+     */
+    readonly integrationId?: string;
     readonly devices: readonly DeviceDeclaration[];
     /**
      * Default `'hub'`: a declaration is cluster state and belongs to the node

package/dist/index.d.ts

@@ -112,6 +112,8 @@ export * from './types/pipeline.js';
 export type { AvailableEngine, PipelineAddonSchema, PipelineDefaultStep, PipelineModelOption, PipelineSchema, PipelineSlotSchema, PipelineTemplate, PipelineTemplateStep, TemplateValidationResult, } from './types/pipeline-schema.js';
 export * from './types/pipeline-step.js';
 export * from './types/tracked.js';
+export type { AutomationAction, AutomationCondition, AutomationConditionAll, AutomationConditionAny, AutomationConditionExpression, AutomationConditionLeaf, AutomationConditionNot, AutomationConditionOperator, AutomationRecipe, AutomationTrigger, GenerateAutomationBlockInput, } from './automation/index.js';
+export { AutomationActionSchema, AutomationConditionOperatorSchema, AutomationConditionSchema, AutomationRecipeSchema, AutomationTriggerSchema, conditionDepth, countConditionLeaves, generateAutomationBlock, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, validateRecipeBounds, } from './automation/index.js';
 export * from './cap-call-context.js';
 export * from './capabilities/index.js';
 export { APPLE_SA_TO_MACRO, AUDIO_MACRO_LABELS, getAudioMacroClassIds, mapAudioLabelToMacro, YAMNET_TO_MACRO, } from './catalogs/audio-classmap.js';