@camstack/system 1.2.313 → 1.2.314

package/dist/builtins/core-blocks/core-blocks.addon.mjs

@@ -1,5 +1,6 @@
-import { K as buildCapabilityLookup, X as composedDeviceRef, at as coreBlockSourceKind, d as CORE_BLOCK_ADDON_PREFIX, et as compositionSourceKey, f as CoreBlockSchema, g as DeclaredDevices, it as coreBlockIdFromAddonId, jn as BaseAddon, kn as errMsg, nt as coreBlockAddonId, ot as coreBlocksCapability, rt as coreBlockComposition, t as ALL_CAPABILITY_DEFINITIONS, tt as compositionSourceRefs, u as CORE_BLOCKS_ADDON_ID, wn as validateComposition } from "../../dist-Cj7pJmXq.mjs";
+import { An as composedDeviceRef, Bn as BaseAddon, Cn as validateComposition, J as buildCapabilityLookup, Pn as compositionSourceKey, an as replacedFieldKeys, at as coreBlocksCapability, d as CORE_BLOCK_ADDON_PREFIX, en as planComposition, et as compositionSourceRefs, f as CoreBlockSchema, g as DeclaredDevices, it as coreBlockSourceKind, l as COMPOSER_RUNNER_ID, nt as coreBlockComposition, rt as coreBlockIdFromAddonId, t as ALL_CAPABILITY_DEFINITIONS, tt as coreBlockAddonId, u as CORE_BLOCKS_ADDON_ID, zn as errMsg } from "../../dist-cH4t1ZEm.mjs";
 import { randomUUID } from "node:crypto";
+import { customizationBlockName } from "@camstack/types/node";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
 //#region src/builtins/core-blocks/block-package.ts
@@ -336,7 +337,7 @@ var BlockSupervisor = class {
 			for (const { block } of compositions) await this.report(block.id, "failed", "no composer is available on this node — a composition cannot run here");
 			return;
 		}
-		if (runners.find((r) => r.name === "composer")?.state === "failed") {
+		if (runners.find((r) => r.name === COMPOSER_RUNNER_ID)?.state === "failed") {
 			for (const { block } of compositions) await this.report(block.id, "failed", "the composer runner's crash circuit-breaker tripped — no composition runs until it is restarted");
 			return;
 		}
@@ -1009,15 +1010,103 @@ function armBlocksIntegration(options) {
 	})() };
 }
 //#endregion
