@camstack/types 1.2.264 → 1.2.265

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;

package/dist/composition/examples.d.ts

@@ -0,0 +1,10 @@
+import { type Composition, type CompositionSourceRef } from './composition.js';
+export declare const ROOM_OCCUPANCY_WINDOW_MS = 300000;
+export declare const ROOM_EXAMPLE_TEMPERATURE_SOURCES: readonly CompositionSourceRef[];
+export declare const ROOM_EXAMPLE_MOTION_SOURCES: readonly CompositionSourceRef[];
+export interface RoomExampleInput {
+    readonly temperatureSources: readonly CompositionSourceRef[];
+    readonly motionSources: readonly CompositionSourceRef[];
+    readonly occupancyWindowMs: number;
+}
+export declare function roomCompositionExample(input: RoomExampleInput): Composition;

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

@@ -0,0 +1,36 @@
+/**
+ * What an expression can PRODUCE: the static half of type validation at save
+ * (D659). The language is untyped at runtime; this walk gives the set of value
+ * kinds the result may take, so a save that would write a string into
+ * `celsius`, or a possible null into a non-nullable field, is refused by name
+ * before it is stored.
+ */
+import type { ExpressionValue } from '../expression/ast.js';
+export type ExpressionValueKind = 'number' | 'string' | 'boolean' | 'null';
+export type ExpressionKindSet = ReadonlySet<ExpressionValueKind>;
+export interface FixedKindRule {
+    readonly kind: 'fixed';
+    readonly result: readonly ExpressionValueKind[];
+}
+/** `coalesce`: the first non-null argument, null only when every argument may be null. */
+export interface CoalesceKindRule {
+    readonly kind: 'coalesce';
+}
+export type BuiltinKindRule = FixedKindRule | CoalesceKindRule;
+/** One rule per builtin. `expression-kinds.spec.ts` fails for a builtin missing here. */
+export declare const BUILTIN_RESULT_KINDS: Readonly<Record<string, BuiltinKindRule>>;
+export interface InferExpressionKindsInput {
+    readonly expr: string;
+    readonly bindingKinds: ReadonlyMap<string, ExpressionKindSet>;
+}
+export interface InferredKinds {
+    readonly ok: true;
+    readonly kinds: ExpressionKindSet;
+}
+export interface InferenceFailure {
+    readonly ok: false;
+    readonly error: string;
+}
+export type InferExpressionKindsResult = InferredKinds | InferenceFailure;
+export declare function kindOfValue(value: ExpressionValue): ExpressionValueKind;
+export declare function inferExpressionKinds(input: InferExpressionKindsInput): InferExpressionKindsResult;

package/dist/composition/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compositions: composed devices (D659). This is the module barrel; leaf files
+ * inside @camstack/types import the deep modules, never this file.
+ */
+export * from './composition.js';
+export * from './composition-graph.js';
+export * from './composition-report.js';
+export * from './evaluate-field.js';
+export * from './examples.js';
+export * from './expression-kinds.js';
+export * from './state-fields.js';
+export * from './validate-composition.js';

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

@@ -0,0 +1,19 @@
+/**
+ * What a capability's state field IS: kind, nullability, whether required. The
+ * validator needs nullability, which `enumerateSchemaFields` does not report,
+ * and that decides a field's unavailable mode (D393).
+ */
+import { z } from 'zod';
+import { type WireableField } from '../device/schema-fields.js';
+export interface StateFieldDescription {
+    readonly path: string;
+    readonly kind: WireableField['kind'];
+    readonly nullable: boolean;
+    readonly required: boolean;
+    /** Present only when `kind === 'enum'` — the closed set of strings the field accepts. */
+    readonly enumValues?: readonly string[];
+}
+export declare function describeStateField(schema: z.ZodType, path: string): StateFieldDescription | null;
+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[];

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

