@camstack/system 1.1.22 → 1.1.23

package/dist/builtins/device-manager/device-aggregation.d.ts

@@ -214,7 +214,14 @@ export declare function setWrapperActive(deps: AggregationDeps, input: {
  * bound caps expose, for the operator's cross-device wiring UI. Binding-driven:
  * walks `getBindings(deviceId)`, skips wrapper caps (their status schemas are
  * internal book-keeping, not wireable domain data), and enumerates each cap's
- * status schema leaf fields. Behavior unchanged from the inline provider method.
+ * status schema leaf fields (per-item fields included for item-array caps).
+ *
+ * `includeSynthesizable: true` (TARGET pickers only) additionally unions in
+ * UNBOUND device-scoped caps that declare `status.empty` (the synthesize-target
+ * marker) and whose `deviceTypes` admit this device's persisted type — so the
+ * FIRST link to a synthesize-only cap (consumables on an HA vacuum) can be
+ * authored before any binding exists. Default (absent/false) behavior is
+ * byte-identical to the binding-driven catalog.
  */
 export declare function getWireableFields(deps: AggregationDeps, input: Parameters<IDeviceManagerProvider['getWireableFields']>[0]): ReturnType<IDeviceManagerProvider['getWireableFields']>;
 export {};

package/dist/builtins/device-manager/device-bindings-store.d.ts

@@ -14,6 +14,9 @@ export interface BindingsDeps {
     readonly ctx: AddonContext;
     readonly capabilityRegistry: ICapabilityRegistry | undefined;
     readonly remoteNativeCaps: RemoteNativeCaps;
+    /** O(1) gate over devices that have `deviceLinks` (the addon's live set).
+     *  Optional: when absent, getBindings adds no virtual `linked` entries. */
+    readonly devicesWithLinks?: ReadonlySet<number>;
 }
 /**
  * Wire the push-fed cross-process native-cap cache (`remoteNativeCaps`).

package/dist/builtins/device-manager/device-link-cycle.d.ts

@@ -0,0 +1,18 @@
+import { DeviceLink } from '@camstack/types';
+/** The slice of a persisted meta row cycle detection needs. Structural subset
+ *  of `PersistedDeviceMeta` so tests (and future callers) can pass plain rows. */
+export interface LinkCycleMetaRow {
+    readonly id: number;
+    readonly stableId: string;
+    readonly parentDeviceId: number | null;
+    readonly deviceLinks?: readonly DeviceLink[];
+}
+/** Node key of the dependency graph: `${deviceId}:${cap}`. */
+type NodeKey = string;
+/**
+ * Detect whether replacing `editedDeviceId`'s links with `editedLinks` closes
+ * a dependency cycle. Returns the cycle as an ordered list of node keys
+ * (first node repeated at the end) or null when the set is safe.
+ */
+export declare function findDeviceLinkCycle(allMeta: Record<string, LinkCycleMetaRow>, editedDeviceId: number, editedLinks: readonly DeviceLink[]): readonly NodeKey[] | null;
+export {};

package/dist/builtins/device-manager/device-link-resolver.d.ts

@@ -1,15 +1,33 @@
 import { z } from 'zod';
-import { DeviceLink } from '@camstack/types';
+import { CapabilityStatusItemArray, DeviceLink } from '@camstack/types';
 /** One resolved source reading paired with the link that produced it. The
  *  `sourceValue` is already transformed; `undefined` skips the overlay. */
 export interface ResolvedLinkValue {
     readonly link: DeviceLink;
     readonly sourceValue: unknown;
 }
+/**
+ * Resolve one link's transformed value. Field sources read via `readField`
+ * (the caller supplies the sibling lookup — sync, e.g. the in-hub state
+ * mirror); literal sources use their per-device constant and never consult
+ * the reader. Returns `undefined` to skip the overlay (unreadable field).
+ * Pure. Async source reads (`resolveLinkedStatus`'s provider `getStatus`
+ * path) cannot use this helper for field sources — they branch on
+ * `source.kind` directly.
+ */
+export declare function resolveLinkValue(link: DeviceLink, readField: (cap: string, fieldPath: string) => unknown): unknown;
 /**
  * Overlay transformed source values onto `base` by dot-path, then validate the
  * result against the target cap's `statusSchema`. On validation failure the
  * overlay is discarded and `base` is returned unchanged (a misconfigured link
  * must never corrupt a cap response). Pure — all I/O happens in the caller.
+ *
+ * Item-array grouping (P2b): when the cap declares `status.itemArray`, links
+ * carrying a `target.itemKey` are grouped per key and upserted as items into
+ * the array (see `upsertItemArrayLinks`); their `fieldPath` is relative to
+ * ONE item ('level', 'status', 'label'). Links WITHOUT an itemKey keep the
+ * scalar dot-path behavior unchanged. A link with an itemKey on a cap that
+ * declares NO `itemArray` is dropped (its item-relative path must never be
+ * scalar-applied to the status root).
  */
-export declare function mergeLinkedStatus(base: Record<string, unknown>, resolved: readonly ResolvedLinkValue[], statusSchema?: z.ZodType): Record<string, unknown>;
+export declare function mergeLinkedStatus(base: Record<string, unknown>, resolved: readonly ResolvedLinkValue[], statusSchema?: z.ZodType, itemArray?: CapabilityStatusItemArray): Record<string, unknown>;

package/dist/builtins/device-manager/device-manager.addon.d.ts

@@ -59,10 +59,15 @@ export declare class DeviceManagerAddon extends BaseAddon {
     private linkTargets;
     /** `${sourceDeviceId}:${sourceCap}` → targets to recompute when that source changes. */
     private linkDependents;
-    /** Expected source `stableId`s (`${container}-${sourceKey}`) across all links,
+    /** Expected source `stableId`s (`${container}-${sourceKey}` for sibling
+     *  sources, the full `sourceStableId` for global sources) across all links,
      *  resolved or not — gates the `registerDevice` rebuild so only a registering
      *  device that IS a link source triggers a reindex (not every boot restore). */
     private expectedSourceStableIds;
+    /** In-flight `${deviceId}:${cap}` pairs of `resolveLinkedStatus` — the P2e
+     *  defensive re-entrancy guard bounding link cycles at resolve time. Mutated
+     *  in place (never reassigned), so the host exposes a direct reference. */
+    private readonly linkResolveInFlight;
     /** Test/diagnostic accessors. */
     linkTargetKeys(): string[];
     linkDependentsKeys(): string[];
@@ -104,7 +109,9 @@ export declare class DeviceManagerAddon extends BaseAddon {
     private discoveryProviderLabel;
     /** Provider ids that report `supportsDiscovery() === true` (probed in parallel). */
     private listDiscoveryCapableProviderIds;
-    /** Build the dependency context the extracted binding resolvers consume. */
+    /** Build the dependency context the extracted binding resolvers consume.
+     *  `devicesWithLinks` is mutated in place (never reassigned) so the direct
+     *  reference stays live — it gates the virtual `linked` binding step. */
     private get bindingsDeps();
     getBindings(input: {
         deviceId: number;