+//#region src/builtins/core-blocks/composition-peers.ts
+/**
+* The stored compositions a save is judged against, as graph peers (D663,
+* ruling S2). Each is identified by its BLOCK ID, targets the device it writes
+* — `composedDeviceRef(block.id)` for a new device, the customized device for an
+* existing one — and, on an existing device, names the fields it REPLACES, so
+* its self-read of a replaced field is the native value and never an edge.
+*
+* `replaced` is not stored anywhere: it is recomputed at save time from the
+* peer's target description (`planComposition(..., target)`), read in the same
+* batch as the candidate's. A peer whose device could not be read has unknown
+* replaced fields: it is OVER-approximated — nothing replaced, every self-read
+* an edge (edges only added, never a cycle hidden) — and its device is listed
+* in `unread`, so the validator refuses a cyclic component only when it holds
+* a candidate node, and names the device (`findCandidateCycles`). An unreadable
+* device never blocks an unrelated save. A peer whose device is GONE is treated
+* the same way (M-1): a stored peer validated earlier may still read it, and
+* assuming every field replaced would remove edges.
+*
+* The candidate's own old version is kept in the list: the graph drops it BY ID
+* (`compositionEdges`), never by target — that is how a second block on
+* the same device reaches `duplicate-target`.
+*/
+function storedCompositions(blocks) {
+	return blocks.flatMap((block) => {
+		const composition = coreBlockComposition(block);
+		return composition === null ? [] : [{
+			blockId: block.id,
+			composition
+		}];
+	});
+}
+/** The existing devices the stored customizations write — each read once with the candidate's. */
+function storedCustomizationTargets(blocks) {
+	return storedCompositions(blocks).flatMap(({ composition }) => composition.target.kind === "existing" ? [composition.target.device] : []);
+}
+/** The fields a stored customization replaces, or why they are unknown. */
+function replacedOf(stored, description, lookupCap) {
+	if (description === void 0) return { error: "it was not read" };
+	if (description.kind === "unreadable") return { error: description.error };
+	if (description.kind === "absent") return { error: "the device does not exist" };
+	return replacedFieldKeys(planComposition(stored.composition, lookupCap, description));
+}
+function peerOf(stored, targets, lookupCap, candidateBlockId) {
+	const { blockId, composition } = stored;
+	if (composition.target.kind === "new") return {
+		peer: {
+			blockId,
+			target: composedDeviceRef(blockId),
+			composition
+		},
+		unread: null
+	};
+	const device = composition.target.device;
+	const key = compositionSourceKey(device);
+	const replaced = replacedOf(stored, targets.get(key), lookupCap);
+	if (!("error" in replaced)) return {
+		peer: {
+			blockId,
+			target: device,
+			composition,
+			replaced
+		},
+		unread: null
+	};
+	return {
+		peer: {
+			blockId,
+			target: device,
+			composition,
+			replaced: /* @__PURE__ */ new Set()
+		},
+		unread: blockId === candidateBlockId ? null : [key, replaced.error]
+	};
+}
+function storedPeers(blocks, targets, lookupCap, candidateBlockId) {
+	const read = storedCompositions(blocks).map((stored) => peerOf(stored, targets, lookupCap, candidateBlockId));
+	return {
+		peers: read.map((r) => r.peer),
+		unread: new Map(read.flatMap((r) => r.unread === null ? [] : [r.unread]))
+	};
+}
+//#endregion
 //#region src/builtins/core-blocks/composition-api.ts
 /**
 * The composition half of the `core-blocks` provider (D659). Flat methods,
 * spread into the provider: no nested sub-object.
 *
-* Every save is VALIDATED against the live sources and every other stored
-* composition first; a refusal names each problem by path and reason (D391)
-* and stores nothing. The store's own refusals (not loaded, unknown block, a
-* code block) propagate unchanged — this layer never swallows them.
+* Every save is VALIDATED against the live sources, its existing target (read
+* once: slim row + `getBindings`) and every stored composition first; a refusal
+* names each problem by path and reason (D391) and stores nothing. The store's
+* own refusals (not loaded, unknown block, a code block) propagate unchanged —
+* this layer never swallows them.
+*
+* A customization of an existing device (D663) has no name of its own: the
+* server derives it (`customizationBlockName`), refuses one the client sends,
+* and never lets it move to another device. One per device, by block id (S2).
 */
 var NOT_LOADED_REASON = "core_blocks has not loaded yet";
 function writeQueue() {
@@ -1044,24 +1133,30 @@ function refuseIfChanged(deps, blockId, expectedUpdatedAt) {
 	} });
 	throw new Error(`core-blocks: the composition "${stored.name}" changed since you read it: stored updatedAt ${stored.updatedAt}, yours ${expectedUpdatedAt} — reload and re-apply your edit`);
 }
+/** The device a composition writes, when it is an EXISTING one; null for a new device. */
+function existingTarget(composition) {
+	return composition.target.kind === "existing" ? composition.target.device : null;
+}
 async function validateAgainstStore(deps, composition, blockId) {
 	if (!deps.store.isLoaded()) throw new Error(`${NOT_LOADED_REASON} — a composition cannot be judged against the stored ones until it has; retry shortly`);
 	const self = blockId === null ? null : composedDeviceRef(blockId);
-	const peers = deps.store.list().flatMap((block) => {
-		const peer = coreBlockComposition(block);
-		return peer === null || block.id === blockId ? [] : [{
-			target: composedDeviceRef(block.id),
-			composition: peer
-		}];
-	});
-	const selfKey = self === null ? null : compositionSourceKey(self);
-	const refs = compositionSourceRefs(composition).filter((r) => compositionSourceKey(r) !== selfKey);
-	const sources = await deps.describeSources(refs);
+	const target = existingTarget(composition);
+	const ownKeys = new Set([self, target].flatMap((ref) => ref === null ? [] : [compositionSourceKey(ref)]));
+	const refs = compositionSourceRefs(composition).filter((r) => !ownKeys.has(compositionSourceKey(r)));
+	const blocks = deps.store.list();
+	const read = await deps.describe(refs, [...target === null ? [] : [target], ...storedCustomizationTargets(blocks)]);
+	const stored = storedPeers(blocks, read.targets, deps.lookupCap, blockId);
 	return validateComposition(composition, {
 		lookupCap: deps.lookupCap,
-		sources,
+		sources: read.sources,
 		self,
-		peers
+		blockId,
+		target: target === null ? null : read.targets.get(compositionSourceKey(target)) ?? {
+			kind: "unreadable",
+			error: "it was not read"
+		},
+		peers: stored.peers,
+		unreadTargets: stored.unread
 	});
 }
 function describeProblems(validation) {
@@ -1096,6 +1191,16 @@ async function readStates(deps, blockIds) {
 		}]));
 	}
 }
