@camstack/types 1.1.20 → 1.1.22

package/dist/capabilities/motion-detection.cap.d.ts

@@ -47,7 +47,7 @@ export declare const motionDetectionCapability: {
     readonly methods: {
         readonly analyze: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
-            frame: z.ZodObject<{
+            frame: z.ZodOptional<z.ZodObject<{
                 data: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
                 format: z.ZodEnum<{
                     jpeg: "jpeg";
@@ -59,7 +59,25 @@ export declare const motionDetectionCapability: {
                 width: z.ZodNumber;
                 height: z.ZodNumber;
                 timestamp: z.ZodNumber;
-            }, z.core.$strip>;
+            }, z.core.$strip>>;
+            frameHandle: z.ZodOptional<z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
             detected: z.ZodBoolean;
             regionCount: z.ZodNumber;

package/dist/capabilities/pet-feeder.cap.d.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+import { DeviceType } from '../device/device-type.js';
+/**
+ * PetKit pet-feeder cap. Models the control + telemetry surface of a
+ * cloud-connected smart feeder (Fresh Element / Mini / D3 / D4 / D4S
+ * Gemini / D4H / D4SH) as a single coherent slice — bowl food level,
+ * battery, desiccant life, feeding state + the four persisted settings
+ * (child-lock / indicator-light / feed-sound / volume).
+ *
+ * Sources: native PetKit (`nodepetkit` `FeederDevice`). Reusable by any
+ * feeder integration that speaks the same food/desiccant/hopper surface.
+ *
+ * `kind: 'poll'` — PetKit exposes only a cloud REST API (no push
+ * channel), so the provider refreshes the slice on a poll interval and
+ * eagerly after every command.
+ *
+ * Dual-hopper feeders (D4S/D4SH) split the bowl into two independent
+ * hoppers. `isDualHopper` gates the two-hopper UI; `food1`/`food2` carry
+ * the per-hopper levels (both `null` on single-hopper models, where
+ * `foodLevel` is the single reading). The manual-feed portion honours the
+ * PetKit hardware range 4–200 g in 1 g steps.
+ *
+ * Device status is exposed both raw and decoded, mirroring PetKit's HA
+ * integration (RobertD502/py-petkit-api). `status` is the connectivity /
+ * power enum (`normal` / `offline` / `on_batteries`); `error` is the
+ * decoded human-readable fault message (null / `no_error` = healthy);
+ * `errorCode` keeps the raw device integer (0 / null = no error) so a
+ * provider that only has the numeric code stays lossless. A provider maps
+ * the library's fields onto these; any it cannot determine stays `null`.
+ */
+/** PetKit manual-feed portion bounds (grams). Mirrors the HA `manual_feed`
+ *  number entity (min 4, max 200, step 1, device_class weight). */
+export declare const PET_FEEDER_MANUAL_FEED_MIN = 4;
+export declare const PET_FEEDER_MANUAL_FEED_MAX = 200;
+/**
+ * Feeder connectivity / power status — mirrors the HA petkit device-status
+ * enum: `normal` (online, mains), `offline` (not reaching PetKit cloud),
+ * `on_batteries` (running on battery backup). `null` until first reported.
+ */
+export declare const PetFeederDeviceStatusSchema: z.ZodEnum<{
+    offline: "offline";
+    normal: "normal";
+    on_batteries: "on_batteries";
+}>;
+export type PetFeederDeviceStatus = z.infer<typeof PetFeederDeviceStatusSchema>;
+export declare const PetFeederStatusSchema: z.ZodObject<{
+    foodLevel: z.ZodNullable<z.ZodNumber>;
+    food1: z.ZodNullable<z.ZodNumber>;
+    food2: z.ZodNullable<z.ZodNumber>;
+    lowFood: z.ZodBoolean;
+    batteryPower: z.ZodNullable<z.ZodNumber>;
+    desiccantLeftDays: z.ZodNullable<z.ZodNumber>;
+    feeding: z.ZodBoolean;
+    status: z.ZodNullable<z.ZodEnum<{
+        offline: "offline";
+        normal: "normal";
+        on_batteries: "on_batteries";
+    }>>;
+    error: z.ZodNullable<z.ZodString>;
+    errorCode: z.ZodNullable<z.ZodNumber>;
+    isDualHopper: z.ZodBoolean;
+    childLock: z.ZodBoolean;
+    indicatorLight: z.ZodBoolean;
+    feedSound: z.ZodBoolean;
+    volume: z.ZodNumber;
+    lastFetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type PetFeederStatus = z.infer<typeof PetFeederStatusSchema>;
+export declare const petFeederCapability: {
+    readonly name: "pet-feeder";
+    readonly scope: "device";
+    readonly deviceNative: true;
+    readonly mode: "singleton";
+    readonly deviceTypes: readonly [DeviceType.PetFeeder];
+    readonly methods: {
+        /**
+         * Dispense food now. Single-hopper feeders take `grams`; dual-hopper
+         * feeders (D4S/D4SH) accept `hopper1`/`hopper2` to target one or both
+         * hoppers. All portions honour the 4–200 g hardware range. At least
+         * one of the three must be present — the provider rejects an empty
+         * request.
+         */
+        readonly feed: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            grams: z.ZodOptional<z.ZodNumber>;
+            hopper1: z.ZodOptional<z.ZodNumber>;
+            hopper2: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Cancel an in-progress manual feed. */
+        readonly cancelFeed: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Reset the desiccant "days remaining" counter after replacing it. */
+        readonly resetDesiccant: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Mark a hopper as refilled (D4H/D4S/D4SH). */
+        readonly markFoodReplenished: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Call the pet with the recorded prompt (D3). */
+        readonly callPet: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Play a stored sound by id (D3 / D4H / D4SH). */
+        readonly playSound: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            soundId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Toggle the child-lock (manual-lock) setting. */
+        readonly setChildLock: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            on: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Toggle the front indicator light. */
+        readonly setIndicatorLight: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            on: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Toggle the dispense chime. */
+        readonly setFeedSound: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            on: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Set the speaker / prompt volume level. */
+        readonly setVolume: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            level: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+    };
+    readonly status: {
+        readonly schema: z.ZodObject<{
+            foodLevel: z.ZodNullable<z.ZodNumber>;
+            food1: z.ZodNullable<z.ZodNumber>;
+            food2: z.ZodNullable<z.ZodNumber>;
+            lowFood: z.ZodBoolean;
+            batteryPower: z.ZodNullable<z.ZodNumber>;
+            desiccantLeftDays: z.ZodNullable<z.ZodNumber>;
+            feeding: z.ZodBoolean;
+            status: z.ZodNullable<z.ZodEnum<{
+                offline: "offline";
+                normal: "normal";
+                on_batteries: "on_batteries";
+            }>>;
+            error: z.ZodNullable<z.ZodString>;
+            errorCode: z.ZodNullable<z.ZodNumber>;
+            isDualHopper: z.ZodBoolean;
+            childLock: z.ZodBoolean;
+            indicatorLight: z.ZodBoolean;
+            feedSound: z.ZodBoolean;
+            volume: z.ZodNumber;
+            lastFetchedAt: z.ZodNumber;
+        }, z.core.$strip>;
+        readonly kind: "poll";
+    };
+    /**
+     * Runtime-state slice — mirrored by the kernel. UI feeder cards read
+     * the full slice via `device.state.petFeeder.value` and refresh on
+     * every poll without re-querying the provider.
+     */
+    readonly runtimeState: z.ZodObject<{
+        foodLevel: z.ZodNullable<z.ZodNumber>;
+        food1: z.ZodNullable<z.ZodNumber>;
+        food2: z.ZodNullable<z.ZodNumber>;
+        lowFood: z.ZodBoolean;
+        batteryPower: z.ZodNullable<z.ZodNumber>;
+        desiccantLeftDays: z.ZodNullable<z.ZodNumber>;
+        feeding: z.ZodBoolean;
+        status: z.ZodNullable<z.ZodEnum<{
+            offline: "offline";
+            normal: "normal";
+            on_batteries: "on_batteries";
+        }>>;
+        error: z.ZodNullable<z.ZodString>;
+        errorCode: z.ZodNullable<z.ZodNumber>;
+        isDualHopper: z.ZodBoolean;
+        childLock: z.ZodBoolean;
+        indicatorLight: z.ZodBoolean;
+        feedSound: z.ZodBoolean;
+        volume: z.ZodNumber;
+        lastFetchedAt: z.ZodNumber;
+    }, z.core.$strip>;
+};
+export type IPetFeederProvider = InferProvider<typeof petFeederCapability>;

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

@@ -710,11 +710,20 @@ export declare const pipelineExecutorCapability: {
          * legacy call shape used by existing benchmark code; once all
          * callers pass it explicitly we make it required.
          *
-         * Exactly one of `frame`, `imageBase64`, `referenceImage` must be
-         * provided:
+         * Exactly one of `frame`, `frameHandle`, `imageBase64`,
+         * `referenceImage` must be provided:
          *  - `frame`: runtime dispatch path (runner → decoded broker frame).
          *    Carries the raw buffer, dimensions, and format; the executor
          *    uses it directly without base64 round-tripping.
+         *  - `frameHandle` (CB5): a zero-pixel shm `FrameHandle` for the SAME
+         *    decoded frame. Both runner and executor are hub-local processes
+         *    sharing `/dev/shm`, so the executor maps the named segment and
+         *    reads the pixels back zero-copy — eliminating the ~1.2MB
+         *    re-serialisation over UDS/MsgPack the `frame` path pays per call.
+         *    High-risk: the FrameRing is a latest-wins seqlock with no
+         *    refcount, so a recycled slot yields a null read; the executor
+         *    then degrades to an empty result and the runner ships pixels via
+         *    `frame` as the fallback (queue-depth gated on the runner side).
          *  - `imageBase64`: one-shot test path (benchmark ImageTab).
          *  - `referenceImage`: named file from the reference-image store.
          */
@@ -748,6 +757,24 @@ export declare const pipelineExecutorCapability: {
                 height: z.ZodNumber;
                 timestamp: z.ZodNumber;
             }, z.core.$strip>>;
+            frameHandle: z.ZodOptional<z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>>;
             imageBase64: z.ZodOptional<z.ZodString>;
             image: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
             referenceImage: z.ZodOptional<z.ZodString>;

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

@@ -459,7 +459,10 @@ export declare const pipelineOrchestratorCapability: {
     readonly methods: {
         /**
          * Pin a camera's pipeline to a specific agent (L1 affinity).
-         * The orchestrator re-evaluates the assignment immediately.
+         * The orchestrator re-evaluates the assignment immediately and persists
+         * the pin under the canonical `pipelineNodeId` device-store key (the
+         * legacy `preferredAgent` key is nulled on write and kept only as a
+         * read-only fallback for stores written before the unification).
          */
         readonly assignPipeline: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -469,8 +472,9 @@ export declare const pipelineOrchestratorCapability: {
         }, z.core.$strip>, "mutation">;
         /**
          * Clear a camera's pipeline pin and let the auto-balancer re-pick
-         * the optimal agent. The orchestrator persists `preferredAgent=null`
-         * (and `pipelineNodeId='auto'`), then re-runs the balancer with the
+         * the optimal agent. The orchestrator persists the canonical
+         * `pipelineNodeId='auto'` (and nulls the legacy `preferredAgent`),
+         * then re-runs the balancer with the
          * cached `RunnerCameraConfig` and migrates only when the chosen
          * node differs. The camera stays in `getPipelineAssignments()` —
          * just with `pinned=false`. If no runner is currently available

package/dist/capabilities/platform-probe.cap.d.ts

@@ -264,9 +264,9 @@ export declare const platformProbeCapability: {
                 directml: "directml";
                 webgpu: "webgpu";
             }>>>;
-            nodeId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
             preferred: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            rationale: z.ZodString;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Hardware-encoder probe — see Task #185. Cached after first call.

package/dist/capabilities/schemas/streaming-shared.d.ts

@@ -49,8 +49,8 @@ export declare const CameraStreamSchema: z.ZodObject<{
 export type CameraStream = z.infer<typeof CameraStreamSchema>;
 export declare const ProfileSlotStatusSchema: z.ZodEnum<{
     error: "error";
-    idle: "idle";
     unassigned: "unassigned";
+    idle: "idle";
     connecting: "connecting";
     streaming: "streaming";
 }>;
@@ -66,8 +66,8 @@ export declare const ProfileSlotSchema: z.ZodObject<{
     sourceCamStreamId: z.ZodNullable<z.ZodString>;
     status: z.ZodEnum<{
         error: "error";
-        idle: "idle";
         unassigned: "unassigned";
+        idle: "idle";
         connecting: "connecting";
         streaming: "streaming";
     }>;

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

@@ -413,8 +413,8 @@ export declare const streamBrokerCapability: {
             sourceCamStreamId: z.ZodNullable<z.ZodString>;
             status: z.ZodEnum<{
                 error: "error";
-                idle: "idle";
                 unassigned: "unassigned";
+                idle: "idle";
                 connecting: "connecting";
                 streaming: "streaming";
             }>;

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

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
-import type { DeviceType } from './device-type.js';
 import type { IDevice } from './device.js';
+import type { DeviceType } from './device-type.js';
 import type { SourceInfo } from './source-info.js';
 export interface DeviceManualCreation {
     getChildCreationSchema(type: DeviceType): z.ZodObject<z.core.$ZodLooseShape>;
@@ -127,7 +127,22 @@ export interface DeviceLinkGlobalSource {
     readonly cap: string;
     readonly fieldPath: string;
 }
-export type DeviceLinkSource = DeviceLinkFieldSource | DeviceLinkLiteralSource | DeviceLinkGlobalSource;
+/** The source kinds a single expression BINDING may use — a sibling FIELD, a
+ *  per-device LITERAL, or a GLOBAL device field. Never another expression:
+ *  bindings do not nest, so an expression cannot reference another expression. */
+export type DeviceLinkExpressionBinding = DeviceLinkFieldSource | DeviceLinkLiteralSource | DeviceLinkGlobalSource;
+/** Expression source (Stage X): compute the target field from N named source
+ *  bindings via a safe, non-Turing-complete infix expression (see
+ *  `packages/types/src/expression/`). Each binding resolves to an
+ *  `ExpressionValue` and is exposed to the expression under its record key.
+ *  `now` (epoch ms) is auto-injected and is a reserved binding name. The
+ *  evaluated result flows through `transform` exactly like a scalar source. */
+export interface DeviceLinkExpressionSource {
+    readonly kind: 'expression';
+    readonly expr: string;
+    readonly bindings: Readonly<Record<string, DeviceLinkExpressionBinding>>;
+}
+export type DeviceLinkSource = DeviceLinkFieldSource | DeviceLinkLiteralSource | DeviceLinkGlobalSource | DeviceLinkExpressionSource;
 /** The target field a link writes: a dot-path into the target cap's status. */
 export interface DeviceLinkTarget {
     readonly cap: string;
@@ -156,6 +171,42 @@ export interface DeviceLink {
     readonly transform?: DeviceLinkTransform;
 }
 export type DeviceLinks = readonly DeviceLink[];
+/** Per-cap display refinement inside a `DeviceDisplayOverride` — unit/precision
+ *  only (icon/label/hidden are device-level). Keyed by cap name for devices
+ *  carrying several numeric caps (e.g. power-meter). */
+export interface DeviceCapDisplayOverride {
+    readonly unit?: string;
+    readonly precision?: number;
+}
+/** Operator-authored per-device display override. Rides the `DeviceMeta`
+ *  lifecycle (persist/preserve/project/pre-seed) — deliberately NOT a new
+ *  cap/store. All fields optional; an empty object is equivalent to absent.
+ *  `unit` triggers render-time conversion when same-dimension as the live
+ *  slice unit (storage stays in source units); `precision` applies AFTER
+ *  conversion; `hidden` removes the device from list surfaces (distinct from
+ *  the HA-only accessories-cap `hiddenChildIds` mechanism). */
+export interface DeviceDisplayOverride {
+    /** Key into ui-library's display icon registry. */
+    readonly icon?: string;
+    /** Overrides the `DEVICE_ROLE_META` label (NOT the device name). */
+    readonly label?: string;
+    /** Canonical spelling (`normalizeUnit` applied at write). */
+    readonly unit?: string;
+    /** Int 0-10, same contract as the slice `precision` field. */
+    readonly precision?: number;
+    readonly hidden?: boolean;
+    readonly perCap?: Readonly<Record<string, DeviceCapDisplayOverride>>;
+}
+/** Operator-authored per-role display default (unit/precision/icon), keyed by
+ *  `DeviceRole` string. Resolution merges these UNDER any per-device
+ *  `DeviceDisplayOverride`. Stored whole-record (full replace) in the
+ *  device-manager addon store's `roleDisplayDefaults` key — NOT on any device's
+ *  meta row. */
+export interface RoleDisplayDefault {
+    readonly unit?: string;
+    readonly precision?: number;
+    readonly icon?: string;
+}
 export interface DeviceMeta {
     readonly id: number;
     readonly stableId: string;
@@ -207,6 +258,12 @@ export interface DeviceMeta {
      *  cap field). Same create/persist/project/restore lifecycle as `childLayout`.
      *  Absent ⇒ no links. Overlaid onto the target cap's `getStatus` at read time. */
     readonly deviceLinks?: DeviceLinks;
+    /** Operator-authored per-device display override (icon/label/unit/precision/
+     *  hidden). Same create/persist/project/restore lifecycle as `deviceLinks`.
+     *  Absent ⇒ no override; the renderer falls back to role default → live slice
+     *  → canonical unit. Applied at RENDER time only — storage stays in source
+     *  units. */
+    readonly display?: DeviceDisplayOverride;
 }
 /**
  * Initial meta a provider supplies on `onCreateDevice`. Differs
@@ -237,6 +294,8 @@ export interface InitialDeviceMeta {
     readonly childLayout?: ChildLayout;
     /** Cross-device field wirings set at create. Mirrors `DeviceMeta.deviceLinks`. */
     readonly deviceLinks?: DeviceLinks;
+    /** Per-device display override set at create. Mirrors `DeviceMeta.display`. */
+    readonly display?: DeviceDisplayOverride;
 }
 /**
  * Single-call payload returned by `BaseDeviceProvider.onCreateDevice`.

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

@@ -81,7 +81,14 @@ export declare enum DeviceType {
     Container = "container",
     /** Single still-image entity (HA `image.*`). Read-only display of an
      *  `entity_picture` signed URL the browser loads directly. `image` cap. */
-    Image = "image"
+    Image = "image",
+    /** Smart pet feeder — cloud-connected food dispenser with a bowl food
+     *  level, battery, desiccant life, feeding state and manual-feed /
+     *  call-pet / maintenance actions. Installed with the `pet-feeder` cap;
+     *  dual-hopper models (D4S/D4SH) expose per-hopper portions. Sources:
+     *  native PetKit (`nodepetkit` `FeederDevice`), reusable by other feeder
+     *  integrations sharing the same food/desiccant/hopper surface. */
+    PetFeeder = "pet-feeder"
 }
 export declare enum DeviceFeature {
     BatteryOperated = "battery-operated",

package/dist/device/index.d.ts

@@ -11,7 +11,7 @@ export type { IDevice } from './device.js';
 export { DEVICE_PROFILES, BATTERY_DEVICE_PROFILE, deviceMatchesProfile, resolveDeviceProfile, } from './device-profile.js';
 export type { DeviceProfile, DeviceProfileMatch, DeviceProfileDefaults, PipelinePhaseMode, } from './device-profile.js';
 export type { ICameraDevice, StreamSourceEntry } from './camera-device.js';
-export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec, ChildLayout, ChildLayoutEntry, DeviceLinkFieldSource, DeviceLinkLiteralSource, DeviceLinkGlobalSource, DeviceLinkSource, DeviceLinkTarget, DeviceLinkTransform, DeviceLink, DeviceLinks, } from './device-management.js';
+export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec, ChildLayout, ChildLayoutEntry, DeviceLinkFieldSource, DeviceLinkLiteralSource, DeviceLinkGlobalSource, DeviceLinkExpressionBinding, DeviceLinkExpressionSource, DeviceLinkSource, DeviceLinkTarget, DeviceLinkTransform, DeviceLink, DeviceLinks, } from './device-management.js';
 export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';
 export { createRuntimeStateBridge } from './runtime-state-helpers.js';

package/dist/expression/ast.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AST for the safe expression mini-language.
+ *
+ * SECURITY BY CONSTRUCTION (spec §4 rule 3): there is deliberately NO member
+ * node, NO index node, NO assignment node and NO lambda/function node in this
+ * union. `a.b`, `a["b"]`, `a = b` and `() => …` are therefore UNREPRESENTABLE —
+ * `__proto__` / `constructor` / `prototype` traversal is impossible at the type
+ * level, not by a runtime denylist. `ExpressionCallNode.callee` is a plain
+ * string (a builtin name), never a node, so a computed call like `(min)(1)` is
+ * unparseable.
+ *
+ * The value domain is the four JSON primitives — no objects, arrays or
+ * functions ever flow through the evaluator.
+ */
+/** The only value types the engine produces or consumes. */
+export type ExpressionValue = number | string | boolean | null;
+export type ExpressionBinaryOperator = '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '<' | '<=' | '>' | '>=';
+export type ExpressionLogicalOperator = '&&' | '||';
+export type ExpressionUnaryOperator = '-' | '!';
+export interface ExpressionLiteralNode {
+    readonly kind: 'literal';
+    readonly value: ExpressionValue;
+}
+export interface ExpressionIdentifierNode {
+    readonly kind: 'identifier';
+    readonly name: string;
+}
+export interface ExpressionUnaryNode {
+    readonly kind: 'unary';
+    readonly op: ExpressionUnaryOperator;
+    readonly operand: ExpressionNode;
+}
+export interface ExpressionBinaryNode {
+    readonly kind: 'binary';
+    readonly op: ExpressionBinaryOperator;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+export interface ExpressionLogicalNode {
+    readonly kind: 'logical';
+    readonly op: ExpressionLogicalOperator;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+export interface ExpressionConditionalNode {
+    readonly kind: 'conditional';
+    readonly test: ExpressionNode;
+    readonly consequent: ExpressionNode;
+    readonly alternate: ExpressionNode;
+}
+export interface ExpressionCallNode {
+    readonly kind: 'call';
+    readonly callee: string;
+    readonly args: readonly ExpressionNode[];
+}
+export type ExpressionNode = ExpressionLiteralNode | ExpressionIdentifierNode | ExpressionUnaryNode | ExpressionBinaryNode | ExpressionLogicalNode | ExpressionConditionalNode | ExpressionCallNode;

package/dist/expression/builtins.d.ts

@@ -0,0 +1,19 @@
+import type { ExpressionValue } from './ast.js';
+/** Optional runtime hooks the evaluator threads through to builtins. Stage U
+ *  installs the real unit-conversion table here; absent → the `convert` stub. */
+export interface ExpressionEvalHooks {
+    /** Convert `value` from unit `from` to unit `to`; `null` when the pair is
+     *  not convertible. Absent hook → `convert` uses its identity-only stub. */
+    readonly convert?: (value: number, from: string, to: string) => number | null;
+}
+export interface ExpressionBuiltin {
+    readonly minArgs: number;
+    /** `Number.POSITIVE_INFINITY` for variadic builtins. */
+    readonly maxArgs: number;
+    readonly apply: (args: readonly ExpressionValue[], hooks: ExpressionEvalHooks) => ExpressionValue;
+}
+/** Frozen, null-prototype builtin table. */
+export declare const EXPRESSION_BUILTINS: Readonly<Record<string, ExpressionBuiltin>>;
+/** The set of valid builtin names — used by the parser to reject unknown
+ *  callees at parse time (immediate author feedback). */
+export declare const EXPRESSION_BUILTIN_NAMES: ReadonlySet<string>;

package/dist/expression/compile.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedExpression } from './parser.js';
+export type CompileResult = {
+    readonly ok: true;
+    readonly parsed: ParsedExpression;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Compile `source` to a `ParsedExpression`, throwing `ExpressionParseError`
+ *  on failure. LRU/negative-cached. */
+export declare function compileExpression(source: string): ParsedExpression;
+/** Compile `source`, returning a discriminated result instead of throwing.
+ *  Used by read paths that must degrade rather than raise. LRU/negative-cached. */
+export declare function compileExpressionSafe(source: string): CompileResult;
+/** Test-only: clear the module-level cache. Not part of the public engine
+ *  surface — used to make cache-behaviour assertions deterministic. */
+export declare function __clearExpressionCompileCache(): void;

package/dist/expression/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error types for the safe expression engine. Two distinct classes so callers
+ * can tell a compile-time (grammar) failure from a runtime (evaluation)
+ * failure — both are non-fatal to the host: read paths degrade to "skip link".
+ */
+/** Thrown by the tokenizer / parser. Carries a 0-based source `position` when
+ *  the failure is anchored to a character (author-facing inline feedback). */
+export declare class ExpressionParseError extends Error {
+    readonly position?: number;
+    constructor(message: string, position?: number);
+}
+/** Thrown by the evaluator (unknown identifier, type mismatch, non-finite
+ *  result, unknown builtin, step-budget exceeded). */
+export declare class ExpressionEvalError extends Error {
+    constructor(message: string);
+}

package/dist/expression/evaluator.d.ts

@@ -0,0 +1,14 @@
+import { type ExpressionEvalHooks } from './builtins.js';
+import type { ExpressionNode, ExpressionValue } from './ast.js';
+export interface ExpressionEvalOptions {
+    readonly hooks?: ExpressionEvalHooks;
+    readonly maxSteps?: number;
+}
+/** Build a null-prototype scope from own-enumerable binding entries. Inherited
+ *  keys of the input (e.g. from a `{__proto__: {...}}` payload) are NOT copied,
+ *  so nothing smuggles in via the prototype chain. */
+export declare function createExpressionScope(bindings: Readonly<Record<string, ExpressionValue>>): Record<string, ExpressionValue>;
+/** Evaluate an AST node against a scope. Throws `ExpressionEvalError` on any
+ *  runtime failure (unknown identifier, type mismatch, non-finite result,
+ *  step-budget exhaustion). */
+export declare function evaluateAst(node: ExpressionNode, scope: Record<string, ExpressionValue>, opts?: ExpressionEvalOptions): ExpressionValue;

package/dist/expression/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Safe expression engine — public surface. A non-Turing-complete infix
+ * mini-language (tokenizer → Pratt parser → whitelisted-AST interpreter) with
+ * NO eval / new Function / node:vm, NO member access, NO loops/lambdas, and
+ * hard resource bounds. Powers the `expression` DeviceLinkSource kind.
+ *
+ * This is the module barrel; leaf files inside @camstack/types MUST import from
+ * the deep modules (e.g. `../expression/compile.js`), never through this file
+ * OR the root barrel (see biome-plugins/no-types-barrel-leaf-import.grit).
+ */
+export type { ExpressionValue, ExpressionNode, ExpressionLiteralNode, ExpressionIdentifierNode, ExpressionUnaryNode, ExpressionBinaryNode, ExpressionLogicalNode, ExpressionConditionalNode, ExpressionCallNode, ExpressionBinaryOperator, ExpressionLogicalOperator, ExpressionUnaryOperator, } from './ast.js';
+export { ExpressionParseError, ExpressionEvalError } from './errors.js';
+export { MAX_EXPRESSION_SOURCE_LENGTH, MAX_EXPRESSION_AST_NODES, MAX_EXPRESSION_EVAL_STEPS, MAX_EXPRESSION_BINDINGS, MAX_EXPRESSION_CALL_ARGS, EXPRESSION_COMPILE_CACHE_CAPACITY, EXPRESSION_IDENTIFIER_RE, RESERVED_BINDING_NAMES, } from './limits.js';
+export { tokenize } from './tokenizer.js';
+export type { Token, Punctuator, Keyword } from './tokenizer.js';
+export { parseExpression } from './parser.js';
+export type { ParsedExpression } from './parser.js';
+export { EXPRESSION_BUILTINS, EXPRESSION_BUILTIN_NAMES, } from './builtins.js';
+export type { ExpressionBuiltin, ExpressionEvalHooks } from './builtins.js';
+export { createExpressionScope, evaluateAst } from './evaluator.js';
+export type { ExpressionEvalOptions } from './evaluator.js';
+export { compileExpression, compileExpressionSafe } from './compile.js';
+export type { CompileResult } from './compile.js';
+export { EXPRESSION_INJECTED_NOW, toExpressionValue, validateExpressionSource, evaluateLinkExpression, } from './link-expression.js';
+export type { ExpressionSourceInput, EvaluateLinkExpressionResult, } from './link-expression.js';

package/dist/expression/limits.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resource-bound constants for the safe expression engine.
+ *
+ * Every bound is defense-in-depth: the grammar is non-Turing-complete (no
+ * loops, recursion, lambdas or member access — see `ast.ts`), so evaluation is
+ * O(nodeCount) by construction. These caps merely put a hard ceiling on the
+ * work a single author-supplied expression can request, so a hostile or
+ * accidental pathological string can never spend unbounded CPU/memory.
+ */
+/** Max source length (chars) — checked BEFORE tokenizing so a huge string is
+ *  rejected without allocation. */
+export declare const MAX_EXPRESSION_SOURCE_LENGTH = 2048;
+/** Max AST nodes — checked during parse; a deeply nested grouping that exceeds
+ *  this is rejected as "expression too complex". */
+export declare const MAX_EXPRESSION_AST_NODES = 256;
+/** Defense-in-depth walker step budget — one increment per node visit during
+ *  evaluation. The grammar guarantees O(nodeCount) walks, so this can only trip
+ *  on a crafted maximum-size AST. */
+export declare const MAX_EXPRESSION_EVAL_STEPS = 4096;
+/** Max named bindings on one `DeviceLinkExpressionSource`. */
+export declare const MAX_EXPRESSION_BINDINGS = 32;
+/** Max positional arguments to any builtin call. */
+export declare const MAX_EXPRESSION_CALL_ARGS = 16;
+/** LRU compile-cache capacity (parsed ASTs keyed by raw source string). */
+export declare const EXPRESSION_COMPILE_CACHE_CAPACITY = 256;
+/** A legal binding / identifier name. */
+export declare const EXPRESSION_IDENTIFIER_RE: RegExp;
+/** Binding names an author may NOT use: `now` is auto-injected; the literal
+ *  keywords lex as values, not identifiers, so binding to them is meaningless. */
+export declare const RESERVED_BINDING_NAMES: ReadonlySet<string>;