@camstack/types 1.2.264 → 1.2.266

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

@@ -0,0 +1,264 @@
+/**
+ * What the validator says about a composition and what the composer says about
+ * a running one: the wire shapes the API returns (D659).
+ */
+import { z } from 'zod';
+export declare const CompositionProblemCodeSchema: z.ZodEnum<{
+    "source-missing": "source-missing";
+    "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";
+    "source-field-unknown": "source-field-unknown";
+    "expression-invalid": "expression-invalid";
+    cycle: "cycle";
+    "duplicate-target": "duplicate-target";
+}>;
+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";
+        "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";
+        "source-field-unknown": "source-field-unknown";
+        "expression-invalid": "expression-invalid";
+        cycle: "cycle";
+        "duplicate-target": "duplicate-target";
+    }>;
+    path: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type CompositionProblem = z.infer<typeof CompositionProblemSchema>;
+export declare const CompositionFieldKindSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    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). */
+export declare const CompositionUnavailableModeSchema: z.ZodEnum<{
+    null: "null";
+    offline: "offline";
+}>;
+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.
+ */
+export declare const CompositionFieldRoleSchema: z.ZodEnum<{
+    derived: "derived";
+    clock: "clock";
+    constant: "constant";
+}>;
+export type CompositionFieldRole = z.infer<typeof CompositionFieldRoleSchema>;
+export declare const CompositionFieldPlanSchema: z.ZodObject<{
+    cap: z.ZodString;
+    path: z.ZodString;
+    featureIndex: z.ZodNumber;
+    kind: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        enum: "enum";
+    }>;
+    nullable: z.ZodBoolean;
+    required: z.ZodBoolean;
+    unavailable: z.ZodEnum<{
+        null: "null";
+        offline: "offline";
+    }>;
+    role: z.ZodEnum<{
+        derived: "derived";
+        clock: "clock";
+        constant: "constant";
+    }>;
+    source: 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">;
+    reads: z.ZodArray<z.ZodObject<{
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CompositionFieldPlan = z.infer<typeof CompositionFieldPlanSchema>;
+export declare const CompositionValidationSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            "source-missing": "source-missing";
+            "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";
+            "source-field-unknown": "source-field-unknown";
+            "expression-invalid": "expression-invalid";
+            cycle: "cycle";
+            "duplicate-target": "duplicate-target";
+        }>;
+        path: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    fields: z.ZodArray<z.ZodObject<{
+        cap: z.ZodString;
+        path: z.ZodString;
+        featureIndex: z.ZodNumber;
+        kind: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+        }>;
+        nullable: z.ZodBoolean;
+        required: z.ZodBoolean;
+        unavailable: z.ZodEnum<{
+            null: "null";
+            offline: "offline";
+        }>;
+        role: z.ZodEnum<{
+            derived: "derived";
+            clock: "clock";
+            constant: "constant";
+        }>;
+        source: 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">;
+        reads: z.ZodArray<z.ZodObject<{
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CompositionValidation = z.infer<typeof CompositionValidationSchema>;
+/** Mirrors `CoreBlockStatus`, pinned by `core-blocks-source.spec.ts` (Task 11). */
+export declare const CompositionRunStatusSchema: z.ZodEnum<{
+    running: "running";
+    failed: "failed";
+    stopped: "stopped";
+    starting: "starting";
+}>;
+export type CompositionRunStatus = z.infer<typeof CompositionRunStatusSchema>;
+export declare const CompositionFieldStateKindSchema: z.ZodEnum<{
+    unavailable: "unavailable";
+    fresh: "fresh";
+    stale: "stale";
+}>;
+export type CompositionFieldStateKind = z.infer<typeof CompositionFieldStateKindSchema>;
+export declare const CompositionFieldStateSchema: z.ZodObject<{
+    cap: z.ZodString;
+    path: z.ZodString;
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        fresh: "fresh";
+        stale: "stale";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CompositionFieldState = z.infer<typeof CompositionFieldStateSchema>;
+export declare const CompositionBlockStateSchema: z.ZodObject<{
+    blockId: z.ZodString;
+    deviceId: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        stopped: "stopped";
+        starting: "starting";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    fields: z.ZodArray<z.ZodObject<{
+        cap: z.ZodString;
+        path: z.ZodString;
+        state: z.ZodEnum<{
+            unavailable: "unavailable";
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CompositionBlockState = z.infer<typeof CompositionBlockStateSchema>;

package/dist/composition/composition.d.ts

@@ -0,0 +1,362 @@
+/**
+ * A COMPOSITION: a device assembled from other devices' state (D659).
+ *
+ * The data half of the composed-devices spec §1. A composition is stored inside
+ * a core block (`CoreBlock.source.kind === 'composition'`) and run by the shared
+ * `composer` runner. It names a TARGET and, for each capability of the target, a
+ * FIELD MAP: every state field has exactly one source.
+ *
+ * Sources are keyed by `(addonId, stableId)`, NEVER by numeric device id. A
+ * resync reissues numeric ids, and a composition that stored them would be
+ * orphaned by the first re-adoption (the linked-devices lesson). A `stableId` is
+ * unique only within its owning addon, so the owner travels with it.
+ *
+ * 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.
+ */
+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";
+/** 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. */
+export declare const MAX_COMPOSITION_FEATURES = 16;
+export declare const MAX_COMPOSITION_FIELDS_PER_FEATURE = 32;
+/** Longest snippet a `code` source may carry (slice 4). */
+export declare const MAX_COMPOSITION_CODE_LENGTH = 20000;
+export declare const CompositionSourceRefSchema: z.ZodObject<{
+    addonId: z.ZodString;
+    stableId: z.ZodString;
+}, z.core.$strip>;
+export type CompositionSourceRef = z.infer<typeof CompositionSourceRefSchema>;
+/** One field of one capability of one source device. */
+export declare const CompositionFieldReadSchema: z.ZodObject<{
+    source: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+}, z.core.$strip>;
+export type CompositionFieldRead = z.infer<typeof CompositionFieldReadSchema>;
+/** `from`: copy one source field verbatim. It is also an expression's `from` binding. */
+export declare const CompositionFromSourceSchema: 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>;
+export type CompositionFromSource = z.infer<typeof CompositionFromSourceSchema>;
+/** A constant binding. No device is read. */
+export declare const CompositionLiteralBindingSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"literal">;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+}, z.core.$strip>;
+export type CompositionLiteralBinding = z.infer<typeof CompositionLiteralBindingSchema>;
+export declare const CompositionBindingSchema: 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">;
+export type CompositionBinding = z.infer<typeof CompositionBindingSchema>;
+/**
+ * `expression`: a formula over named bindings, in the salvaged expression
+ * engine. Validated at parse by the SAME function every other consumer runs,
+ * so the editor and the store cannot disagree.
+ */
+export declare const CompositionExpressionSourceSchema: 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>;
+export type CompositionExpressionSource = z.infer<typeof CompositionExpressionSourceSchema>;
+/** `code`: RESERVED for slice 4 (own runner, one-way eject). */
+export declare const CompositionCodeSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"code">;
+    code: z.ZodString;
+}, z.core.$strip>;
+export type CompositionCodeSource = z.infer<typeof CompositionCodeSourceSchema>;
+export declare const CompositionFieldSourceSchema: 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">;
+export type CompositionFieldSource = z.infer<typeof CompositionFieldSourceSchema>;
+/** `forward`: RESERVED for slice 3. Argument mapping arrives there as an additive optional `args`. */
+export declare const CompositionForwardCommandSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"forward">;
+    source: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+    cap: z.ZodString;
+    method: z.ZodString;
+}, z.core.$strip>;
+export type CompositionForwardCommand = z.infer<typeof CompositionForwardCommandSchema>;
+export declare const CompositionCommandTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"forward">;
+    source: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+    cap: z.ZodString;
+    method: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"code">;
+    code: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type CompositionCommandTarget = z.infer<typeof CompositionCommandTargetSchema>;
+export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"fields">;
+    cap: 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">>;
+    commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"forward">;
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        method: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"code">;
+        code: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+}, z.core.$strip>;
+export type CompositionFieldsFeature = z.infer<typeof CompositionFieldsFeatureSchema>;
+/** RESERVED for slice 3: a media / data-plane cap, whole, from one source. */
+export declare const CompositionPassthroughFeatureSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"passthrough">;
+    cap: z.ZodString;
+    source: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CompositionPassthroughFeature = z.infer<typeof CompositionPassthroughFeatureSchema>;
+export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"fields">;
+    cap: 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">>;
+    commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"forward">;
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+        cap: z.ZodString;
+        method: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"code">;
+        code: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"passthrough">;
+    cap: z.ZodString;
+    source: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export type CompositionFeature = z.infer<typeof CompositionFeatureSchema>;
+/**
+ * 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).
+ */
+export declare const CompositionNewTargetSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"new">;
+    type: z.ZodEnum<typeof DeviceType>;
+    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. */
+export declare const CompositionExistingTargetSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"existing">;
+    device: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CompositionExistingTarget = z.infer<typeof CompositionExistingTargetSchema>;
+export declare const CompositionTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"new">;
+    type: z.ZodEnum<typeof DeviceType>;
+    role: z.ZodOptional<z.ZodEnum<typeof DeviceRole>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"existing">;
+    device: z.ZodObject<{
+        addonId: z.ZodString;
+        stableId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export type CompositionTarget = z.infer<typeof CompositionTargetSchema>;
+export declare const CompositionSchema: z.ZodObject<{
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"new">;
+        type: z.ZodEnum<typeof DeviceType>;
+        role: z.ZodOptional<z.ZodEnum<typeof DeviceRole>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"existing">;
+        device: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">;
+    features: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"fields">;
+        cap: 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">>;
+        commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"forward">;
+            source: z.ZodObject<{
+                addonId: z.ZodString;
+                stableId: z.ZodString;
+            }, z.core.$strip>;
+            cap: z.ZodString;
+            method: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            code: z.ZodString;
+        }, z.core.$strip>], "kind">>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"passthrough">;
+        cap: z.ZodString;
+        source: z.ZodObject<{
+            addonId: z.ZodString;
+            stableId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type Composition = z.infer<typeof CompositionSchema>;
+export declare function compositionSourceKey(ref: CompositionSourceRef): string;
+export declare function compositionSliceKey(ref: CompositionSourceRef, cap: string): string;
+export declare function compositionReadKey(read: CompositionFieldRead): string;
+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[];

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

@@ -0,0 +1,63 @@
+/**
+ * One composed field, evaluated from what its sources say NOW (D659).
+ *
+ * Pure. The composer calls it on every source change, and the slice-5 editor
+ * will call it for its live preview, so both see the same answer.
+ *
+ * The rules (spec §2):
+ *  - a source that is offline or unreadable keeps its last value and is marked
+ *    STALE; the field is stale and keeps computing (D49);
+ *  - a source that is GONE makes the field UNAVAILABLE, `fatal`, and never a
+ *    plausible number (D393);
+ *  - a source that is unavailable but NOT gone (e.g. a cap unregistered at
+ *    runtime, R7b) makes the field UNAVAILABLE, non-fatal, `value: null`: it
+ *    may come back on its own, no block failure is raised for it;
+ *  - an expression that fails on a value makes the field unavailable for that
+ *    value, and NOT fatal: the next value may compute.
+ *
+ * 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
+ * momentarily unregistered) can never hide a later fatal one (a deleted
+ * source) behind an early return.
+ */
+import type { ExpressionValue } from '../expression/ast.js';
+import { type CompositionFieldRead, type CompositionFieldSource } from './composition.js';
+export interface SourceFreshReading {
+    readonly state: 'fresh';
+    readonly value: ExpressionValue;
+}
+export interface SourceStaleReading {
+    readonly state: 'stale';
+    readonly value: ExpressionValue;
+    readonly reason: string;
+}
+export interface SourceUnavailableReading {
+    readonly state: 'unavailable';
+    readonly reason: string;
+    /** True when the source is GONE: device or cap missing, two reads agreed. */
+    readonly fatal: boolean;
+}
+export type SourceReading = SourceFreshReading | SourceStaleReading | SourceUnavailableReading;
+export type SourceReader = (read: CompositionFieldRead) => SourceReading;
+export interface FieldValueOutcome {
+    readonly state: 'fresh' | 'stale';
+    readonly value: ExpressionValue;
+    readonly reason: string | null;
+    /** When a windowed builtin's answer flips on its own; null when nothing will. */
+    readonly deadline: number | null;
+}
+export interface FieldUnavailableOutcome {
+    readonly state: 'unavailable';
+    /** Always `null` — an unavailable field is never a stand-in value (D393). */
+    readonly value: null;
+    readonly reason: string;
+    readonly fatal: boolean;
+}
+export type FieldOutcome = FieldValueOutcome | FieldUnavailableOutcome;
+export interface EvaluateCompositionFieldInput {
+    readonly source: CompositionFieldSource;
+    readonly read: SourceReader;
+    readonly now: number;
+}
+export declare function evaluateCompositionField(input: EvaluateCompositionFieldInput): FieldOutcome;