+/**
+* One block's composer state. A block the answer leaves out is UNREACHABLE,
+* never folded into "no composition" (D315, M-4).
+*/
+async function readState(deps, blockId) {
+	return (await readStates(deps, [blockId])).get(blockId) ?? {
+		kind: "unreachable",
+		error: "the composer state read returned no entry for the block"
+	};
+}
 function toViews(blocks, states) {
 	return blocks.flatMap((block) => {
 		const state = states.get(block.id);
@@ -1105,6 +1210,98 @@ function toViews(blocks, states) {
 		}];
 	});
 }
+var NO_NAME_OF_ITS_OWN = "a customization has no name of its own — the device's name is shown; omit `name`";
+var NEW_DEVICE_NEEDS_NAME = "a new device needs a name";
+var DEVICE_IS_FIXED = "a customization's device cannot be changed — delete it and customize the other device";
+var NEVER_BECOMES_CUSTOMIZATION = "a composed device cannot become the customization of another device — create the customization instead";
+/**
+* The numeric id of a save's existing target, for the refusal line's tag
+* (D391: a line about a device carries `tags.deviceId`). Read only on a
+* refusal — one listing — and a failed read names itself on the line instead.
+*/
+async function resolveTarget(deps, target) {
+	try {
+		const found = (await deps.describe([], [target])).targets.get(compositionSourceKey(target));
+		if (found?.kind === "found") return {
+			kind: "device",
+			deviceId: found.deviceId
+		};
+		return {
+			kind: "unresolved",
+			why: found?.kind ?? "not described"
+		};
+	} catch (err) {
+		return {
+			kind: "unresolved",
+			why: errMsg(err)
+		};
+	}
+}
+/** A save refused before validation, by name (D391): logged, then thrown. */
+async function refuseSave(deps, subject, target, reason) {
+	const resolved = target === null ? null : await resolveTarget(deps, target);
+	deps.logger.warn("composition save refused", {
+		...resolved?.kind === "device" ? { tags: { deviceId: resolved.deviceId } } : {},
+		meta: {
+			name: subject.name,
+			blockId: subject.blockId,
+			target: target === null ? null : compositionSourceKey(target),
+			...resolved?.kind === "unresolved" ? { targetUnresolved: resolved.why } : {},
+			reason
+		}
+	});
+	throw new Error(`core-blocks: the composition "${subject.name}" was refused — ${reason}`);
+}
+/**
+* The name a new block is stored under (rule 1): a new device's own, required;
+* a customization's DERIVED from its device (ruling S2), never the client's.
+*/
+async function nameOnCreate(deps, block) {
+	const target = existingTarget(block.composition);
+	if (target === null) {
+		if (block.name === void 0) return refuseSave(deps, {
+			name: "(unnamed)",
+			blockId: null
+		}, null, NEW_DEVICE_NEEDS_NAME);
+		return block.name;
+	}
+	if (block.name !== void 0) return refuseSave(deps, {
+		name: block.name,
+		blockId: null
+	}, target, NO_NAME_OF_ITS_OWN);
+	return customizationBlockName(target);
+}
+/**
+* A customization is pinned to its device and carries no client name (rule 2);
+* a composed device never turns into one — its name would be the client's. An
+* unknown or code block falls through to the store, whose refusal names it.
+*/
+async function refuseRetarget(deps, blockId, patch) {
+	const stored = deps.store.get(blockId);
+	const current = stored === null ? null : coreBlockComposition(stored);
+	if (stored === null || current === null) return;
+	const subject = {
+		name: stored.name,
+		blockId
+	};
+	const pinned = existingTarget(current);
+	const next = patch.composition === void 0 ? pinned : existingTarget(patch.composition);
+	if (pinned === null) {
+		if (next !== null) return refuseSave(deps, subject, next, NEVER_BECOMES_CUSTOMIZATION);
+		return;
+	}
+	if (patch.name !== void 0) return refuseSave(deps, subject, pinned, NO_NAME_OF_ITS_OWN);
+	if (next === null || compositionSourceKey(next) !== compositionSourceKey(pinned)) return refuseSave(deps, subject, pinned, DEVICE_IS_FIXED);
+}
+/** The block customizing `device`, found by TARGET — never by its derived name (rule 4). */
+function customizationOf(blocks, device) {
+	const key = compositionSourceKey(device);
+	return blocks.find((block) => {
+		const composition = coreBlockComposition(block);
+		const target = composition === null ? null : existingTarget(composition);
+		return target !== null && compositionSourceKey(target) === key;
+	}) ?? null;
+}
 /**
 * Every write runs validate-then-persist on ONE chain. Validation awaits a
 * source read before the save lands; two unserialized saves (A reads B, B
@@ -1115,12 +1312,16 @@ function buildCompositionApi(deps) {
 	const serialized = writeQueue();
 	return {
 		createComposition: ({ block, caller }) => serialized(async () => {
+			const name = await nameOnCreate(deps, block);
 			const validation = await validateAgainstStore(deps, block.composition, null);
 			if (!validation.ok) refuse(deps, {
-				name: block.name,
+				name,
 				blockId: null
 			}, validation);
-			const created = await deps.store.createComposition(block, caller.userId);
+			const created = await deps.store.createComposition({
+				...block,
+				name
+			}, caller.userId);
 			deps.logger.info("composition created", { meta: {
 				blockId: created.id,
 				name: created.name,
@@ -1131,6 +1332,7 @@ function buildCompositionApi(deps) {
 		}),
 		updateComposition: ({ blockId, expectedUpdatedAt, block, caller }) => serialized(async () => {
 			refuseIfChanged(deps, blockId, expectedUpdatedAt);
+			await refuseRetarget(deps, blockId, block);
 			if (block.composition !== void 0) {
 				const validation = await validateAgainstStore(deps, block.composition, blockId);
 				if (!validation.ok) refuse(deps, {
@@ -1156,10 +1358,12 @@ function buildCompositionApi(deps) {
 				state: "loaded",
 				view: null
 			};
-			const [view] = toViews([block], await readStates(deps, [blockId]));
 			return {
 				state: "loaded",
-				view: view ?? null
+				view: {
+					block,
+					state: await readState(deps, blockId)
+				}
 			};
 		},
 		listCompositions: async () => {
@@ -1177,18 +1381,45 @@ function buildCompositionApi(deps) {
 				views: toViews(blocks, await readStates(deps, blocks.map((b) => b.id)))
 			};
 		},
+		getCustomization: async ({ addonId, stableId }) => {
+			if (!deps.store.isLoaded()) return {
+				state: "not-loaded",
+				reason: NOT_LOADED_REASON
+			};
+			const block = customizationOf(deps.store.list(), {
+				addonId,
+				stableId
+			});
+			if (block === null) return {
+				state: "loaded",
+				view: null
+			};
+			return {
+				state: "loaded",
+				view: {
+					block,
+					state: await readState(deps, block.id)
+				}
+			};
+		},
 		validateComposition: async ({ composition, blockId }) => validateAgainstStore(deps, composition, blockId ?? null)
 	};
 }
 //#endregion
 //#region src/builtins/core-blocks/composition-sources.ts
 /**
-* Describe a composition's sources for SAVE-time validation (D659): one
-* `listAll` per owning addon, one `getBindings` per found device. A read that
-* fails makes the source `unreadable`, and the save is REFUSED rather than
+* Describe what a composition reads and writes for SAVE-time validation
+* (D659, D663): one `listAll` per owning addon, one `getBindings` per found
+* device — shared by a device that is both a source and a target. A read that
+* fails makes the device `unreadable`, and the save is REFUSED rather than
 * stored unchecked. Refusing a save destroys nothing (D49).
 *
-* Sources are keyed by `{addonId, stableId}` — never a numeric device id,
+* A SOURCE is described by the caps bound to it; an EXISTING TARGET by its row
+* type and each bound cap with the addon serving it — what `planComposition`
+* needs to tell a replace from an add (the composer reads it the same way, from
+* the same two reads: the slim row and `getBindings`).
+*
+* Devices are keyed by `{addonId, stableId}` — never a numeric device id,
 * which is this node's allocation and not the composition's identity.
 */
 async function listOwners(ports, refs) {
@@ -1202,7 +1433,7 @@ async function listOwners(ports, refs) {
 	}));
 	return new Map(listed);
 }
