@camstack/system 1.1.22 → 1.1.23

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -1,5 +1,5 @@
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
-import { BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceRole, DeviceStatusSchema, DeviceType, EventCategory, STREAM_PROFILE_META, WELL_KNOWN_TAB_MAP, applyTransform, buildStreamParamsConfigSchema, deviceManagerCapability, deviceStateCapability, deviceStatusCapability, enumerateSchemaFields, errMsg, getByPath, isDeviceConfigCap, parseStreamParamsFormPatch, setByPath, sleep } from "@camstack/types";
+import { ALL_CAPABILITY_DEFINITIONS, BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceRole, DeviceStatusSchema, DeviceType, EventCategory, STREAM_PROFILE_META, WELL_KNOWN_TAB_MAP, applyTransform, buildStreamParamsConfigSchema, deviceManagerCapability, deviceStateCapability, deviceStatusCapability, enumerateItemArrayFields, enumerateSchemaFields, errMsg, getByPath, isDeviceConfigCap, parseStreamParamsFormPatch, setByPath, sleep } from "@camstack/types";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 /**
@@ -504,6 +504,21 @@ async function getBindings(deps, input) {
 		});
 		seenCaps.add(entry.capName);
 	}
+	if (deps.devicesWithLinks?.has(input.deviceId)) {
+		const row = ((await deps.ctx.settings.readAddonStore()).deviceMeta ?? {})[String(input.deviceId)];
+		for (const link of row?.deviceLinks ?? []) {
+			const capName = link.target.cap;
+			if (seenCaps.has(capName)) continue;
+			entries.push({
+				capName,
+				kind: "linked",
+				providerAddonId: deps.ctx.id,
+				providerNodeId: deps.ctx.kernel.localNodeId ?? "hub",
+				nativeAddonId: ""
+			});
+			seenCaps.add(capName);
+		}
+	}
 	return {
 		deviceId: input.deviceId,
 		entries
@@ -1166,11 +1181,47 @@ async function setWrapperActive(deps, input) {
 	});
 }
 /**
+* Build the wireable-cap entry for one capability definition: the status
+* schema's scalar leaf fields plus — for an item-array cap
+* (`status.itemArray`) — the per-item fields tagged `item: true` (a link
+* targeting one must carry a `target.itemKey`) and the cap-level `itemArray`
+* descriptor so the UI can address items. Returns null when the cap exposes
+* nothing wireable (no status schema / no leaf fields).
+*/
+function wireableEntryForDef(capName, def) {
+	const status = def.status;
+	const schema = status?.schema;
+	if (!schema) return null;
+	const itemArray = status.itemArray;
+	const fields = [...enumerateSchemaFields(schema), ...itemArray ? enumerateItemArrayFields(itemArray) : []].map((f) => ({
+		path: f.path,
+		kind: f.kind,
+		...f.enumValues !== void 0 ? { enumValues: [...f.enumValues] } : {},
+		...f.item === true ? { item: true } : {}
+	}));
+	if (fields.length === 0) return null;
+	return {
+		cap: capName,
+		fields,
+		...itemArray ? { itemArray: {
+			path: itemArray.path,
+			keyField: itemArray.keyField
+		} } : {}
+	};
+}
+/**
 * Per-device wireable-field catalog — the domain status fields a device's
 * 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.
 */
 async function getWireableFields(deps, input) {
 	const { deviceId } = input;
@@ -1184,20 +1235,20 @@ async function getWireableFields(deps, input) {
 		seen.add(entry.capName);
 		const def = reg.getDefinition(entry.capName);
 		if (!def || def.kind === "wrapper") continue;
-		const schema = def.status?.schema;
-		if (!schema) continue;
-		const fields = enumerateSchemaFields(schema).map((f) => f.enumValues !== void 0 ? {
-			path: f.path,
-			kind: f.kind,
-			enumValues: [...f.enumValues]
-		} : {
-			path: f.path,
-			kind: f.kind
-		});
-		if (fields.length > 0) caps.push({
-			cap: entry.capName,
-			fields
-		});
+		const wireable = wireableEntryForDef(entry.capName, def);
+		if (wireable) caps.push(wireable);
+	}
+	if (input.includeSynthesizable === true) {
+		const deviceType = ((await deps.ctx.settings.readAddonStore()).deviceMeta ?? {})[String(deviceId)]?.type;
+		if (deviceType !== void 0) for (const def of ALL_CAPABILITY_DEFINITIONS) {
+			if (seen.has(def.name)) continue;
+			if (def.scope !== "device" || def.kind === "wrapper") continue;
+			if (def.status?.empty === void 0) continue;
+			if (def.deviceTypes && !def.deviceTypes.some((t) => t === deviceType)) continue;
+			seen.add(def.name);
+			const wireable = wireableEntryForDef(def.name, def);
+			if (wireable) caps.push(wireable);
+		}
 	}
 	return { caps };
 }