@@ -0,0 +1,46 @@
+/**
+ * Save-time validation of a composition (D659): shape, capability fit, field
+ * kinds, nullability, sources, cycles. 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
+ * re-runs at apply time, where the sources are the tracker's business.
+ */
+import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import { type Composition, type CompositionSourceRef } from './composition.js';
+import { type CompositionPeer } from './composition-graph.js';
+import type { CompositionFieldPlan, CompositionProblem, 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. */
+export declare const BASE_DEVICE_CAPS: ReadonlySet<string>;
+export interface CompositionSourceFound {
+    readonly kind: 'found';
+    readonly deviceId: number;
+    readonly caps: ReadonlySet<string>;
+}
+export interface CompositionSourceAbsent {
+    readonly kind: 'absent';
+}
+export interface CompositionSourceUnreadable {
+    readonly kind: 'unreadable';
+    readonly error: string;
+}
+export type CompositionSourceDescription = CompositionSourceFound | 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;
+    /** Every OTHER stored composition; cycles run through them. */
+    readonly peers: readonly CompositionPeer[];
+}
+export interface CompositionPlanResult {
+    readonly problems: readonly CompositionProblem[];
+    readonly fields: readonly CompositionFieldPlan[];
+}
+export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup): CompositionPlanResult;
+export declare function compositionSourceRefs(composition: Composition): readonly CompositionSourceRef[];
+export declare function validateComposition(composition: Composition, ctx: ValidateCompositionContext): CompositionValidation;

package/dist/device/schema-fields.d.ts

@@ -8,6 +8,9 @@ export interface WireableField {
      *  `target.itemKey`. Absent/false for plain status fields. */
     readonly item?: boolean;
 }
+/** Unwrap ZodNullable / ZodOptional / ZodDefault wrappers to reach the inner type.
+ *  Zod v4 exposes `.unwrap()` on all three wrapper classes. */
+export declare function unwrapSchema(schema: z.ZodType): z.ZodType;
 /** Walk a cap status schema into flat wireable leaf fields (dotted paths).
  *  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
  *  so fields with null live values are still offered. Arrays / unknown shapes

package/dist/expression/builtins.d.ts

@@ -1,10 +1,38 @@
+/**
+ * Frozen, null-prototype builtin function table for the expression engine
+ * (spec §4 rule 4). The table is the SOLE surface of callable functions: the
+ * parser rejects any callee not in it, and the evaluator gates each call on an
+ * own-property check against it.
+ *
+ * Because the object has a NULL prototype AND is `Object.freeze`d:
+ *  - it cannot be polluted (no `__proto__` / `constructor` write reaches it);
+ *  - a lookup for `toString` / `hasOwnProperty` / `constructor` finds NOTHING
+ *    (there is no `Object.prototype` in the chain), so those names are not
+ *    callable — they are simply "unknown function" at parse time.
+ *
+ * Every numeric argument is validated as a finite number and every numeric
+ * RESULT is re-checked finite, so `/0`, `sqrt(-1)` (→ NaN) and overflow
+ * (`pow(10,400)` → Infinity) all raise `ExpressionEvalError` and fail the link
+ * closed rather than emitting a garbage value.
+ */
 import type { ExpressionValue } from './ast.js';
-/** Optional runtime hooks the evaluator threads through to builtins. Stage U
- *  installs the real unit-conversion table here; absent → the `convert` stub. */
+/** Optional runtime hooks the evaluator threads through to builtins. */
 export interface ExpressionEvalHooks {
     /** Convert `value` from unit `from` to unit `to`; `null` when the pair is
      *  not convertible. Absent hook → `convert` uses its identity-only stub. */
     readonly convert?: (value: number, from: string, to: string) => number | null;
+    /**
+     * Epoch ms of THIS evaluation. `evaluateExpressionSource` sets it to the same
+     * `now` the scope carries. A windowed builtin with no clock fails closed:
+     * reading the wall clock here would make an evaluation unrepeatable.
+     */
+    readonly now?: number;
+    /**
+     * Called by a windowed builtin with the instant its answer will change ON ITS
+     * OWN, with no source event. The composer arms ONE timer at the earliest such
+     * instant. That is a deadline, never a poll (D659).
+     */
+    readonly noteDeadline?: (at: number) => void;
 }
 export interface ExpressionBuiltin {
     readonly minArgs: number;