@camstack/types 1.2.267 → 1.2.268

package/dist/capabilities/device-extension.cap.d.ts

@@ -2,11 +2,10 @@
  * `device-extension` — ONE place to see and author what a device is extended
  * with by OTHER devices (D648).
  *
- * **A contract, not a store.** Every slot (`linked-devices`,
- * `doorbell-source`, later `consumables-graft`) is declared by the cap that
- * owns the function (`extensionSlots` in its `*.cap.ts`, D4) and SERVED by the
- * addon that already owns its store, over that store and its existing write
- * path. This cap persists nothing and has no config method (guarded by
+ * **A contract, not a store.** Every slot (`linked-devices`, `doorbell-source`)
+ * is declared by the cap that owns the function (`extensionSlots` in its
+ * `*.cap.ts`, D4) and SERVED by the addon that already owns its store, over
+ * that store and its existing write path. This cap persists nothing and has no config method (guarded by
  * `scripts/check-extension-slots.ts`): D62 applied to the whole feature, and
  * D3 — no shadow registry.
  *
@@ -27,6 +26,11 @@
  * The slot's value travels as the generated discriminated union
  * (`ExtensionSlotValue`, keyed on `slot`), so a value under the wrong slot is
  * a schema error before it reaches any owner.
+ *
+ * **Associations only.** A slot LISTS other devices on its host. A host that
+ * GAINS a capability from other devices is a composition (D663, amends D648:
+ * the reserved `graft` shape, its `projects` and its `enabled` switch were
+ * retired unimplemented).
  */
 import { z } from 'zod';
 import { type InferProvider } from './capability-definition.js';
@@ -58,7 +62,7 @@ export type ExtensionSource = z.infer<typeof ExtensionSourceSchema>;
 /**
  * How one picked source stands. `missing` — no such device (deleted, or an id
  * that never existed); `foreign` — a device the slot's owner cannot read from
- * (slice 2's cross-owner graft source); `unavailable` — it exists but is not a
+ * (a source owned by another addon); `unavailable` — it exists but is not a
  * valid source now (a container, which is never a pick). A source in any of
  * these states is SHOWN, never silently dropped or re-pointed.
  */
@@ -107,8 +111,6 @@ export declare const ExtensionSlotStateSchema: z.ZodObject<{
         "doorbell-source": "doorbell-source";
     }>;
     authority: z.ZodString;
-    enabled: z.ZodNullable<z.ZodBoolean>;
-    projects: z.ZodNullable<z.ZodString>;
     activation: z.ZodNullable<z.ZodObject<{
         state: z.ZodEnum<{
             unknown: "unknown";
@@ -169,8 +171,6 @@ export declare const ExtensionSlotRowSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         "doorbell-source": "doorbell-source";
     }>;
     authority: z.ZodString;
-    enabled: z.ZodNullable<z.ZodBoolean>;
-    projects: z.ZodNullable<z.ZodString>;
     activation: z.ZodNullable<z.ZodObject<{
         state: z.ZodEnum<{
             unknown: "unknown";
@@ -244,7 +244,8 @@ export type ExtensionCandidates = z.infer<typeof ExtensionCandidatesSchema>;
 /**
  * What a write did. `none` — applied in place. `host` / `parent` — the owner
  * reloaded the host (or, for an accessory child, its parent) because the
- * write changed what the host REGISTERS (a graft switched on or off, slice 2).
+ * write changed what the host REGISTERS. A slot never adds a capability to its
+ * host — that is a composition (D663) — so today's owners answer `none`.
  */
 export declare const ExtensionSetResultSchema: z.ZodObject<{
     applied: z.ZodLiteral<true>;
@@ -318,8 +319,6 @@ export declare const deviceExtensionCapability: {
                 "doorbell-source": "doorbell-source";
             }>;
             authority: z.ZodString;
-            enabled: z.ZodNullable<z.ZodBoolean>;
-            projects: z.ZodNullable<z.ZodString>;
             activation: z.ZodNullable<z.ZodObject<{
                 state: z.ZodEnum<{
                     unknown: "unknown";

package/dist/capabilities/device-state.cap.d.ts

@@ -1,4 +1,69 @@
 import { z } from 'zod';
+/**
+ * Per-field ownership (D663). A composition may CLAIM fields of a native
+ * cap's runtime-state slice on an existing device: `replace` overlays the
+ * claimed fields on the native slice, `add` builds a slice the device does
+ * not natively have. Declared here — once — so the hub mirror (Task 5) and
+ * the claim methods (Task 6) share one union.
+ */
+export declare const FieldClaimModeSchema: z.ZodEnum<{
+    replace: "replace";
+    add: "add";
+}>;
+export type FieldClaimMode = z.infer<typeof FieldClaimModeSchema>;
+/** What a claim, patch or release answers. A refusal always names its reason. */
+export declare const ClaimOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    changed: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    code: z.ZodEnum<{
+        "unknown-device": "unknown-device";
+        "owned-by-other": "owned-by-other";
+        "not-claimed": "not-claimed";
+        "field-not-claimed": "field-not-claimed";
+        "invalid-slice": "invalid-slice";
+        "row-unreadable": "row-unreadable";
+        "migration-in-flight": "migration-in-flight";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>], "ok">;
+export type ClaimOutcome = z.infer<typeof ClaimOutcomeSchema>;
+/** One claim as `listClaims` reports it. `fields` is the PLANNED set, explicit (ruling S5). */
+export declare const FieldClaimSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    capName: z.ZodString;
+    owner: z.ZodString;
+    mode: z.ZodEnum<{
+        replace: "replace";
+        add: "add";
+    }>;
+    fields: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type FieldClaim = z.infer<typeof FieldClaimSchema>;
+/**
+ * What `listClaims` answers. The claims INDEX is a listing projection loaded
+ * from the settings store at boot; until a load has succeeded it is
+ * `not-loaded`, never `[]` — an unanswered question must not look like an
+ * empty answer (D315).
+ */
+export declare const ClaimsListingSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"loaded">;
+    claims: z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        capName: z.ZodString;
+        owner: z.ZodString;
+        mode: z.ZodEnum<{
+            replace: "replace";
+            add: "add";
+        }>;
+        fields: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"not-loaded">;
+    reason: z.ZodString;
+}, z.core.$strip>], "state">;
+export type ClaimsListing = z.infer<typeof ClaimsListingSchema>;
 /**
  * `deviceState` — generic, cap-agnostic surface for cross-process
  * access to per-device runtime state. Read pendant for every cap's
@@ -32,8 +97,12 @@ export declare const deviceStateCapability: {
         readonly getSnapshot: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>, import("./capability-definition.js").CapabilityMethodKind>;
-        /** Single cap slice. Returns null when the slice hasn't been
-         *  written or the device isn't registered. */
+        /**
+         * Single cap slice — the EFFECTIVE one: the merge every consumer sees, null
+         * when the slice hasn't been written, the device isn't registered, or a
+         * claim HOLDS the cap (D663). Never the native shadow — that is
+         * `getNativeCapSlice`, admin-only.
+         */
         readonly getCapSlice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
             capName: z.ZodString;
@@ -79,6 +148,121 @@ export declare const deviceStateCapability: {
             capName: z.ZodString;
             slice: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Claim `fields` of `capName` on a device for `owner`. The PLANNED field set
+         * is explicit (ruling S5): `values` may be partial and MUST be a subset of
+         * `fields` (else `field-not-claimed`); a claimed field with no value is HELD,
+         * never answered from the native. A re-claim by the same owner REPLACES
+         * `fields` and MERGES `values` — a field dropped from `fields` loses its
+         * value. Another owner's claim → `owned-by-other`.
+         */
+        readonly claimFields: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            capName: z.ZodString;
+            owner: z.ZodString;
+            mode: z.ZodEnum<{
+                replace: "replace";
+                add: "add";
+            }>;
+            fields: z.ZodArray<z.ZodString>;
+            values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            changed: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            ok: z.ZodLiteral<false>;
+            code: z.ZodEnum<{
+                "unknown-device": "unknown-device";
+                "owned-by-other": "owned-by-other";
+                "not-claimed": "not-claimed";
+                "field-not-claimed": "field-not-claimed";
+                "invalid-slice": "invalid-slice";
+                "row-unreadable": "row-unreadable";
+                "migration-in-flight": "migration-in-flight";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strip>], "ok">, "mutation">;
+        /**
+         * Write owned values. Every key of `values` must be in the claim's `fields`
+         * (`field-not-claimed`); no claim → `not-claimed`; another owner's →
+         * `owned-by-other`. Partial patches merge (S5); debounced like a native slice.
+         */
+        readonly patchOwnedFields: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            capName: z.ZodString;
+            owner: z.ZodString;
+            values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            changed: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            ok: z.ZodLiteral<false>;
+            code: z.ZodEnum<{
+                "unknown-device": "unknown-device";
+                "owned-by-other": "owned-by-other";
+                "not-claimed": "not-claimed";
+                "field-not-claimed": "field-not-claimed";
+                "invalid-slice": "invalid-slice";
+                "row-unreadable": "row-unreadable";
+                "migration-in-flight": "migration-in-flight";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strip>], "ok">, "mutation">;
+        /**
+         * Hand the cap back. A `replace` re-emits the native slice exactly as last
+         * written; an `add` leaves the mirror. `not-claimed` also removes a stale
+         * index entry — the index self-heals through this method.
+         */
+        readonly releaseClaim: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            capName: z.ZodString;
+            owner: z.ZodString;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            changed: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            ok: z.ZodLiteral<false>;
+            code: z.ZodEnum<{
+                "unknown-device": "unknown-device";
+                "owned-by-other": "owned-by-other";
+                "not-claimed": "not-claimed";
+                "field-not-claimed": "field-not-claimed";
+                "invalid-slice": "invalid-slice";
+                "row-unreadable": "row-unreadable";
+                "migration-in-flight": "migration-in-flight";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strip>], "ok">, "mutation">;
+        /** Every claim the index lists, optionally those whose owner starts with `ownerPrefix`. */
+        readonly listClaims: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            ownerPrefix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"loaded">;
+            claims: z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                capName: z.ZodString;
+                owner: z.ZodString;
+                mode: z.ZodEnum<{
+                    replace: "replace";
+                    add: "add";
+                }>;
+                fields: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"not-loaded">;
+            reason: z.ZodString;
+        }, z.core.$strip>], "state">, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * The NATIVE slice — what the provider wrote, the shadow under a `replace`
+         * claim — for the owner's derived reads. Admin-only (D224, ruled in the
+         * Task 6 review): the shadow is a second truth beside the merge, and the
+         * event channel already refuses it to everyone but the composer; a
+         * protected read of it would hand out what the events withhold.
+         */
+        readonly getNativeCapSlice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>, import("./capability-definition.js").CapabilityMethodKind>;
     };
     readonly events: {
         /**

package/dist/capabilities/index.d.ts

@@ -38,7 +38,7 @@ export { cameraStreamsCapability, type ICameraStreamsProvider, type PickedCamStr
 export { emitsCollectionSelector, extractNestedAddonId, isArrayOutputSchema, isCollectionArrayMethod, isObjectInput, isVoidInput, kebabToCamel, looseSchema, objectInputDeclaresAddonId, objectInputDeclaresRequiredDeviceId, procedureAuthKey, resolveMethodAuth, } from './cap-router-predicates.js';
 export type { CapabilityDefinition, CapabilityEventSchema, CapabilityMethodAuth, CapabilityMethodCaller, CapabilityMethodKind, CapabilityMethodOptions, CapabilityMethodSchema, CapabilityMountHint, CapabilityMountKind, CapabilityStatusItemArray, CapabilityStatusKind, CapabilityStatusSchema, CapCaller, DeviceConfigDerivedFormUi, DeviceConfigSpec, DeviceConfigUiSpec, DeviceConfigWidgetUi, DeviceSettingsContribution, InferDeviceProxyCap, InferEvents, InferName, InferNativeProvider, InferProvider, InferRuntimeState, ProviderKind, RuntimeStateDurability, UiContribution, UiContributionKind, UiContributionRemote, } from './capability-definition.js';
 export { DEFAULT_RUNTIME_STATE_DURABILITY, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, event, expandCapMethods, isDeviceConfigCap, method, optionalMethod, PROVIDER_PIN_FIELD, resolveCapMount, } from './capability-definition.js';
-export { CORE_BLOCK_ADDON_PREFIX, CORE_BLOCKS_ADDON_ID, type CompositionBlockInput, CompositionBlockInputSchema, type CompositionBlockPatch, type CoreBlock, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockInput, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockSource, type CoreBlockSourceKind, CoreBlockSourceSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockComposition, coreBlockIdFromAddonId, coreBlockSourceKind, coreBlocksCapability, type CompositionGetRead, CompositionGetReadSchema, type CompositionListRead, CompositionListReadSchema, type CompositionStateRead, CompositionStateReadSchema, type CompositionView, CompositionViewSchema, type ICoreBlocksProvider, } from './core-blocks.cap.js';
+export { CORE_BLOCK_ADDON_PREFIX, CORE_BLOCKS_ADDON_ID, type CompositionBlockInput, CompositionBlockInputSchema, type CompositionBlockPatch, type CoreBlock, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockInput, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockSource, type CoreBlockSourceKind, CoreBlockSourceSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockComposition, coreBlockIdFromAddonId, coreBlockSourceKind, coreBlocksCapability, type CompositionCustomizationRead, CompositionCustomizationReadSchema, type CompositionGetRead, CompositionGetReadSchema, type CompositionListRead, CompositionListReadSchema, type CompositionStateRead, CompositionStateReadSchema, type CompositionView, CompositionViewSchema, type ICoreBlocksProvider, } from './core-blocks.cap.js';
 export { COMPOSER_RUNNER_ID, type ComposerApplyInput, ComposerApplyInputSchema, type ComposerApplyResult, ComposerApplyResultSchema, type ComposerBlock, ComposerBlockSchema, type ComposerBlockVerdict, ComposerBlockVerdictSchema, type ComposerUnreadableBlock, ComposerUnreadableBlockSchema, composerCapability, type IComposerProvider, } from './composer.cap.js';
 export * from './custom-actions.js';
 export type { CustomModelDescriptor, ICustomModelRegistryProvider, } from './custom-model-registry.cap.js';
@@ -55,7 +55,7 @@ export { DeviceExportStatusSchema, deviceExportCapability, ExportSetupFieldSchem
 export type { DeviceInfo, DeviceManagerApplyInitialMetaInput } from './device-manager.cap.js';
 export { ConfigEntrySchema, DEVICE_CHILDREN_BATCH_MAX, DeviceInfoSchema, deviceManagerCapability, type IDeviceManagerProvider, type LinkedDevice, LinkedDeviceSchema, type LinkedDevicesMode, LinkedDevicesModeSchema, LINKED_DEVICES_SLOT, type LinkedDevicesSlotValue, LinkedDevicesSlotValueSchema, type MigrateDeviceResult, MigrateDeviceResultSchema, type MigrateSwitchOutcome, MigrateSwitchOutcomeSchema, type MigrateSwitchReport, MigrateSwitchReportSchema, } from './device-manager.cap.js';
 export { DiscoveredDeviceSchema, deviceProviderCapability, ProviderStatusSchema, } from './device-provider.cap.js';
-export { deviceStateCapability } from './device-state.cap.js';
+export { type ClaimOutcome, ClaimOutcomeSchema, type ClaimsListing, ClaimsListingSchema, deviceStateCapability, type FieldClaim, type FieldClaimMode, FieldClaimModeSchema, FieldClaimSchema, } from './device-state.cap.js';
 export type { EmbeddingFailedModel, EmbeddingFailedRequirement, EmbeddingModelFailure, EmbeddingRefusal, EmbeddingRefusalCode, EmbeddingTower, IEmbeddingEncoderProvider, } from './embedding-encoder.cap.js';
 export { EMBEDDING_MODEL_FAILED, EMBEDDING_REQUIREMENTS_FAILED, EMBEDDING_REQUIREMENTS_UNAVAILABLE, EmbeddingFailedModelSchema, EmbeddingFailedRequirementSchema, EmbeddingInfoSchema, EmbeddingRefusalCodeSchema, EmbeddingResultSchema, EmbeddingTowerSchema, embeddingEncoderCapability, embeddingModelFailedError, embeddingModelFailedOf, embeddingRefusalOf, embeddingRequirementsFailedError, embeddingRequirementsUnavailableError, isEmbeddingModelFailed, } from './embedding-encoder.cap.js';
 export type { FailureContribution, IFailureContributionProvider, } from './failure-contribution.cap.js';
@@ -145,7 +145,7 @@ export { type ClimateControlStatus, ClimateControlStatusSchema, climateControlCa
 export { type ColorHsvTriplet, type ColorInput, type ColorRgbTriplet, type ColorStatus, ColorStatusSchema, colorCapability, type IColorProvider, } from './color.cap.js';
 export { CONNECTION_TEST_TIMEOUT_MS, ConnectionTestDescriptorSchema, ConnectionTestInputSchema, type ConnectionTestOutcome, ConnectionTestOutcomeSchema, connectionTestCapability, type IConnectionTestProvider, } from './connection-test.cap.js';
 export { type ConnectivityStatus, ConnectivityStatusSchema, connectivityCapability, type IConnectivityProvider, } from './connectivity.cap.js';
-export { type ConsumableItem, ConsumableItemSchema, type ConsumablesStatus, ConsumablesStatusSchema, consumablesCapability, type IConsumablesProvider, } from './consumables.cap.js';
+export { type ConsumableItem, ConsumableItemSchema, type ConsumableRemaining, ConsumableRemainingSchema, type ConsumableRemainingUnit, ConsumableRemainingUnitSchema, type ConsumablesStatus, ConsumablesStatusSchema, consumablesCapability, type IConsumablesProvider, } from './consumables.cap.js';
 export { type ContactStatus, ContactStatusSchema, contactCapability, type IContactProvider, } from './contact.cap.js';
 export { type ControlKind, ControlKindSchema, type ControlSetValueInput, type ControlStatus, ControlStatusSchema, controlCapability, type IControlProvider, } from './control.cap.js';
 export { type CoverState, CoverStateSchema, type CoverStatus, CoverStatusSchema, coverCapability, type ICoverProvider, } from './cover.cap.js';

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

@@ -6,31 +6,64 @@
  * through another composition, is refused at save by name (spec §2).
  *
  * The graph is built for ONE save: the CANDIDATE composition (the one being
- * validated) plus every STORED composition. The candidate ALWAYS replaces any
- * stored peer that targets the same device, regardless of where that stored
- * peer sits in `stored` — whether a save introduces or removes a cycle must
- * never depend on array order. Two DIFFERENT stored peers that (wrongly)
- * target the same device are corrupted state, not a cycle to resolve by
- * picking one silently; that is refused by name (D391).
+ * validated) plus every STORED composition. The candidate replaces its own old
+ * version, identified BY BLOCK ID wherever it sits in `stored` — whether a save
+ * introduces or removes a cycle must never depend on array order. A DIFFERENT
+ * block targeting the candidate's device is refused by name: one composition
+ * per device (D663). Two different stored peers that (wrongly) target the same
+ * device are corrupted state, not a cycle to resolve by picking one silently;
+ * that is refused by name too (D391).
+ *
+ * A customization of an EXISTING device reads that device's NATIVE value for a
+ * field it replaces or does not write ("Invert state" reads the `on` it
+ * replaces): such a self-read is no edge, so it is never a cycle (D663).
+ * Another composition reading that field reads the customizer's output.
  *
  * `findCompositionCycles` reports at least one cycle per cycle-SET (the DFS
- * marks a node `done` after its first expansion) — enough to refuse a save,
- * not to enumerate every elementary cycle through a shared node. A dotted
+ * marks a node `done` after its first expansion) — not every elementary cycle
+ * through a shared node, so the path it names may AVOID the candidate while
+ * one through it goes unreported. What a save refuses is therefore decided per
+ * strongly connected component (`findCandidateCycles`, C-1). A dotted
  * `fieldPath` is matched only as an exact string: a write to `state.value` and
  * a read of `state` would not connect (no nested field writes exist yet).
+ *
+ * An item leaf is its own node, `…#consumables.items[desiccant].status`
+ * (`featureFieldEntries`), so two items sharing an inner path never merge. No
+ * READ can name an array element (`describeStateField` never describes one),
+ * so an item node is write-only: its edges to sources are what the check needs.
  */
 import { type Composition, type CompositionSourceRef } from './composition.js';
 export interface CompositionPeer {
+    /** The block that stores this composition — its identity (D663). */
+    readonly blockId: string;
     /** The device this composition writes: `composedDeviceRef(blockId)` for a new target. */
     readonly target: CompositionSourceRef;
     readonly composition: Composition;
+    /** `"cap.field"` keys this composition REPLACES on an existing target; its reads of them are native. */
+    readonly replaced?: ReadonlySet<string>;
 }
 export interface CompositionCycle {
     /** Node keys, first and last equal. */
     readonly path: readonly string[];
 }
-/** Two stored compositions both target the same device — refused by name, never silently resolved. */
+/** Two blocks' compositions target the same device — refused by name, never silently resolved. */
 export declare class CompositionGraphError extends Error {
 }
 export declare function compositionEdges(candidate: CompositionPeer, stored: readonly CompositionPeer[]): ReadonlyMap<string, readonly string[]>;
 export declare function findCompositionCycles(candidate: CompositionPeer, stored: readonly CompositionPeer[]): readonly CompositionCycle[];
+/** A cycle-bearing strongly connected component that holds one of the candidate's nodes. */
+export interface CandidateCycle {
+    /** One representative cycle through a candidate node inside the component: first and last equal. */
+    readonly path: readonly string[];
+    /** Every node of the component — what the save would close a loop through. */
+    readonly component: ReadonlySet<string>;
+}
+/**
+ * The cycles THIS save closes, decided per strongly connected component — never
+ * per reported DFS path, which names one back-edge per revisit and can report a
+ * component's cycle by a path that avoids the candidate while the one through it
+ * goes unreported. A component refuses when it holds a candidate node and a
+ * cycle (more than one node, or a self-loop). Components without a candidate
+ * node are not this save's cycles.
+ */
+export declare function findCandidateCycles(candidate: CompositionPeer, stored: readonly CompositionPeer[]): readonly CandidateCycle[];

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

@@ -0,0 +1,25 @@
+/**
+ * Item-array fields of a composition (D663): `consumables.items[<key>]`.
+ *
+ * Items are addressed through the cap's `status.itemArray` descriptor — the
+ * one the source picker already uses — so a cap without one is refused
+ * (`not-item-array`). A composition that names `items` owns the WHOLE array.
+ * Each item leaf is planned as its own field, carrying `item`, and keyed by
+ * `compositionFieldKey` so two items sharing an inner path never share a
+ * record or a graph node.
+ *
+ * The composer sets some item fields itself: the key and label (from the
+ * entry) and {@link COMPOSED_ITEM_FIXED_FIELDS}. A source for any of them is
+ * refused by name (`item-field-reserved`) — `resettable` is fixed `false`
+ * because `reset` is refused until commands arrive (slice 3).
+ */
+import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import { type CompositionFieldsFeature } from './composition.js';
+import type { CompositionFeatureMode } from './composition-report.js';
+import { type CompositionPlanResult } from './plan-result.js';
+import type { CapabilityLookup } from './validate-composition.js';
+/** Item fields the composer writes itself, with the value it writes. */
+export declare const COMPOSED_ITEM_FIXED_FIELDS: {
+    readonly resettable: false;
+};
+export declare function planItems(def: CapabilityDefinition, feature: CompositionFieldsFeature, featureIndex: number, lookupCap: CapabilityLookup, mode?: CompositionFeatureMode): CompositionPlanResult;

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";