@@ -1311,6 +1362,99 @@ var DeviceEventPropagator = class {
 	}
 };
 //#endregion
+//#region src/builtins/device-manager/device-link-cycle.ts
+function nodeKey(deviceId, cap) {
+	return `${deviceId}:${cap}`;
+}
+/**
+* Resolve a link source to its `(deviceId, cap)` node, or null when the
+* source is a literal (no device) or does not resolve to a known device.
+* Sibling FIELD sources resolve against the TARGET's container stableId
+* (its parent's, falling back to its own for a top-level target) — the same
+* rule `rebuildLinkDependents` / `resolveLinkedStatus` apply.
+*/
+function resolveSourceNode(link, targetRow, rowById, idByStableId) {
+	const src = link.source;
+	if (src.kind === "literal") return null;
+	const wantedStableId = src.kind === "global" ? src.sourceStableId : `${targetRow.parentDeviceId !== null ? rowById.get(targetRow.parentDeviceId)?.stableId ?? targetRow.stableId : targetRow.stableId}-${src.sourceKey}`;
+	const srcId = idByStableId.get(wantedStableId);
+	if (srcId === void 0) return null;
+	return nodeKey(srcId, src.cap);
+}
+/**
+* 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.
+*/
+function findDeviceLinkCycle(allMeta, editedDeviceId, editedLinks) {
+	const rows = Object.values(allMeta);
+	const rowById = /* @__PURE__ */ new Map();
+	const idByStableId = /* @__PURE__ */ new Map();
+	for (const r of rows) {
+		rowById.set(r.id, r);
+		if (!idByStableId.has(r.stableId)) idByStableId.set(r.stableId, r.id);
+	}
+	const dependsOn = /* @__PURE__ */ new Map();
+	const addEdges = (row, links) => {
+		for (const link of links) {
+			const srcNode = resolveSourceNode(link, row, rowById, idByStableId);
+			if (srcNode === null) continue;
+			const tNode = nodeKey(row.id, link.target.cap);
+			const list = dependsOn.get(tNode) ?? [];
+			list.push(srcNode);
+			dependsOn.set(tNode, list);
+		}
+	};
+	for (const r of rows) {
+		const links = r.id === editedDeviceId ? editedLinks : r.deviceLinks ?? [];
+		if (links.length > 0) addEdges(r, links);
+	}
+	const roots = [...new Set(editedLinks.map((l) => nodeKey(editedDeviceId, l.target.cap)))];
+	for (const root of roots) {
+		const cycle = dfsFindCycle(root, dependsOn);
+		if (cycle) return cycle;
+	}
+	return null;
+}
+/** Iterative DFS from `root` over `dependsOn`; returns the first back-edge
+*  cycle path (closed — first node repeated last) or null. */
+function dfsFindCycle(root, dependsOn) {
+	const onPath = /* @__PURE__ */ new Set();
+	const done = /* @__PURE__ */ new Set();
+	const path = [];
+	const stack = [{
+		node: root,
+		nextChild: 0
+	}];
+	onPath.add(root);
+	path.push(root);
+	while (stack.length > 0) {
+		const frame = stack[stack.length - 1];
+		const children = dependsOn.get(frame.node) ?? [];
+		if (frame.nextChild < children.length) {
+			const child = children[frame.nextChild];
+			frame.nextChild += 1;
+			if (onPath.has(child)) {
+				const start = path.indexOf(child);
+				return [...path.slice(start), child];
+			}
+			if (done.has(child)) continue;
+			stack.push({
+				node: child,
+				nextChild: 0
+			});
+			onPath.add(child);
+			path.push(child);
+			continue;
+		}
+		stack.pop();
+		onPath.delete(frame.node);
+		path.pop();
+		done.add(frame.node);
+	}
+	return null;
+}
+//#endregion
 //#region src/builtins/device-manager/device-meta-actions.ts
 /**
 * Device meta-mutation + persistence actions for the device-manager addon —
@@ -1872,6 +2016,8 @@ async function setChildLayout(pctx, input) {
 */
 async function setDeviceLinks(pctx, input) {
 	const { deviceId, deviceLinks } = input;
+	const cycle = findDeviceLinkCycle(await pctx.metaStore.readMeta(), deviceId, deviceLinks);
+	if (cycle) throw new Error(`[device-manager] setDeviceLinks: cross-device link cycle: ${cycle.join(" → ")}`);
 	await pctx.metaStore.withMetaWriteLock(async () => {
 		const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
 		if (!persisted) throw new Error(`[device-manager] setDeviceLinks: unknown device id=${deviceId}`);
@@ -2194,13 +2340,15 @@ function buildLinkIndexes(entries) {
 			sourceDeviceId
 		});
 		targets.set(tKey, tList);
-		const sKey = `${sourceDeviceId}:${link.source.cap}`;
-		const sList = dependents.get(sKey) ?? [];
-		sList.push({
-			targetDeviceId,
-			targetCap: link.target.cap
-		});
-		dependents.set(sKey, sList);
+		if (link.source.kind !== "literal") {
+			const sKey = `${sourceDeviceId}:${link.source.cap}`;
+			const sList = dependents.get(sKey) ?? [];
+			sList.push({
+				targetDeviceId,
+				targetCap: link.target.cap
+			});
+			dependents.set(sKey, sList);
+		}
 	}
 	return {
 		targets,
@@ -2315,6 +2463,15 @@ var DeviceMetaStore = class {
 		for (const m of Object.values(meta)) if (m.stableId === wanted) return m.id;
 		return null;
 	};
+	/** Resolve a GLOBAL link source (P2e) to a live device id: the device whose
+	*  FULL stableId equals `sourceStableId`, regardless of parent container.
+	*  First match wins (stableIds are effectively unique cluster-wide — see the
+	*  `DeviceLinkGlobalSource` docblock). Null when absent. Pure over a
+	*  pre-read meta map so a multi-link resolve reads the store once. */
+	resolveGlobalSourceDeviceId = (sourceStableId, meta) => {
+		for (const m of Object.values(meta)) if (m.stableId === sourceStableId) return m.id;
+		return null;
+	};
 	allocateNextDeviceId = async () => {
 		const current = (await this.readStore()).nextDeviceId ?? 1;
 		await this.settings.writeAddonStore({ nextDeviceId: current + 1 });
@@ -2345,8 +2502,18 @@ var DeviceMetaStore = class {
 			const container = targetMeta.parentDeviceId !== null ? stableIdById.get(targetMeta.parentDeviceId) ?? stableIdById.get(targetId) : stableIdById.get(targetId);
 			if (container === void 0) continue;
 			for (const link of targetMeta.deviceLinks ?? []) {
-				expectedSources.add(`${container}-${link.source.sourceKey}`);
-				const srcId = idByStableId.get(`${container}-${link.source.sourceKey}`);
+				const src = link.source;
+				if (src.kind === "literal") {
+					entries.push({
+						targetDeviceId: targetId,
+						link,
+						sourceDeviceId: -1
+					});
+					continue;
+				}
+				const wantedStableId = src.kind === "global" ? src.sourceStableId : `${container}-${src.sourceKey}`;
+				expectedSources.add(wantedStableId);
+				const srcId = idByStableId.get(wantedStableId);
 				if (srcId === void 0) continue;
 				entries.push({
 					targetDeviceId: targetId,
@@ -2892,6 +3059,18 @@ async function testField(pctx, input) {
 function isRecord(x) {
 	return x !== null && typeof x === "object" && !Array.isArray(x);
 }
+/**
+* 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.
+*/
+function resolveLinkValue(link, readField) {
+	return applyTransform(link.source.kind === "literal" ? link.source.value : readField(link.source.cap, link.source.fieldPath), link.transform);
+}
 /** Narrow Zod v4's structural `$ZodType` (returned by `.unwrap()`) back to the
 *  concrete classic `z.ZodType`. Every runtime schema is a `z.ZodType`, so this
 *  is a true `instanceof` guard rather than a cast. */
@@ -2923,19 +3102,88 @@ function fillNullableDefaults(schema, value) {
 	return out;
 }
 /**
+* Group item-targeted links (`target.itemKey` set) by itemKey and upsert each
+* group as ONE item into the status' item array (see
+* `CapabilityStatusItemArray`). A NEW item is seeded from `emptyItem` with
+* `keyField` (and `labelField`, when declared) set to the itemKey; an
+* EXISTING item (matched by `keyField`) is cloned and overlaid in place, so
+* native fields a link doesn't touch are preserved. Each upserted item is
+* validated against `itemSchema` — an invalid item is skipped WITHOUT
+* discarding its valid siblings. Returns the new draft and whether anything
+* was applied. Pure + immutable (base array/items are never mutated).
+*/
+function upsertItemArrayLinks(draft, grouped, itemArray) {
+	const arrRaw = getByPath(draft, itemArray.path);
+	const arr = Array.isArray(arrRaw) ? [...arrRaw] : [];
+	let touched = false;
+	for (const [itemKey, group] of grouped) {
+		const idx = arr.findIndex((el) => isRecord(el) && el[itemArray.keyField] === itemKey);
+		const existing = idx >= 0 ? arr[idx] : null;
+		let item = isRecord(existing) ? { ...existing } : {
+			...itemArray.emptyItem,
+			[itemArray.keyField]: itemKey,
+			...itemArray.labelField !== void 0 ? { [itemArray.labelField]: itemKey } : {}
+		};
+		let itemTouched = false;
+		for (const { link, sourceValue } of group) {
+			if (sourceValue === void 0) continue;
+			item = setByPath(item, link.target.fieldPath, sourceValue);
+			itemTouched = true;
+		}
+		if (!itemTouched) continue;
+		const repaired = fillNullableDefaults(itemArray.itemSchema, item);
+		const parsed = itemArray.itemSchema.safeParse(repaired);
+		if (!parsed.success) continue;
+		if (isRecord(parsed.data)) item = parsed.data;
+		if (idx >= 0) arr[idx] = item;
+		else arr.push(item);
+		touched = true;
+	}
+	if (!touched) return {
+		draft,
+		touched: false
+	};
+	return {
+		draft: setByPath(draft, itemArray.path, arr),
+		touched: true
+	};
+}
+/**
 * 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).
 */
-function mergeLinkedStatus(base, resolved, statusSchema) {
+function mergeLinkedStatus(base, resolved, statusSchema, itemArray) {
 	let draft = base;
 	let touched = false;
-	for (const { link, sourceValue } of resolved) {
-		if (sourceValue === void 0) continue;
-		draft = setByPath(draft, link.target.fieldPath, sourceValue);
+	const grouped = /* @__PURE__ */ new Map();
+	for (const entry of resolved) {
+		const itemKey = entry.link.target.itemKey;
+		if (itemKey !== void 0) {
+			if (!itemArray) continue;
+			const group = grouped.get(itemKey);
+			if (group) group.push(entry);
+			else grouped.set(itemKey, [entry]);
+			continue;
+		}
+		if (entry.sourceValue === void 0) continue;
+		draft = setByPath(draft, entry.link.target.fieldPath, entry.sourceValue);
 		touched = true;
 	}
+	if (itemArray && grouped.size > 0) {
+		const upserted = upsertItemArrayLinks(draft, grouped, itemArray);
+		draft = upserted.draft;
+		touched = touched || upserted.touched;
+	}
 	if (!touched) return base;
 	if (!statusSchema) return draft;
 	const repaired = fillNullableDefaults(statusSchema, draft);
@@ -3132,8 +3380,11 @@ var DeviceStateMirror = class DeviceStateMirror {
 	* Read-time overlay of a cap slice with its cross-device linked values.
 	* Returns a cloned raw mirror slice when the (device, cap) pair has no
 	* links. Sources are read from the same in-hub stateMirror — sync, no
-	* cross-process call. The disk writer must NOT use this method; it must
-	* persist raw provider truth via snapshotForDevice.
+	* cross-process call. When the raw slice is ABSENT but the cap is a link
+	* target, the slice is SYNTHESIZED: the merge base is seeded from the
+	* cap's declared `status.empty` default; a failed/empty synthesize
+	* returns null (no phantom slices). The disk writer must NOT use this
+	* method; it must persist raw provider truth via snapshotForDevice.
 	*/
 	overlayedSlice(deviceId, cap) {
 		const raw = this.stateMirror.get(deviceId)?.get(cap) ?? null;
@@ -3141,34 +3392,50 @@ var DeviceStateMirror = class DeviceStateMirror {
 		if (!links || links.length === 0) return raw ? { ...raw } : null;
 		const resolved = links.map((rl) => ({
 			link: rl.link,
-			sourceValue: applyTransform(getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(rl.link.source.cap), rl.link.source.fieldPath), rl.link.transform)
+			sourceValue: resolveLinkValue(rl.link, (srcCap, fieldPath) => getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(srcCap), fieldPath))
 		}));
-		const schema = this.linkHost.capabilityRegistry?.getDefinition(cap)?.status?.schema;
-		return mergeLinkedStatus(raw ? { ...raw } : {}, resolved, schema);
+		const capStatus = this.linkHost.capabilityRegistry?.getDefinition(cap)?.status;
+		const schema = capStatus?.schema;
+		const empty = capStatus?.empty;
+		const base = raw ? { ...raw } : empty !== null && typeof empty === "object" && !Array.isArray(empty) ? { ...empty } : {};
+		const merged = mergeLinkedStatus(base, resolved, schema, capStatus?.itemArray);
+		if (!raw && merged === base) return null;
+		return merged;
 	}
 	/**
 	* Like snapshotForDevice but applies the device-link overlay per cap.
 	* Used exclusively by the device-state READ methods (getSnapshot,
-	* getAllSnapshots) so callers see overlayed values. The debounced disk
-	* writer must continue to call snapshotForDevice (raw truth).
+	* getAllSnapshots) so callers see overlayed values. SYNTHESIZE-only
+	* link-target caps (no base mirror slice) are unioned into the iterated
+	* key set so they appear at warm-load — `overlayedSlice` builds them from
+	* the cap's `status.empty` (and drops them when nothing resolves). The
+	* debounced disk writer must continue to call snapshotForDevice (raw truth).
 	*/
 	snapshotForDeviceOverlayed(deviceId) {
 		const perCap = this.stateMirror.get(deviceId);
-		if (!perCap) return {};
+		const capNames = new Set(perCap ? perCap.keys() : []);
+		const prefix = `${deviceId}:`;
+		for (const key of this.linkHost.linkTargets.keys()) if (key.startsWith(prefix)) capNames.add(key.slice(prefix.length));
 		const out = {};
-		for (const capName of perCap.keys()) {
+		for (const capName of capNames) {
 			const s = this.overlayedSlice(deviceId, capName);
 			if (s) out[capName] = s;
 		}
 		return out;
 	}
-	/** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`. */
+	/** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`.
+	*  Devices that only exist as link TARGETS (no mirror slice yet) are
+	*  included via the link reverse-index so their synthesized caps appear. */
 	allSnapshotsOverlayed() {
+		const deviceIds = new Set(this.stateMirror.keys());
+		for (const key of this.linkHost.linkTargets.keys()) {
+			const id = Number(key.slice(0, key.indexOf(":")));
+			if (Number.isFinite(id)) deviceIds.add(id);
+		}
 		const out = {};
-		for (const [deviceId, perCap] of this.stateMirror) {
-			const dev = {};
-			for (const [capName, slice] of perCap) dev[capName] = this.overlayedSlice(deviceId, capName) ?? { ...slice };
-			out[String(deviceId)] = dev;
+		for (const deviceId of deviceIds) {
+			const dev = this.snapshotForDeviceOverlayed(deviceId);
+			if (this.stateMirror.has(deviceId) || Object.keys(dev).length > 0) out[String(deviceId)] = dev;
 		}
 		return out;
 	}
@@ -3287,14 +3554,27 @@ function resolveNativeCapOwnerSync(pctx, capName, deviceId) {
 * `getProviderForDevice` (routes cross-process); merge is pure.
 */
 async function resolveLinkedStatus(pctx, input) {
-	const { deviceId, cap, baseStatus } = input;
+	const { deviceId, cap } = input;
 	if (!pctx.host.devicesWithLinks.has(deviceId)) return null;
+	const inFlightKey = `${deviceId}:${cap}`;
+	if (pctx.host.linkResolveInFlight.has(inFlightKey)) return null;
+	pctx.host.linkResolveInFlight.add(inFlightKey);
+	try {
+		return await resolveLinkedStatusInner(pctx, input);
+	} finally {
+		pctx.host.linkResolveInFlight.delete(inFlightKey);
+	}
+}
+/** Body of `resolveLinkedStatus` — see the wrapper for the re-entrancy guard. */
+async function resolveLinkedStatusInner(pctx, input) {
+	const { deviceId, cap, baseStatus } = input;
 	const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
 	if (!persisted) return null;
 	const links = (persisted.meta.deviceLinks ?? []).filter((l) => l.target.cap === cap);
 	if (links.length === 0) return null;
 	const capRegistry = pctx.host.capabilityRegistry;
-	const schema = capRegistry?.getDefinition(cap)?.status?.schema;
+	const capStatus = capRegistry?.getDefinition(cap)?.status;
+	const schema = capStatus?.schema;
 	if (!schema) return null;
 	const allMeta = await pctx.metaStore.readMeta();
 	let containerStableId = persisted.stableId;
@@ -3305,11 +3585,19 @@ async function resolveLinkedStatus(pctx, input) {
 	}
 	const resolved = [];
 	for (const link of links) {
-		const srcId = pctx.metaStore.resolveSourceDeviceId(containerStableId, link.source.sourceKey, allMeta);
+		const src = link.source;
+		if (src.kind === "literal") {
+			resolved.push({
+				link,
+				sourceValue: applyTransform(src.value, link.transform)
+			});
+			continue;
+		}
+		const srcId = src.kind === "global" ? pctx.metaStore.resolveGlobalSourceDeviceId(src.sourceStableId, allMeta) : pctx.metaStore.resolveSourceDeviceId(containerStableId, src.sourceKey, allMeta);
 		if (srcId === null) continue;
 		try {
-			const srcProvider = capRegistry?.getProviderForDevice(link.source.cap, srcId);
-			const raw = getByPath(typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0, link.source.fieldPath);
+			const srcProvider = capRegistry?.getProviderForDevice(src.cap, srcId);
+			const raw = getByPath(typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0, src.fieldPath);
 			resolved.push({
 				link,
 				sourceValue: applyTransform(raw, link.transform)
@@ -3321,14 +3609,18 @@ async function resolveLinkedStatus(pctx, input) {
 					capName: cap
 				},
 				meta: {
-					sourceKey: link.source.sourceKey,
+					sourceKey: src.kind === "global" ? src.sourceStableId : src.sourceKey,
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
 		}
 	}
 	if (resolved.length === 0) return null;
-	return mergeLinkedStatus(isRecord$1(baseStatus) ? baseStatus : {}, resolved, schema);
+	const synthesizing = !isRecord$1(baseStatus);
+	const base = isRecord$1(baseStatus) ? baseStatus : isRecord$1(capStatus.empty) ? { ...capStatus.empty } : {};
+	const merged = mergeLinkedStatus(base, resolved, schema, capStatus.itemArray);
+	if (synthesizing && merged === base) return null;
+	return merged;
 }
 //#endregion
 //#region src/builtins/device-manager/device-manager.addon.ts
@@ -3394,10 +3686,15 @@ var DeviceManagerAddon = class extends BaseAddon {
 	linkTargets = /* @__PURE__ */ new Map();
 	/** `${sourceDeviceId}:${sourceCap}` → targets to recompute when that source changes. */
 	linkDependents = /* @__PURE__ */ new Map();
-	/** 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). */
 	expectedSourceStableIds = /* @__PURE__ */ new Set();
+	/** 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. */
+	linkResolveInFlight = /* @__PURE__ */ new Set();
 	/** Test/diagnostic accessors. */
 	linkTargetKeys() {
 		return [...this.linkTargets.keys()];
@@ -3469,6 +3766,7 @@ var DeviceManagerAddon = class extends BaseAddon {
 			get expectedSourceStableIds() {
 				return expectedSourceStableIds();
 			},
+			linkResolveInFlight: this.linkResolveInFlight,
 			dropDeviceOverlays: (deviceId) => this.stateMirror.dropDeviceOverlays(deviceId),
 			remoteNativeCaps: this.remoteNativeCaps,
 			seedMirror: (deviceId, blob) => this.stateMirror.seedMirror(deviceId, blob),
@@ -3517,12 +3815,15 @@ var DeviceManagerAddon = class extends BaseAddon {
 			}
 		}))).filter((id) => id !== null);
 	}
-	/** 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. */
 	get bindingsDeps() {
 		return {
 			ctx: this.ctx,
 			capabilityRegistry: this.capabilityRegistry,
-			remoteNativeCaps: this.remoteNativeCaps
+			remoteNativeCaps: this.remoteNativeCaps,
+			devicesWithLinks: this.devicesWithLinks
 		};
 	}
 	async getBindings(input) {

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

@@ -62,6 +62,12 @@ export declare class DeviceMetaStore {
      *  whose stableId is `${parentStableId}-${sourceKey}`. Null when absent.
      *  Pure over a pre-read meta map so a multi-link resolve reads the store once. */
     resolveSourceDeviceId: (parentStableId: string, sourceKey: string, meta: Record<string, PersistedDeviceMeta>) => number | null;
+    /** Resolve a GLOBAL link source (P2e) to a live device id: the device whose
+     *  FULL stableId equals `sourceStableId`, regardless of parent container.
+     *  First match wins (stableIds are effectively unique cluster-wide — see the
+     *  `DeviceLinkGlobalSource` docblock). Null when absent. Pure over a
+     *  pre-read meta map so a multi-link resolve reads the store once. */
+    resolveGlobalSourceDeviceId: (sourceStableId: string, meta: Record<string, PersistedDeviceMeta>) => number | null;
     allocateNextDeviceId: () => Promise<number>;
     /** Rebuild the `linkTargets` / `linkDependents` reverse-index maps from the
      *  current persisted meta. Called at boot (once the `devicesWithLinks` seed

package/dist/builtins/device-manager/device-provider-context.d.ts

@@ -14,6 +14,10 @@ export interface ProviderHost {
     readonly devicesWithLinks: Set<number>;
     /** Expected link-source stableIds, gating the `registerDevice` rebuild. */
     readonly expectedSourceStableIds: Set<string>;
+    /** In-flight `${deviceId}:${cap}` pairs of `resolveLinkedStatus` — the
+     *  defensive re-entrancy guard that bounds link cycles at resolve time
+     *  (P2e). A nested resolve of a pair already in flight returns null. */
+    readonly linkResolveInFlight: Set<string>;
     /** Drop a removed device's overlay-emit guard entries (state-mirror keyed
      *  `${deviceId}:${cap}`). Called from `removeDevice`. */
     dropDeviceOverlays(deviceId: number): void;

package/dist/builtins/device-manager/device-state-mirror.d.ts

@@ -108,18 +108,26 @@ export declare class DeviceStateMirror {
      * Read-time overlay of a cap slice with its cross-device linked values.
      * Returns a cloned raw mirror slice when the (device, cap) pair has no
      * links. Sources are read from the same in-hub stateMirror — sync, no
-     * cross-process call. The disk writer must NOT use this method; it must
-     * persist raw provider truth via snapshotForDevice.
+     * cross-process call. When the raw slice is ABSENT but the cap is a link
+     * target, the slice is SYNTHESIZED: the merge base is seeded from the
+     * cap's declared `status.empty` default; a failed/empty synthesize
+     * returns null (no phantom slices). The disk writer must NOT use this
+     * method; it must persist raw provider truth via snapshotForDevice.
      */
     overlayedSlice(deviceId: number, cap: string): Record<string, unknown> | null;
     /**
      * Like snapshotForDevice but applies the device-link overlay per cap.
      * Used exclusively by the device-state READ methods (getSnapshot,
-     * getAllSnapshots) so callers see overlayed values. The debounced disk
-     * writer must continue to call snapshotForDevice (raw truth).
+     * getAllSnapshots) so callers see overlayed values. SYNTHESIZE-only
+     * link-target caps (no base mirror slice) are unioned into the iterated
+     * key set so they appear at warm-load — `overlayedSlice` builds them from
+     * the cap's `status.empty` (and drops them when nothing resolves). The
+     * debounced disk writer must continue to call snapshotForDevice (raw truth).
      */
     snapshotForDeviceOverlayed(deviceId: number): Record<string, Record<string, unknown>>;
-    /** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`. */
+    /** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`.
+     *  Devices that only exist as link TARGETS (no mirror slice yet) are
+     *  included via the link reverse-index so their synthesized caps appear. */
     allSnapshotsOverlayed(): Record<string, Record<string, Record<string, unknown>>>;
     private emitStateChanged;
     /** Emit DeviceStateChanged for (deviceId, cap) using the OVERLAID slice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.1.22",
+  "version": "1.1.23",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",