@camstack/types 1.2.266 → 1.2.268

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

@@ -21,6 +21,11 @@ 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`. */
@@ -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,10 +65,17 @@ 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>;
 /**
@@ -71,9 +88,21 @@ export declare const CompositionFieldRoleSchema: z.ZodEnum<{
     constant: "constant";
 }>;
 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,7 +114,9 @@ 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";
@@ -129,6 +160,29 @@ 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<{
@@ -150,6 +204,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 +216,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,7 +232,9 @@ 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";
@@ -211,14 +277,28 @@ 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>>;
 }, 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 +310,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 +332,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,6 +159,47 @@ 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;
@@ -183,6 +230,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<{
@@ -237,6 +314,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<{
@@ -268,7 +375,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<{
@@ -331,6 +438,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<{
@@ -360,3 +497,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
@@ -37,6 +45,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,6 +63,8 @@ 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 {

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/field-kinds.d.ts

@@ -0,0 +1,42 @@
+import { type CompositionFieldSource } from './composition.js';
+import type { CompositionFeatureMode, CompositionFieldRole, CompositionProblem, CompositionProblemCode, CompositionUnavailableMode } from './composition-report.js';
+import { type ExpressionKindSet } from './expression-kinds.js';
+import { type StateFieldDescription } from './state-fields.js';
+import type { CapabilityLookup } from './validate-composition.js';
+interface KindsFound {
+    readonly ok: true;
+    readonly kinds: ExpressionKindSet;
+}
+interface KindsRefused {
+    readonly ok: false;
+    readonly code: CompositionProblemCode;
+    readonly message: string;
+}
+type KindsResult = KindsFound | KindsRefused;
+export declare function sourceKinds(source: CompositionFieldSource, lookupCap: CapabilityLookup): KindsResult;
+export declare function compatibility(cap: string, target: StateFieldDescription, kinds: ExpressionKindSet, at: string): readonly CompositionProblem[];
+/**
+ * An enum target whose source is a save-time-KNOWN string literal outside its
+ * `enumValues` is refused now rather than left to fail the write later. A
+ * dynamic source (a `from` read, a non-literal expression) is left to
+ * runtime — see {@link literalStringValue}.
+ */
+export declare function enumLiteralProblem(cap: string, target: StateFieldDescription, source: CompositionFieldSource, at: string): CompositionProblem | null;
+export declare function roleOf(source: CompositionFieldSource): CompositionFieldRole;
+interface UnavailableChosen {
+    readonly ok: true;
+    readonly unavailable: CompositionUnavailableMode;
+}
+interface UnavailableRefused {
+    readonly ok: false;
+    readonly problem: CompositionProblem;
+}
+export type UnavailableResult = UnavailableChosen | UnavailableRefused;
+/**
+ * How a planned field says "unavailable", per feature mode and AFTER `roleOf`
+ * (D393, D663 rulings S1 + S1b). The composer cannot take a device it does not
+ * own offline, and D393 forbids a stale number, so on an existing target a
+ * field that READS a source never gets `offline`.
+ */
+export declare function unavailableFor(tf: StateFieldDescription, role: CompositionFieldRole, mode: CompositionFeatureMode, cap: string, at: string): UnavailableResult;
+export {};

package/dist/composition/index.d.ts

@@ -4,6 +4,7 @@
  */
 export * from './composition.js';
 export * from './composition-graph.js';
+export * from './composition-items.js';
 export * from './composition-report.js';
 export * from './evaluate-field.js';
 export * from './examples.js';

package/dist/composition/plan-result.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The result of planning part of a composition, and the two helpers every
+ * planner builds it with. Internal to the composition module — NOT in the
+ * barrel (`problem`/`refused` are too generic a name for `@camstack/types`).
+ */
+import type { CompositionFeaturePlan, CompositionFieldPlan, CompositionProblem, CompositionProblemCode } from './composition-report.js';
+export interface CompositionPlanResult {
+    readonly problems: readonly CompositionProblem[];
+    readonly fields: readonly CompositionFieldPlan[];
+    /** One entry per planned feature, with its mode; empty for a per-field or per-item result. */
+    readonly features: readonly CompositionFeaturePlan[];
+}
+export declare function problem(code: CompositionProblemCode, path: string, message: string): CompositionProblem;
+export declare function refused(...problems: readonly CompositionProblem[]): CompositionPlanResult;
+/** Where a planned field sits in the composition: `features[N].fields.<path>` or `features[N].items.<key>.fields.<path>`. */
+export declare function compositionFieldAt(field: CompositionFieldPlan): string;

package/dist/composition/state-fields.d.ts

@@ -17,3 +17,9 @@ export declare function describeStateField(schema: z.ZodType, path: string): Sta
 export declare function describeTopLevelStateFields(schema: z.ZodType): ReadonlyMap<string, StateFieldDescription>;
 /** Top-level keys a value MUST carry: those whose schema refuses `undefined`. */
 export declare function requiredTopLevelKeys(schema: z.ZodType): readonly string[];
+/**
+ * The proper prefixes of `path` whose schema accepts `undefined`: a required
+ * leaf under one of them is required only once something writes that parent
+ * (`remaining.unit` is required only when `remaining` is present).
+ */
+export declare function optionalAncestors(schema: z.ZodType, path: string): readonly string[];

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

@@ -1,16 +1,19 @@
 /**
  * Save-time validation of a composition (D659): shape, capability fit, field
- * kinds, nullability, sources, cycles. Every refusal names its reason (D391),
+ * kinds, nullability, sources, cycles — and on an EXISTING target (D663),
+ * add vs replace per feature, self reads, one composition per device. Every refusal names its reason (D391),
  * and every variant a later slice implements is refused BY NAME with that slice.
  *
- * Pure: the caller DESCRIBES the sources (one read each) and passes the other
- * stored compositions. `planComposition` is the static half the composer
+ * Pure: the caller DESCRIBES the sources and an existing target (one read
+ * each) and passes the other stored compositions. `planComposition` is the static half the composer
  * re-runs at apply time, where the sources are the tracker's business.
  */
 import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import type { DeviceType } from '../device/device-type.js';
 import { type Composition, type CompositionSourceRef } from './composition.js';
+import { type CompositionPlanResult } from './plan-result.js';
 import { type CompositionPeer } from './composition-graph.js';
-import type { CompositionFieldPlan, CompositionProblem, CompositionValidation } from './composition-report.js';
+import { type CompositionValidation } from './composition-report.js';
 export type CapabilityLookup = (capName: string) => CapabilityDefinition | null;
 export declare function buildCapabilityLookup(defs: readonly CapabilityDefinition[]): CapabilityLookup;
 /** Caps every `BaseDevice` registers on itself; a second registration throws. */
@@ -28,19 +31,51 @@ export interface CompositionSourceUnreadable {
     readonly error: string;
 }
 export type CompositionSourceDescription = CompositionSourceFound | CompositionSourceAbsent | CompositionSourceUnreadable;
+/** An existing target device, read once: its type and each cap bound to it, with the addon serving it. */
+export interface CompositionTargetFound {
+    readonly kind: 'found';
+    readonly deviceId: number;
+    readonly type: DeviceType;
+    /** cap name → `nativeAddonId` (`getBindings`). A cap the composer grafted carries `COMPOSER_ADDON_ID`. */
+    readonly nativeCaps: ReadonlyMap<string, string>;
+}
+export type CompositionTargetDescription = CompositionTargetFound | CompositionSourceAbsent | CompositionSourceUnreadable;
 export interface ValidateCompositionContext {
     readonly lookupCap: CapabilityLookup;
     /** Keyed by `compositionSourceKey`. A ref with no entry was not read, and is refused as unreadable. */
     readonly sources: ReadonlyMap<string, CompositionSourceDescription>;
     /** The device this composition writes; null on create, when the block has no id yet. */
     readonly self: CompositionSourceRef | null;
+    /** The block being saved; null on create. Its stored old version is recognised by this id (D663). */
+    readonly blockId: string | null;
+    /** The EXISTING target device, read once; null for a new-device composition (a missing read is refused). */
+    readonly target: CompositionTargetDescription | null;
     /** Every OTHER stored composition; cycles run through them. */
     readonly peers: readonly CompositionPeer[];
+    /**
+     * Devices of stored customizations whose target could not be read, by
+     * `compositionSourceKey` → why. Their peers are OVER-approximated (nothing
+     * `replaced`, so every self-read is an edge — edges are only added, a cycle
+     * never hidden). A cyclic component holding a candidate node and such a
+     * device refuses NAMING the device ("possible cycle"); a component without a
+     * candidate node is never this save's cycle (`findCandidateCycles`).
+     */
+    readonly unreadTargets?: ReadonlyMap<string, string>;
 }
-export interface CompositionPlanResult {
-    readonly problems: readonly CompositionProblem[];
-    readonly fields: readonly CompositionFieldPlan[];
-}
-export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup): CompositionPlanResult;
+export type { CompositionPlanResult } from './plan-result.js';
+/** The candidate's block id before its first save. Stored block ids are `randomUUID()`, so none can carry it. */
+export declare const PENDING_BLOCK_ID = "(unsaved)";
+/**
+ * The static plan. `target` describes an EXISTING target device (one read);
+ * it is ignored for a new one. On an existing target each feature REPLACES a
+ * cap the device has natively, else ADDS it (D663).
+ */
+export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup, target?: CompositionTargetDescription): CompositionPlanResult;
 export declare function compositionSourceRefs(composition: Composition): readonly CompositionSourceRef[];
+/**
+ * `compositionFieldKey` of every field a REPLACE feature of `plan` owns — the
+ * candidate's own, and a stored peer's `CompositionPeer.replaced` (D663): one
+ * derivation, so the graph reads both the same way.
+ */
+export declare function replacedFieldKeys(plan: CompositionPlanResult): ReadonlySet<string>;
 export declare function validateComposition(composition: Composition, ctx: ValidateCompositionContext): CompositionValidation;