@camstack/types 1.2.267 → 1.2.269

package/dist/composition/composition-report.d.ts

@@ -5,15 +5,15 @@
 import { z } from 'zod';
 export declare const CompositionProblemCodeSchema: z.ZodEnum<{
     "source-missing": "source-missing";
+    "unknown-field": "unknown-field";
+    "kind-mismatch": "kind-mismatch";
+    "not-composable": "not-composable";
     "reserved-variant": "reserved-variant";
     "unknown-capability": "unknown-capability";
-    "not-composable": "not-composable";
     "wrong-device-type": "wrong-device-type";
     "has-commands": "has-commands";
-    "unknown-field": "unknown-field";
     "nested-field": "nested-field";
     "missing-field": "missing-field";
-    "kind-mismatch": "kind-mismatch";
     "may-be-null": "may-be-null";
     "source-unreadable": "source-unreadable";
     "source-capability-missing": "source-capability-missing";
@@ -21,21 +21,26 @@ export declare const CompositionProblemCodeSchema: z.ZodEnum<{
     "expression-invalid": "expression-invalid";
     cycle: "cycle";
     "duplicate-target": "duplicate-target";
+    "not-item-array": "not-item-array";
+    "item-field-reserved": "item-field-reserved";
+    "target-missing": "target-missing";
+    "target-unreadable": "target-unreadable";
+    "not-replaceable": "not-replaceable";
 }>;
 export type CompositionProblemCode = z.infer<typeof CompositionProblemCodeSchema>;
 /** One refusal, named (D391). `path` points into the composition, e.g. `features[0].fields.celsius`. */
 export declare const CompositionProblemSchema: z.ZodObject<{
     code: z.ZodEnum<{
         "source-missing": "source-missing";
+        "unknown-field": "unknown-field";
+        "kind-mismatch": "kind-mismatch";
+        "not-composable": "not-composable";
         "reserved-variant": "reserved-variant";
         "unknown-capability": "unknown-capability";
-        "not-composable": "not-composable";
         "wrong-device-type": "wrong-device-type";
         "has-commands": "has-commands";
-        "unknown-field": "unknown-field";
         "nested-field": "nested-field";
         "missing-field": "missing-field";
-        "kind-mismatch": "kind-mismatch";
         "may-be-null": "may-be-null";
         "source-unreadable": "source-unreadable";
         "source-capability-missing": "source-capability-missing";
@@ -43,6 +48,11 @@ export declare const CompositionProblemSchema: z.ZodObject<{
         "expression-invalid": "expression-invalid";
         cycle: "cycle";
         "duplicate-target": "duplicate-target";
+        "not-item-array": "not-item-array";
+        "item-field-reserved": "item-field-reserved";
+        "target-missing": "target-missing";
+        "target-unreadable": "target-unreadable";
+        "not-replaceable": "not-replaceable";
     }>;
     path: z.ZodString;
     message: z.ZodString;
@@ -55,25 +65,46 @@ export declare const CompositionFieldKindSchema: z.ZodEnum<{
     enum: "enum";
 }>;
 export type CompositionFieldKind = z.infer<typeof CompositionFieldKindSchema>;
-/** How a field says "unavailable": `null` when its schema allows it, else the device goes offline (D393). */
+/**
+ * How a field says "unavailable" (D393, D663): `null` when its schema allows it;
+ * `unknown` — the enum's own word — for an ADDED field that has one; `release`
+ * for a REPLACED field of an existing device, whose claim is released so the
+ * native provider's reading shows again; else the (composed) device goes offline.
+ */
 export declare const CompositionUnavailableModeSchema: z.ZodEnum<{
     null: "null";
+    unknown: "unknown";
     offline: "offline";
+    release: "release";
 }>;
 export type CompositionUnavailableMode = z.infer<typeof CompositionUnavailableModeSchema>;
 /**
  * `derived` reads a source · `clock` reads only `now`, recomputed when a sibling
- * field of its cap changes value · `constant` reads nothing, computed once.
+ * field of its cap changes value · `constant` reads nothing, computed once ·
+ * `accumulator` advances from the target's seed/current output.
  */
 export declare const CompositionFieldRoleSchema: z.ZodEnum<{
     derived: "derived";
     clock: "clock";
     constant: "constant";
+    accumulator: "accumulator";
 }>;
 export type CompositionFieldRole = z.infer<typeof CompositionFieldRoleSchema>;
+/** The item a planned field belongs to; its `path` is then the dotted path INSIDE the item. */
+export declare const CompositionFieldItemSchema: z.ZodObject<{
+    arrayPath: z.ZodString;
+    key: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type CompositionFieldItem = z.infer<typeof CompositionFieldItemSchema>;
 export declare const CompositionFieldPlanSchema: z.ZodObject<{
     cap: z.ZodString;
     path: z.ZodString;
+    item: z.ZodOptional<z.ZodObject<{
+        arrayPath: z.ZodString;
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
     featureIndex: z.ZodNumber;
     kind: z.ZodEnum<{
         string: "string";
@@ -85,12 +116,15 @@ export declare const CompositionFieldPlanSchema: z.ZodObject<{
     required: z.ZodBoolean;
     unavailable: z.ZodEnum<{
         null: "null";
+        unknown: "unknown";
         offline: "offline";
+        release: "release";
     }>;
     role: z.ZodEnum<{
         derived: "derived";
         clock: "clock";
         constant: "constant";
+        accumulator: "accumulator";
     }>;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
@@ -129,20 +163,43 @@ export declare const CompositionFieldPlanSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CompositionFieldPlan = z.infer<typeof CompositionFieldPlanSchema>;
+/** The key every record map, log line and graph node uses for a planned field. Two items' `status` are two keys. */
+export declare function compositionFieldKey(plan: Pick<CompositionFieldPlan, 'cap' | 'path' | 'item'>): string;
+/**
+ * What a feature does to its target (D663): `new` builds a capability on a new
+ * device; on an existing device it `add`s a capability the device lacks, or
+ * `replace`s named fields of one it has natively.
+ */
+export declare const CompositionFeatureModeSchema: z.ZodEnum<{
+    new: "new";
+    replace: "replace";
+    add: "add";
+}>;
+export type CompositionFeatureMode = z.infer<typeof CompositionFeatureModeSchema>;
+export declare const CompositionFeaturePlanSchema: z.ZodObject<{
+    featureIndex: z.ZodNumber;
+    cap: z.ZodString;
+    mode: z.ZodEnum<{
+        new: "new";
+        replace: "replace";
+        add: "add";
+    }>;
+}, z.core.$strip>;
+export type CompositionFeaturePlan = z.infer<typeof CompositionFeaturePlanSchema>;
 export declare const CompositionValidationSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
             "source-missing": "source-missing";
+            "unknown-field": "unknown-field";
+            "kind-mismatch": "kind-mismatch";
+            "not-composable": "not-composable";
             "reserved-variant": "reserved-variant";
             "unknown-capability": "unknown-capability";
-            "not-composable": "not-composable";
             "wrong-device-type": "wrong-device-type";
             "has-commands": "has-commands";
-            "unknown-field": "unknown-field";
             "nested-field": "nested-field";
             "missing-field": "missing-field";
-            "kind-mismatch": "kind-mismatch";
             "may-be-null": "may-be-null";
             "source-unreadable": "source-unreadable";
             "source-capability-missing": "source-capability-missing";
@@ -150,6 +207,11 @@ export declare const CompositionValidationSchema: z.ZodObject<{
             "expression-invalid": "expression-invalid";
             cycle: "cycle";
             "duplicate-target": "duplicate-target";
+            "not-item-array": "not-item-array";
+            "item-field-reserved": "item-field-reserved";
+            "target-missing": "target-missing";
+            "target-unreadable": "target-unreadable";
+            "not-replaceable": "not-replaceable";
         }>;
         path: z.ZodString;
         message: z.ZodString;
@@ -157,6 +219,11 @@ export declare const CompositionValidationSchema: z.ZodObject<{
     fields: z.ZodArray<z.ZodObject<{
         cap: z.ZodString;
         path: z.ZodString;
+        item: z.ZodOptional<z.ZodObject<{
+            arrayPath: z.ZodString;
+            key: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
         featureIndex: z.ZodNumber;
         kind: z.ZodEnum<{
             string: "string";
@@ -168,12 +235,15 @@ export declare const CompositionValidationSchema: z.ZodObject<{
         required: z.ZodBoolean;
         unavailable: z.ZodEnum<{
             null: "null";
+            unknown: "unknown";
             offline: "offline";
+            release: "release";
         }>;
         role: z.ZodEnum<{
             derived: "derived";
             clock: "clock";
             constant: "constant";
+            accumulator: "accumulator";
         }>;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
             source: z.ZodObject<{
@@ -211,14 +281,36 @@ export declare const CompositionValidationSchema: z.ZodObject<{
             fieldPath: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    features: z.ZodArray<z.ZodObject<{
+        featureIndex: z.ZodNumber;
+        cap: z.ZodString;
+        mode: z.ZodEnum<{
+            new: "new";
+            replace: "replace";
+            add: "add";
+        }>;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodObject<{
+        featureIndex: z.ZodNumber;
+        cap: z.ZodString;
+        eventName: z.ZodString;
+        category: z.ZodEnum<typeof import("../index.js").EventCategory>;
+        stateField: z.ZodString;
+        fieldKey: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CompositionValidation = z.infer<typeof CompositionValidationSchema>;
-/** Mirrors `CoreBlockStatus`, pinned by `core-blocks-source.spec.ts` (Task 11). */
+/**
+ * Mirrors `CoreBlockStatus`, pinned by `core-blocks-source.spec.ts`. `degraded`:
+ * running, but a replaced field is released to the native provider while its
+ * source is unavailable (ruling S1b, D663) — the reason names each such field.
+ */
 export declare const CompositionRunStatusSchema: z.ZodEnum<{
     running: "running";
     failed: "failed";
     stopped: "stopped";
     starting: "starting";
+    degraded: "degraded";
 }>;
 export type CompositionRunStatus = z.infer<typeof CompositionRunStatusSchema>;
 export declare const CompositionFieldStateKindSchema: z.ZodEnum<{
@@ -230,6 +322,11 @@ export type CompositionFieldStateKind = z.infer<typeof CompositionFieldStateKind
 export declare const CompositionFieldStateSchema: z.ZodObject<{
     cap: z.ZodString;
     path: z.ZodString;
+    item: z.ZodOptional<z.ZodObject<{
+        arrayPath: z.ZodString;
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
     state: z.ZodEnum<{
         unavailable: "unavailable";
         fresh: "fresh";
@@ -247,11 +344,17 @@ export declare const CompositionBlockStateSchema: z.ZodObject<{
         failed: "failed";
         stopped: "stopped";
         starting: "starting";
+        degraded: "degraded";
     }>;
     reason: z.ZodOptional<z.ZodString>;
     fields: z.ZodArray<z.ZodObject<{
         cap: z.ZodString;
         path: z.ZodString;
+        item: z.ZodOptional<z.ZodObject<{
+            arrayPath: z.ZodString;
+            key: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
         state: z.ZodEnum<{
             unavailable: "unavailable";
             fresh: "fresh";

package/dist/composition/composition.d.ts

@@ -14,13 +14,19 @@
  * Later slices EXTEND these unions and do not reshape them. The variants a later
  * slice implements are already in the wire shape, and `validateComposition`
  * refuses them BY NAME until then:
- *   target `existing` → slice 2 · feature `passthrough` → slice 3 ·
- *   `commands` (`forward`) → slice 3 · source `code` → slice 4.
+ *   feature `passthrough` → slice 3 · `commands` (`forward`) → slice 3 ·
+ *   source `code` → slice 4. Target `existing` (customize a device) is slice 2 (D663).
  */
 import { z } from 'zod';
 import { DeviceRole, DeviceType } from '../device/device-type.js';
 /** The owner of every composed device: the `composer` builtin. */
 export declare const COMPOSER_ADDON_ID = "composer";
+/**
+ * The stored name of a block that customizes an EXISTING device starts with this
+ * (`customizationBlockName`, `@camstack/types/node`). Never parsed to tell a
+ * customization apart: `composition.target.kind === 'existing'` says that (D663).
+ */
+export declare const CUSTOMIZATION_BLOCK_NAME_PREFIX = "customize:";
 /** A composed device's stableId is this prefix plus the block id. */
 export declare const COMPOSED_DEVICE_STABLE_ID_PREFIX = "composed-";
 /** A device with more capabilities than this is two devices. */
@@ -153,9 +159,51 @@ export declare const CompositionCommandTargetSchema: z.ZodDiscriminatedUnion<[z.
     code: z.ZodString;
 }, z.core.$strip>], "kind">;
 export type CompositionCommandTarget = z.infer<typeof CompositionCommandTargetSchema>;
+/** An item key inside an item-array cap (`consumables.items[<key>]`). */
+export declare const COMPOSITION_ITEM_KEY_RE: RegExp;
+export declare const MAX_COMPOSITION_ITEMS = 16;
+/** The item-array path of every item-array cap that exists (`consumables.items`). */
+export declare const COMPOSITION_ITEM_ARRAY_PATH = "items";
+/**
+ * One item of an item-array cap (D663), addressed through the cap's
+ * `status.itemArray` descriptor. `fields` are paths INSIDE the item, nested
+ * allowed (`remaining.value`); the key and label come from the entry itself.
+ */
+export declare const CompositionItemEntrySchema: z.ZodObject<{
+    label: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+        kind: z.ZodLiteral<"from">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"expression">;
+        expr: z.ZodString;
+        bindings: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+            kind: z.ZodLiteral<"from">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"literal">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"code">;
+        code: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type CompositionItemEntry = z.infer<typeof CompositionItemEntrySchema>;
 export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
     kind: z.ZodLiteral<"fields">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             addonId: z.ZodString;
@@ -183,6 +231,36 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
     }, z.core.$strip>], "kind">>;
+    items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+            kind: z.ZodLiteral<"from">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"expression">;
+            expr: z.ZodString;
+            bindings: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+                kind: z.ZodLiteral<"from">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"literal">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            }, z.core.$strip>], "kind">>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            code: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>>;
     commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"forward">;
         source: z.ZodObject<{
@@ -201,6 +279,7 @@ export type CompositionFieldsFeature = z.infer<typeof CompositionFieldsFeatureSc
 export declare const CompositionPassthroughFeatureSchema: z.ZodObject<{
     kind: z.ZodLiteral<"passthrough">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     source: z.ZodObject<{
         addonId: z.ZodString;
         stableId: z.ZodString;
@@ -210,6 +289,7 @@ export type CompositionPassthroughFeature = z.infer<typeof CompositionPassthroug
 export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"fields">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             addonId: z.ZodString;
@@ -237,6 +317,36 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
         kind: z.ZodLiteral<"code">;
         code: z.ZodString;
     }, z.core.$strip>], "kind">>;
+    items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+            kind: z.ZodLiteral<"from">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"expression">;
+            expr: z.ZodString;
+            bindings: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+                kind: z.ZodLiteral<"from">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"literal">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            }, z.core.$strip>], "kind">>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            code: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>>;
     commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"forward">;
         source: z.ZodObject<{
@@ -252,12 +362,15 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"passthrough">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     source: z.ZodObject<{
         addonId: z.ZodString;
         stableId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>], "kind">;
 export type CompositionFeature = z.infer<typeof CompositionFeatureSchema>;
+/** Only an explicit `false` disables a feature; omitted preserves the existing wire default. */
+export declare function compositionFeatureEnabled(feature: CompositionFeature): boolean;
 /**
  * A NEW device. It has no `name` of its own: the block's name IS the device's
  * name (2026-08-08). A second copy here would be a second writer of one string (D62).
@@ -268,7 +381,7 @@ export declare const CompositionNewTargetSchema: z.ZodObject<{
     role: z.ZodOptional<z.ZodEnum<typeof DeviceRole>>;
 }, z.core.$strip>;
 export type CompositionNewTarget = z.infer<typeof CompositionNewTargetSchema>;
-/** RESERVED for slice 2: customize an existing device. */
+/** Customize an EXISTING device: each feature adds a capability or replaces fields of a native one (D663). */
 export declare const CompositionExistingTargetSchema: z.ZodObject<{
     kind: z.ZodLiteral<"existing">;
     device: z.ZodObject<{
@@ -304,6 +417,7 @@ export declare const CompositionSchema: z.ZodObject<{
     features: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"fields">;
         cap: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
         fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             source: z.ZodObject<{
                 addonId: z.ZodString;
@@ -331,6 +445,36 @@ export declare const CompositionSchema: z.ZodObject<{
             kind: z.ZodLiteral<"code">;
             code: z.ZodString;
         }, z.core.$strip>], "kind">>;
+        items: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodString;
+            fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                source: z.ZodObject<{
+                    addonId: z.ZodString;
+                    stableId: z.ZodString;
+                }, z.core.$strip>;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+                kind: z.ZodLiteral<"from">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"expression">;
+                expr: z.ZodString;
+                bindings: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    source: z.ZodObject<{
+                        addonId: z.ZodString;
+                        stableId: z.ZodString;
+                    }, z.core.$strip>;
+                    cap: z.ZodString;
+                    fieldPath: z.ZodString;
+                    kind: z.ZodLiteral<"from">;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"literal">;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                }, z.core.$strip>], "kind">>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"code">;
+                code: z.ZodString;
+            }, z.core.$strip>], "kind">>;
+        }, z.core.$strip>>>;
         commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"forward">;
             source: z.ZodObject<{
@@ -346,6 +490,7 @@ export declare const CompositionSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"passthrough">;
         cap: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
         source: z.ZodObject<{
             addonId: z.ZodString;
             stableId: z.ZodString;
@@ -360,3 +505,17 @@ export declare function composedDeviceStableId(blockId: string): string;
 export declare function composedDeviceRef(blockId: string): CompositionSourceRef;
 /** Every device field a source reads: `from` is one read, an expression is its `from` bindings. */
 export declare function fieldReads(source: CompositionFieldSource): readonly CompositionFieldRead[];
+/** The ONE spelling of an item leaf as a field path: `items[desiccant].remaining.value`. */
+export declare function compositionItemFieldPath(arrayPath: string, key: string, path: string): string;
+export interface CompositionFeatureFieldEntry {
+    readonly fieldPath: string;
+    readonly source: CompositionFieldSource;
+}
+/**
+ * Every written field of a feature, item leaves under their bracketed path.
+ * `arrayPath` is `'items'` for every item-array cap that exists
+ * (`consumables.cap.ts`); the graph has no cap lookup, so the default stands
+ * and `planItems` asserts it agrees with the cap's descriptor.
+ */
+export declare function featureFieldEntries(feature: CompositionFieldsFeature, arrayPath?: string): readonly CompositionFeatureFieldEntry[];
+export declare function featureSources(feature: CompositionFieldsFeature): readonly CompositionFieldSource[];

package/dist/composition/customization-name.d.ts

@@ -0,0 +1,6 @@
+import { type CompositionSourceRef } from './composition.js';
+/**
+ * Derived by the SERVER on save, never sent by the client; never shown as the
+ * device's name. Unique per target: the plain ref when it fits, else a hash.
+ */
+export declare function customizationBlockName(ref: CompositionSourceRef): string;

package/dist/composition/evaluate-field.d.ts

@@ -15,6 +15,14 @@
  *  - an expression that fails on a value makes the field unavailable for that
  *    value, and NOT fatal: the next value may compute.
  *
+ * `confirmed` (D663, D49): whether a NON-fatal unavailability is an ANSWER — a
+ * cap the provider unregistered and a re-read agreed, a field the source
+ * reported without, an expression that failed on a value — or only the
+ * absence of one (a failed read, a first or empty read, a source not tracked
+ * yet). Only a confirmed unavailability may hand a `release`-mode field back
+ * to the native provider; an unconfirmed one holds it on its last value.
+ * Absent means NOT confirmed. Fatal is always confirmed.
+ *
  * When an expression has more than one unavailable binding, a FATAL one always
  * wins the outcome, regardless of position: every binding is scanned before
  * the field is judged, so an earlier non-fatal binding (e.g. a cap that is
@@ -22,6 +30,7 @@
  * source) behind an early return.
  */
 import type { ExpressionValue } from '../expression/ast.js';
+import { type StatefulExpressionMemory } from '../expression/expression-source.js';
 import { type CompositionFieldRead, type CompositionFieldSource } from './composition.js';
 export interface SourceFreshReading {
     readonly state: 'fresh';
@@ -37,6 +46,8 @@ export interface SourceUnavailableReading {
     readonly reason: string;
     /** True when the source is GONE: device or cap missing, two reads agreed. */
     readonly fatal: boolean;
+    /** The unavailability is an answer, not a missing one (see the header). Absent = not confirmed. */
+    readonly confirmed?: boolean;
 }
 export type SourceReading = SourceFreshReading | SourceStaleReading | SourceUnavailableReading;
 export type SourceReader = (read: CompositionFieldRead) => SourceReading;
@@ -53,11 +64,20 @@ export interface FieldUnavailableOutcome {
     readonly value: null;
     readonly reason: string;
     readonly fatal: boolean;
+    /** Fatal, or a non-fatal unavailability that is an answer (see the header). Absent = not confirmed. */
+    readonly confirmed?: boolean;
 }
 export type FieldOutcome = FieldValueOutcome | FieldUnavailableOutcome;
 export interface EvaluateCompositionFieldInput {
     readonly source: CompositionFieldSource;
     readonly read: SourceReader;
     readonly now: number;
+    readonly stateful?: {
+        readonly currentOutput: unknown;
+        readonly expressionMemory: StatefulExpressionMemory;
+        readonly startedAtMs: number;
+        /** Scope structural AST paths to their owning output field. */
+        readonly callPathPrefix?: string;
+    };
 }
 export declare function evaluateCompositionField(input: EvaluateCompositionFieldInput): FieldOutcome;

package/dist/composition/examples.d.ts

@@ -8,3 +8,36 @@ export interface RoomExampleInput {
     readonly occupancyWindowMs: number;
 }
 export declare function roomCompositionExample(input: RoomExampleInput): Composition;
+/**
+ * The slice-2 worked customization (D663): the PetKit "Fresh Element Infinity"
+ * feeder as Home Assistant imports it — ONE `Container` with a child per entity
+ * (`<container stableId>-<entityId>`), and NO native battery (its
+ * `binary_sensor.*_battery` is `battery_charging`, which `isBatteryEntity` does
+ * not match). The customization ADDS `consumables` (the desiccant) and
+ * `battery`. It is the Task 14 acceptance case and the template slice 5's
+ * presets start from.
+ *
+ * Every read names what the HA provider REALLY registers (read 2026-09-28):
+ * the desiccant sensor has a unit (`d`) but no device_class, so HA hosts it as
+ * an `enum-sensor` whose `value` is the raw STRING state — `number(d)` reads it,
+ * and anything that is not a number is `null`, never 0 (D393). The battery
+ * status sensor is an `enum-sensor` too (`unavailable` keeps its cold `''`, so
+ * `percentage` is `null`). `charging` maps `battery_charging` off to
+ * `'unknown'`, never `'none'`: off does not prove "on battery alone" (the
+ * operator confirms the real semantics live).
+ */
+export declare const FEEDER_EXAMPLE_HA_DEVICE_ID = "8dec3b512fda40cbb8cd121c7a99f890";
+export declare const FEEDER_EXAMPLE_ADDON_ID = "provider-homeassistant";
+/** The container and the three children the feeder customization reads, under one HA broker. */
+export interface FeederExampleSources {
+    readonly feeder: CompositionSourceRef;
+    /** `sensor.freshelement_3_desiccant_days_remaining` — `enum-sensor.value`, a numeric string. */
+    readonly desiccantDays: CompositionSourceRef;
+    /** `sensor.freshelement_3_battery_status` — `enum-sensor.value`. */
+    readonly batteryStatus: CompositionSourceRef;
+    /** `binary_sensor.freshelement_3_battery` (`battery_charging`) — `binary.on`. */
+    readonly batteryCharging: CompositionSourceRef;
+}
+/** The HA container's stableId (`ha-discovery.ts`) and a child's (`<container>-<entityId>`). */
+export declare function feederExampleSources(brokerId: string): FeederExampleSources;
+export declare function feederCustomizationExample(sources: FeederExampleSources): Composition;

package/dist/composition/expression-kinds.d.ts

@@ -33,4 +33,5 @@ export interface InferenceFailure {
 }
 export type InferExpressionKindsResult = InferredKinds | InferenceFailure;
 export declare function kindOfValue(value: ExpressionValue): ExpressionValueKind;
+export declare function expressionContainsBuiltinCall(expr: string, callee: string): boolean;
 export declare function inferExpressionKinds(input: InferExpressionKindsInput): InferExpressionKindsResult;