-async function describeOne(ports, ref, listing) {
+function rowOf(ref, listing) {
 	if (listing === void 0) return {
 		kind: "unreadable",
 		error: `\`${ref.addonId}\` was not listed`
@@ -1212,24 +1443,68 @@ async function describeOne(ports, ref, listing) {
 		error: listing.error
 	};
 	const row = listing.find((r) => r.stableId === ref.stableId);
-	if (row === void 0) return { kind: "absent" };
-	try {
-		return {
-			kind: "found",
-			deviceId: row.id,
-			caps: new Set(await ports.boundCaps(row.id))
-		};
-	} catch (err) {
-		return {
-			kind: "unreadable",
-			error: errMsg(err)
-		};
-	}
+	return row === void 0 ? { kind: "absent" } : {
+		kind: "row",
+		row
+	};
+}
+/** ONE `getBindings` per found device, whether it is read as a source, a target, or both. */
+async function readBindings(ports, deviceIds) {
+	const read = await Promise.all([...new Set(deviceIds)].map(async (deviceId) => {
+		try {
+			return [deviceId, await ports.bindings(deviceId)];
+		} catch (err) {
+			return [deviceId, { error: errMsg(err) }];
+		}
+	}));
+	return new Map(read);
+}
+function describeSource(lookup, bindings) {
+	if (lookup.kind !== "row") return lookup;
+	const bound = bindings.get(lookup.row.id);
+	if (bound === void 0) return {
+		kind: "unreadable",
+		error: "its bindings were not read"
+	};
+	if ("error" in bound) return {
+		kind: "unreadable",
+		error: bound.error
+	};
+	return {
+		kind: "found",
+		deviceId: lookup.row.id,
+		caps: new Set(bound.map((b) => b.capName))
+	};
 }
-async function describeCompositionSources(ports, refs) {
-	const owners = await listOwners(ports, refs);
-	const described = await Promise.all(refs.map(async (ref) => [compositionSourceKey(ref), await describeOne(ports, ref, owners.get(ref.addonId))]));
-	return new Map(described);
+function describeTarget(lookup, bindings) {
+	if (lookup.kind !== "row") return lookup;
+	const { id, type } = lookup.row;
+	const bound = bindings.get(id);
+	if (bound === void 0) return {
+		kind: "unreadable",
+		error: "its bindings were not read"
+	};
+	if ("error" in bound) return {
+		kind: "unreadable",
+		error: bound.error
+	};
+	return {
+		kind: "found",
+		deviceId: id,
+		type,
+		nativeCaps: new Map(bound.map((b) => [b.capName, b.nativeAddonId]))
+	};
+}
+async function describeCompositionSources(ports, sources, targets = []) {
+	const owners = await listOwners(ports, [...sources, ...targets]);
+	const lookup = (ref) => [compositionSourceKey(ref), rowOf(ref, owners.get(ref.addonId))];
+	const sourceRows = sources.map(lookup);
+	const targetRows = targets.map(lookup);
+	const bindings = await readBindings(ports, [...sourceRows, ...targetRows].flatMap(([, l]) => l.kind === "row" ? [l.row.id] : []));
+	return {
+		sources: new Map(sourceRows.map(([key, l]) => [key, describeSource(l, bindings)])),
+		targets: new Map(targetRows.map(([key, l]) => [key, describeTarget(l, bindings)]))
+	};
 }
 //#endregion
 //#region src/builtins/core-blocks/core-blocks.addon.ts
@@ -1503,9 +1778,10 @@ var CoreBlocksAddon = class extends BaseAddon {
 		};
 	}
 	/**
-	* The composition methods (D659), flat. Sources are read over `ctx.api` at
-	* SAVE time — one listing per owning addon, one binding read per found
-	* device — and a read that fails refuses the save rather than skipping it.
+	* The composition methods (D659), flat. Sources and existing targets are read
+	* over `ctx.api` at SAVE time — one slim listing per owning addon, one binding
+	* read per found device — and a read that fails refuses the save rather than
+	* skipping it.
 	*/
 	buildCompositionApi() {
 		const requireApi = () => {
@@ -1515,13 +1791,13 @@ var CoreBlocksAddon = class extends BaseAddon {
 		};
 		return buildCompositionApi({
 			store: this.requireStore(),
-			describeSources: (refs) => describeCompositionSources({
+			describe: (sources, targets) => describeCompositionSources({
 				listByAddon: async (addonId) => requireApi().deviceManager.listAll.query({
 					addonId,
 					projection: "slim"
 				}),
-				boundCaps: async (deviceId) => (await requireApi().deviceManager.getBindings.query({ deviceId })).entries.map((e) => e.capName)
-			}, refs),
+				bindings: async (deviceId) => (await requireApi().deviceManager.getBindings.query({ deviceId })).entries
+			}, sources, targets),
 			lookupCap: buildCapabilityLookup(ALL_CAPABILITY_DEFINITIONS),
 			composerStates: async (blockIds) => (await requireApi().composer.getStates.query({ blockIds: [...blockIds] })).states,
 			convergeSoon: () => this.convergeSoon(),

package/dist/builtins/device-manager/claimed-status-overlay.d.ts

@@ -0,0 +1,12 @@
+import { ICapabilityRegistry, IScopedLogger } from '@camstack/types';
+import { DeviceManagerSettings } from './device-meta-store.js';
+import { ClaimsIndexView, DeviceStateMirror } from './device-state-mirror.js';
+export interface ClaimedStatusOverlayDeps {
+    readonly mirror: DeviceStateMirror;
+    /** The claims index as it is NOW — loaded or not; read at every question, never captured. */
+    readonly claimsIndex: () => ClaimsIndexView;
+    /** The settings door the mirror reads a device's row through. */
+    readonly settings: () => DeviceManagerSettings;
+    readonly logger: IScopedLogger;
+}
+export declare function installClaimedStatusOverlay(registry: ICapabilityRegistry, deps: ClaimedStatusOverlayDeps): () => void;

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

@@ -30,6 +30,13 @@ export declare class DeviceManagerAddon extends BaseAddon {
      * `ctx`); `null` before initialise / when `ctx.settings` is absent.
      */
     private stateMirrorImpl;
+    /**
+     * Removes the claimed-status overlay this addon installed on the capability
+     * registry (D663, S3): `getStatus` of a claimed cap answers the mirror for
+     * every caller while it is installed. Run in `onShutdown`; `null` before
+     * init or when the kernel handed the addon no registry.
+     */
+    private uninstallStatusOverlay;
     /**
      * Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
      * Kept in sync with `DeviceBindingsChanged` push events emitted by forked
@@ -64,6 +71,15 @@ export declare class DeviceManagerAddon extends BaseAddon {
     private readonly removalFence;
     /** The runtime-state mirror, asserted present (constructed in onInitialize). */
     private get stateMirror();
+    /**
+     * The per-field claims index (D663): which devices carry a claim, for the
+     * seed and for `listClaims`. Constructed at init and loaded before the first
+     * provider method can run; a load that fails leaves it `not-loaded`, and
+     * every seed reads its row until a later call loads it.
+     */
+    private fieldClaimsImpl;
+    /** The claims index, asserted present (constructed in onInitialize). */
+    private get fieldClaims();
     /** Build the `ProviderHost` the extracted provider-method modules
      *  (`device-meta-actions`, `device-queries`) reach — exposes the addon's
      *  private state/methods they need without leaking the class internals.