@camstack/system 1.2.307 → 1.2.309

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

@@ -1,4 +1,4 @@
-import { J as coreBlockIdFromAddonId, Y as coreBlocksCapability, c as CORE_BLOCKS_ADDON_ID, gn as BaseAddon, l as CORE_BLOCK_ADDON_PREFIX, m as DeclaredDevices, mn as errMsg, q as coreBlockAddonId, u as CoreBlockSchema } from "../../dist-DdfJa8Zn.mjs";
+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-BEuQPDk_.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
@@ -152,6 +152,27 @@ async function removeBlockPackage(root, blockId) {
 }
 //#endregion
 //#region src/builtins/core-blocks/block-supervisor.ts
+/**
+* Converging the running block processes onto the stored blocks.
+*
+* Reconcile against the registry, not one-shot reactions to events: a spawn
+* that was missed because an event was dropped (D8 — events are telemetry) has
+* to be fixed by the next pass, and an operator restarting the hub must end up
+* with exactly the blocks the store says are enabled. So `converge()` is
+* idempotent and safe to call from a timer, from a write, and from boot.
+*
+* **The supervision itself is not in this file, and that is deliberate.** A
+* block that never returns is bounded by `process-service`'s `CrashSupervisor`
+* (D6) — the same circuit-breaker that bounds every addon. This class only
+* decides which runners should exist and translates their state back into
+* something the author can read. Re-implementing backoff here would be a second
+* supervisor to keep in step with the first.
+*
+* The invariant it exists to hold: **a block that is not running says why.**
+* Every path out of `converge()` that does not end in a live process writes a
+* status the operator can see, with the reason attached. A block that is
+* silently absent is the failure mode this whole feature has to avoid.
+*/
 /** Runner state → what the author should read. `crashed` is the window between
 *  an exit and the scheduled respawn, so it reads as `starting` with the reason
 *  attached rather than as a terminal failure it is not. */
@@ -176,6 +197,16 @@ var BlockSupervisor = class {
 	/** Serialises passes so a timer tick cannot interleave with a write-driven
 	*  converge and spawn the same runner twice. */
 	inFlight = Promise.resolve();
+	/** Composition restarts not yet delivered to the composer. Stores nothing durable (D62). */
+	pendingCompositionRestarts = /* @__PURE__ */ new Set();
+	/**
+	* Empty applies still owed: the composer withdraws only after TWO agree
+	* (D49), and a boot sends one. Only an apply the composer says it ACTED on
+	* (`result.acted`) pays one off — it can refuse with the store loaded.
+	*/
+	emptyAppliesOwed = 2;
+	/** Consecutive applies that could not reach the composer: warned once per run. */
+	failedApplies = 0;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -212,6 +243,11 @@ var BlockSupervisor = class {
 	* then never re-launch it.
 	*/
 	restart(blockId) {
+		const block = this.deps.store.get(blockId);
+		if (block !== null && coreBlockSourceKind(block) === "composition") {
+			this.pendingCompositionRestarts = new Set([...this.pendingCompositionRestarts, blockId]);
+			return this.converge();
+		}
 		this.inFlight = this.inFlight.then(() => this.runRestart(blockId), () => this.runRestart(blockId));
 		return this.inFlight;
 	}
@@ -236,9 +272,11 @@ var BlockSupervisor = class {
 		}
 	}
 	async reconcile() {
+		if (!this.deps.storeLoaded()) await this.deps.loadStore();
 		const blocks = this.deps.store.list();
-		const mine = blocks.filter((b) => b.enabled && this.isPlacedHere(b));
-		const runners = new Map((await this.deps.host.list()).map((r) => [blockIdFromAddonId(r.name), r]).filter((pair) => pair[0] !== null));
+		const mine = blocks.filter((b) => b.enabled && this.isPlacedHere(b) && coreBlockSourceKind(b) === "code");
+		const snapshots = await this.deps.host.list();
+		const runners = new Map(snapshots.map((r) => [blockIdFromAddonId(r.name), r]).filter((pair) => pair[0] !== null));
 		for (const block of blocks) {
 			if (!block.enabled || this.isPlacedHere(block)) continue;
 			await this.report(block.id, "failed", `no core-block supervisor runs on "${block.placement}" — this block is not running anywhere. Move it to "${this.deps.nodeId}" to run it.`);
@@ -256,6 +294,7 @@ var BlockSupervisor = class {
 			if (this.deps.store.get(blockId) !== null) await this.report(blockId, "stopped");
 			else await removeBlockPackage(this.deps.root, blockId);
 		}
+		for (const block of blocks) if (block.enabled && coreBlockSourceKind(block) === "recipe") await this.report(block.id, "failed", "a recipe block cannot run yet — recipes are stored, not executed, in this release");
 		for (const block of mine) {
 			const runner = runners.get(block.id);
 			const stale = runner !== void 0 && this.materialized.get(block.id) !== block.updatedAt;
@@ -273,6 +312,71 @@ var BlockSupervisor = class {
 			}
 			await this.launch(block);
 		}
+		await this.convergeCompositions(blocks, snapshots);
+	}
+	/**
+	* Send every composition placed here to the composer and mirror its verdicts
+	* into the block status, reason verbatim. A `starting` verdict (the composer
+	* does not trust its store or seed yet) is mirrored as `starting`; the next
+	* pass of this same converge is the retry — no timer of its own (D3).
+	*/
+	async convergeCompositions(blocks, runners) {
+		const compositions = blocks.flatMap((block) => {
+			const composition = coreBlockComposition(block);
+			return composition !== null && this.isPlacedHere(block) ? [{
+				block,
+				composition
+			}] : [];
+		});
+		const unreadable = this.deps.store.unreadableCompositions();
+		const nothingToSay = compositions.length === 0 && unreadable.length === 0;
+		if (nothingToSay && this.emptyAppliesOwed === 0) return;
+		const composer = this.deps.composer;
+		if (composer === null) {
+			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") {
+			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;
+		}
+		const restart = this.pendingCompositionRestarts;
+		const integrationId = this.deps.integrationId();
+		const storeLoaded = this.deps.storeLoaded();
+		try {
+			const result = await composer.apply({
+				integrationId,
+				storeLoaded,
+				blocks: compositions.map(({ block, composition }) => ({
+					id: block.id,
+					name: block.name,
+					enabled: block.enabled,
+					updatedAt: block.updatedAt,
+					composition
+				})),
+				restartBlockIds: [...restart],
+				unreadableBlocks: [...unreadable]
+			});
+			if (this.failedApplies > 0) {
+				this.deps.logger.info("the composer answered again", { meta: { failedApplies: this.failedApplies } });
+				this.failedApplies = 0;
+			}
+			this.pendingCompositionRestarts = new Set([...this.pendingCompositionRestarts].filter((id) => !restart.has(id)));
+			this.emptyAppliesOwed = !nothingToSay || !result.acted ? 2 : Math.max(0, this.emptyAppliesOwed - 1);
+			const verdicts = new Map(result.blocks.map((v) => [v.blockId, v]));
+			for (const { block } of compositions) {
+				const verdict = verdicts.get(block.id);
+				if (verdict === void 0) await this.report(block.id, "starting", "the composer did not answer for this block");
+				else await this.report(block.id, verdict.status, verdict.reason);
+			}
+		} catch (err) {
+			this.failedApplies += 1;
+			if (this.failedApplies === 1) this.deps.logger.warn("the composer could not be reached — compositions keep their last status", { meta: {
+				error: errMsg(err),
+				compositions: compositions.length
+			} });
+			for (const { block } of compositions) if (block.status === "stopped" && block.enabled) await this.report(block.id, "starting", `the composer is not reachable yet: ${errMsg(err)}`);
+		}
 	}
 	/** Compile, write the package, spawn. Each failure is reported ON the block
 	*  — the author asked for this to run, so they are owed the reason it does
@@ -543,12 +647,42 @@ var CORE_BLOCKS_INDEXES = [{
 	name: "idx_core_blocks_enabled",
 	columns: ["enabled"]
 }];
+/**
+* Rows one read asks for. A read that ANSWERS this many is not a loaded table:
+* rows past the limit would be absent, and an absent composition reads as a
+* deleted one (D49).
+*/
+var CORE_BLOCKS_LOAD_LIMIT = 1e3;
+/**
+* What an unparseable row's `source.kind` says, or null when it cannot be told.
+* Absent means `code`, as it does for a readable row.
+*/
+function rawSourceKind(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	if (!("source" in raw) || raw.source === void 0) return "code";
+	const source = raw.source;
+	if (typeof source !== "object" || source === null || !("kind" in source)) return null;
+	return typeof source.kind === "string" ? source.kind : null;
+}
+/** An unreadable row that may be a composition: one whose kind says so, or cannot be told. */
+function mayBeComposition(raw) {
+	const kind = rawSourceKind(raw);
+	return kind !== "code" && kind !== "recipe";
+}
+function parseErrorText(issues) {
+	return issues.map((i) => `${i.path.map(String).join(".")}: ${i.message}`).join("; ");
+}
 var CoreBlockStore = class {
 	byId = /* @__PURE__ */ new Map();
+	/** Rows that exist but do not parse and may be compositions — held for the composer, never dropped (D49). */
+	unreadable = [];
 	store;
 	logger;
 	now;
 	newId;
+	loaded = false;
+	/** Consecutive failed reads — the warn is once per run of them, not once per retry. */
+	failedLoads = 0;
 	constructor(deps) {
 		this.store = deps.store;
 		this.logger = deps.logger;
@@ -562,32 +696,70 @@ var CoreBlockStore = class {
 			indexes: [...CORE_BLOCKS_INDEXES]
 		});
 	}
+	/** True only after a `load()` that READ the table. The composer withdraws nothing otherwise (D49). */
+	isLoaded() {
+		return this.loaded;
+	}
+	/** Stored composition rows that do not parse, by id — the composer holds their devices. */
+	unreadableCompositions() {
+		return this.unreadable;
+	}
 	/**
 	* Hydrate every block.
 	*
 	* A row whose JSON no longer validates is SKIPPED with a warning rather than
 	* dropped or repaired: it is somebody's code, and the honest answer to "I
-	* cannot read this" is to leave it on disk and say so.
+	* cannot read this" is to leave it on disk and say so. A skipped row that may
+	* be a COMPOSITION is also kept in `unreadableCompositions()`: absent from the
+	* composer's input it would read as deleted, and its device would go (D49).
+	*
+	* `source` is parsed here, and a build older than D659 strips `source` and
+	* rewrites the row — rolling back below D659 erases compositions.
 	*/
 	async load() {
 		try {
 			const rows = await this.store.query.query({
 				collection: CORE_BLOCKS_COLLECTION,
-				filter: { limit: 1e3 }
+				filter: { limit: CORE_BLOCKS_LOAD_LIMIT }
 			});
+			if (rows.length >= 1e3) throw new Error(`core_blocks answered ${rows.length} rows, the read limit — rows past it would read as deleted`);
 			this.byId.clear();
+			this.loaded = true;
+			if (this.failedLoads > 0) {
+				this.logger.info("core blocks loaded after failed reads", { meta: { failedAttempts: this.failedLoads } });
+				this.failedLoads = 0;
+			}
 			let skipped = 0;
+			const unreadable = [];
 			for (const row of rows) {
-				const parsed = CoreBlockSchema.safeParse(row.data["block"]);
+				const raw = row.data["block"];
+				const parsed = CoreBlockSchema.safeParse(raw);
 				if (!parsed.success) {
 					skipped += 1;
+					if (mayBeComposition(raw)) {
+						const name = row.data["name"];
+						unreadable.push({
+							id: row.id,
+							name: typeof name === "string" ? name : null,
+							error: parseErrorText(parsed.error.issues)
+						});
+					}
 					continue;
 				}
 				this.byId.set(parsed.data.id, parsed.data);
 			}
-			if (skipped > 0) this.logger.warn("core blocks skipped as unreadable — left on disk, not repaired", { meta: { skipped } });
+			this.unreadable = unreadable;
+			if (skipped > 0) this.logger.warn("core blocks skipped as unreadable — left on disk, not repaired", { meta: {
+				skipped,
+				heldForComposer: unreadable.map((u) => u.id)
+			} });
 		} catch (err) {
-			this.logger.warn("core block load failed", { meta: { error: String(err) } });
+			this.failedLoads += 1;
+			if (this.failedLoads === 1) this.logger.warn("core block load failed — retried on every converge until it reads", { meta: { error: String(err) } });
+			else this.logger.debug("core block load failed again", { meta: {
+				error: String(err),
+				failedAttempts: this.failedLoads
+			} });
 		}
 	}
 	list() {
@@ -601,6 +773,7 @@ var CoreBlockStore = class {
 		return this.list().filter((b) => b.enabled && b.placement === nodeId);
 	}
 	async create(input, createdBy) {
+		this.requireLoaded();
 		const now = this.now();
 		const block = CoreBlockSchema.parse({
 			...input,
@@ -619,13 +792,61 @@ var CoreBlockStore = class {
 	async update(blockId, patch) {
 		const existing = this.byId.get(blockId);
 		if (!existing) throw new Error(`core block not found: ${blockId}`);
+		if ((patch.code !== void 0 && patch.code !== existing.code || patch.placement !== void 0 && patch.placement !== existing.placement || patch.integrationId !== void 0 && patch.integrationId !== existing.integrationId) && coreBlockSourceKind(existing) !== "code") throw new Error(`core block "${existing.name}" is a composition — its code, placement and integration are fixed; edit it with updateComposition`);
+		if (patch.name !== void 0 && patch.name !== existing.name && coreBlockSourceKind(existing) !== "code") throw new Error(`core block "${existing.name}" is a composition — rename it with updateComposition, which checks expectedUpdatedAt`);
 		const updated = CoreBlockSchema.parse({
 			...existing,
 			...patch,
 			id: existing.id,
 			createdBy: existing.createdBy,
 			createdAt: existing.createdAt,
-			updatedAt: this.now()
+			updatedAt: Math.max(this.now(), existing.updatedAt + 1)
+		});
+		await this.persist(updated);
+		this.byId.set(updated.id, updated);
+		return updated;
+	}
+	/**
+	* Store a composition block (D659): hub-placed, no code, never `running` on
+	* creation — the composer's verdict, mirrored by the supervisor, says that.
+	*/
+	async createComposition(input, createdBy) {
+		this.requireLoaded();
+		const now = this.now();
+		const block = CoreBlockSchema.parse({
+			name: input.name,
+			enabled: input.enabled,
+			placement: "hub",
+			code: "",
+			source: {
+				kind: "composition",
+				composition: input.composition
+			},
+			id: this.newId(),
+			createdBy,
+			createdAt: now,
+			updatedAt: now,
+			status: "stopped",
+			lastChangedAt: now
+		});
+		await this.persist(block);
+		this.byId.set(block.id, block);
+		return block;
+	}
+	/** Patch a composition block. Immutable: returns the NEW block. Refuses a code block by name. */
+	async updateComposition(blockId, patch) {
+		const existing = this.byId.get(blockId);
+		if (!existing) throw new Error(`core block not found: ${blockId}`);
+		if (coreBlockSourceKind(existing) !== "composition") throw new Error(`core block "${existing.name}" is a code block — edit it with update`);
+		const updated = CoreBlockSchema.parse({
+			...existing,
+			...patch.name === void 0 ? {} : { name: patch.name },
+			...patch.enabled === void 0 ? {} : { enabled: patch.enabled },
+			...patch.composition === void 0 ? {} : { source: {
+				kind: "composition",
+				composition: patch.composition
+			} },
+			updatedAt: Math.max(this.now(), existing.updatedAt + 1)
 		});
 		await this.persist(updated);
 		this.byId.set(updated.id, updated);
@@ -651,9 +872,17 @@ var CoreBlockStore = class {
 		await this.persist(next);
 		this.byId.set(blockId, next);
 	}
+	/**
+	* A write before the table has been read would be wiped from memory by the
+	* load that follows (it clears and refills), so it is refused by name.
+	*/
+	requireLoaded() {
+		if (!this.loaded) throw new Error("core_blocks has not loaded yet — nothing can be created until it has; retry shortly");
+	}
 	/** Idempotent delete — an unknown id is a no-op. */
 	async delete(blockId) {
 		this.byId.delete(blockId);
+		this.unreadable = this.unreadable.filter((u) => u.id !== blockId);
 		await this.store.delete.mutate({
 			collection: CORE_BLOCKS_COLLECTION,
 			key: blockId
@@ -718,6 +947,11 @@ var BLOCKS_INTEGRATION_NAME = "Blocks";
 * with every device on the cluster, and the sweep would delete the blocks'), or
 * make `core-blocks` declare a device of its own. Neither is worth the
 * convenience; the spec test pins both.
+*
+* A SECOND owner hangs devices here since D659: `composer` (every composed
+* device). It is equally safe for the same reason — its rows are owned by
+* `composer`, never by `core-blocks`, and its own withdrawal sweep is scoped to
+* `composer`.
 */
 async function reconcileBlocksIntegration(ports) {
 	return (await new DeclaredDevices({
@@ -775,6 +1009,229 @@ function armBlocksIntegration(options) {
 	})() };
 }
 //#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.
+*/
+var NOT_LOADED_REASON = "core_blocks has not loaded yet";
+function writeQueue() {
+	let tail = Promise.resolve();
+	return (write) => {
+		const run = tail.then(write, write);
+		tail = run.then(() => void 0, () => void 0);
+		return run;
+	};
+}
+/**
+* Optimistic concurrency: an update names the `updatedAt` it read. A block
+* changed since is refused by name — last-write-wins would drop the other
+* admin's edit without a word. An unknown block falls through to the store,
+* whose own refusal names it.
+*/
+function refuseIfChanged(deps, blockId, expectedUpdatedAt) {
+	const stored = deps.store.get(blockId);
+	if (stored === null || stored.updatedAt === expectedUpdatedAt) return;
+	deps.logger.warn("composition update refused: changed since read", { meta: {
+		blockId,
+		storedUpdatedAt: stored.updatedAt,
+		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`);
+}
+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);
+	return validateComposition(composition, {
+		lookupCap: deps.lookupCap,
+		sources,
+		self,
+		peers
+	});
+}
+function describeProblems(validation) {
+	return validation.problems.map((p) => `${p.path} [${p.code}]: ${p.message}`);
+}
+function refuse(deps, subject, validation) {
+	const problems = describeProblems(validation);
+	deps.logger.warn("composition save refused", { meta: {
+		name: subject.name,
+		blockId: subject.blockId,
+		problems
+	} });
+	throw new Error(`core-blocks: the composition "${subject.name}" was refused — ${problems.join("; ")}`);
+}
+async function readStates(deps, blockIds) {
+	try {
+		const states = await deps.composerStates(blockIds);
+		const byId = new Map(states.map((s) => [s.blockId, s]));
+		return new Map(blockIds.map((id) => [id, {
+			kind: "answered",
+			state: byId.get(id) ?? null
+		}]));
+	} catch (err) {
+		const error = errMsg(err);
+		deps.logger.warn("composer state unreachable", { meta: {
+			blocks: blockIds.length,
+			error
+		} });
+		return new Map(blockIds.map((id) => [id, {
+			kind: "unreachable",
+			error
+		}]));
+	}
+}
+function toViews(blocks, states) {
+	return blocks.flatMap((block) => {
+		const state = states.get(block.id);
+		return state === void 0 ? [] : [{
+			block,
+			state
+		}];
+	});
+}
+/**
+* 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
+* reads A) would each be judged against a store without the other and BOTH
+* pass — a stored cycle nothing downstream catches.
+*/
+function buildCompositionApi(deps) {
+	const serialized = writeQueue();
+	return {
+		createComposition: ({ block, caller }) => serialized(async () => {
+			const validation = await validateAgainstStore(deps, block.composition, null);
+			if (!validation.ok) refuse(deps, {
+				name: block.name,
+				blockId: null
+			}, validation);
+			const created = await deps.store.createComposition(block, caller.userId);
+			deps.logger.info("composition created", { meta: {
+				blockId: created.id,
+				name: created.name,
+				by: caller.userId
+			} });
+			deps.convergeSoon();
+			return { block: created };
+		}),
+		updateComposition: ({ blockId, expectedUpdatedAt, block, caller }) => serialized(async () => {
+			refuseIfChanged(deps, blockId, expectedUpdatedAt);
+			if (block.composition !== void 0) {
+				const validation = await validateAgainstStore(deps, block.composition, blockId);
+				if (!validation.ok) refuse(deps, {
+					name: block.name ?? blockId,
+					blockId
+				}, validation);
+			}
+			const updated = await deps.store.updateComposition(blockId, block);
+			deps.logger.info("composition updated", { meta: {
+				blockId,
+				by: caller.userId
+			} });
+			deps.convergeSoon();
+			return { block: updated };
+		}),
+		getComposition: async ({ blockId }) => {
+			if (!deps.store.isLoaded()) return {
+				state: "not-loaded",
+				reason: NOT_LOADED_REASON
+			};
+			const block = deps.store.get(blockId);
+			if (block === null || coreBlockComposition(block) === null) return {
+				state: "loaded",
+				view: null
+			};
+			const [view] = toViews([block], await readStates(deps, [blockId]));
+			return {
+				state: "loaded",
+				view: view ?? null
+			};
+		},
+		listCompositions: async () => {
+			if (!deps.store.isLoaded()) return {
+				state: "not-loaded",
+				reason: NOT_LOADED_REASON
+			};
+			const blocks = deps.store.list().filter((b) => coreBlockComposition(b) !== null);
+			if (blocks.length === 0) return {
+				state: "loaded",
+				views: []
+			};
+			return {
+				state: "loaded",
+				views: toViews(blocks, await readStates(deps, blocks.map((b) => b.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
+* stored unchecked. Refusing a save destroys nothing (D49).
+*
+* Sources 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) {
+	const addons = [...new Set(refs.map((r) => r.addonId))];
+	const listed = await Promise.all(addons.map(async (addonId) => {
+		try {
+			return [addonId, await ports.listByAddon(addonId)];
+		} catch (err) {
+			return [addonId, { error: errMsg(err) }];
+		}
+	}));
+	return new Map(listed);
+}
+async function describeOne(ports, ref, listing) {
+	if (listing === void 0) return {
+		kind: "unreadable",
+		error: `\`${ref.addonId}\` was not listed`
+	};
+	if ("error" in listing) return {
+		kind: "unreadable",
+		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)
+		};
+	}
+}
+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);
+}
+//#endregion
 //#region src/builtins/core-blocks/core-blocks.addon.ts
 /**
 * The `core-blocks` provider — CRUD over user-authored TypeScript, with the
@@ -886,6 +1343,7 @@ var CoreBlocksAddon = class extends BaseAddon {
 			store: {
 				list: () => store.list(),
 				get: (blockId) => store.get(blockId),
+				unreadableCompositions: () => store.unreadableCompositions(),
 				setStatus: (blockId, status, error) => store.setStatus(blockId, status, error)
 			},
 			host: createBrokerProcessHost(broker),
@@ -896,7 +1354,15 @@ var CoreBlocksAddon = class extends BaseAddon {
 				};
 				return compileBlock(this.transpiler, code);
 			},
-			logger: this.ctx.logger.child("supervisor")
+			logger: this.ctx.logger.child("supervisor"),
+			composer: { apply: async (input) => {
+				const api = this.ctx.api;
+				if (!api) throw new Error("no ctx.api on this node — the composer cannot be reached");
+				return api.composer.applyBlocks.mutate(input);
+			} },
+			integrationId: () => this.blocksIntegrationId,
+			storeLoaded: () => store.isLoaded(),
+			loadStore: () => store.load()
 		});
 	}
 	/**
@@ -1032,8 +1498,35 @@ var CoreBlocksAddon = class extends BaseAddon {
 					filePath: l.filePath,
 					content: l.content
 				})) };
-			}
+			},
+			...this.buildCompositionApi()
+		};
+	}
+	/**
+	* 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.
+	*/
+	buildCompositionApi() {
+		const requireApi = () => {
+			const api = this.ctx.api;
+			if (!api) throw new Error("core-blocks: no ctx.api on this node — compositions cannot be read");
+			return api;
 		};
+		return buildCompositionApi({
+			store: this.requireStore(),
+			describeSources: (refs) => 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),
+			lookupCap: buildCapabilityLookup(ALL_CAPABILITY_DEFINITIONS),
+			composerStates: async (blockIds) => (await requireApi().composer.getStates.query({ blockIds: [...blockIds] })).states,
+			convergeSoon: () => this.convergeSoon(),
+			logger: this.ctx.logger.child("compositions")
+		});
 	}
 };
 /**

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

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-D3ch99WD.js");
-const require_retired_settings_keys = require("../../retired-settings-keys-DG_LEPqC.js");
+const require_dist = require("../../dist-BhO9eYKO.js");
+const require_retired_settings_keys = require("../../retired-settings-keys-DHgnJqS3.js");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
 //#region src/builtins/device-manager/adoption-job-engine.ts

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

@@ -1,5 +1,5 @@
-import { At as locationIconKey, Et as legacyAutoLinkIds, Hn as sleep$1, Ht as parseStreamParamsFormPatch, Pn as isDeviceConfigCap, Sn as DeviceType, Tn as WELL_KNOWN_TAB_MAP, Un as EventCategory, W as buildStreamParamsConfigSchema, X as createDeviceExtensionProvider, Xt as runtimeStatePolicyFor, at as deviceStatusCapability, bn as DeviceFeature, ct as enumerateItemArrayFields, d as DAY_NAMES, et as defineExtensionSlotProvider, ft as expandContainer, gn as BaseAddon, gt as formatMinutes, h as DeviceStatusSchema, it as deviceStateCapability, k as STREAM_PROFILE_META, lt as enumerateSchemaFields, mn as errMsg, nt as deviceExtensionCapability, o as CAMERA_SWITCH_ORDER, rt as deviceManagerCapability, s as CAP_NAMES_WITH_STATUS, t as ALL_CAPABILITY_DEFINITIONS, tn as siteZoneKey, x as MINUTES_PER_DAY, xn as DeviceRole, y as LocationIconIdSchema, zt as normalizeUnit } from "../../dist-DdfJa8Zn.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-BJNhhXap.mjs";
+import { Bn as WELL_KNOWN_TAB_MAP, C as MINUTES_PER_DAY, Fn as DeviceFeature, Ht as locationIconKey, In as DeviceRole, Ln as DeviceType, Ot as formatMinutes, Rt as legacyAutoLinkIds, Yn as isDeviceConfigCap, Zt as normalizeUnit, _ as DeviceStatusSchema, bt as enumerateSchemaFields, dt as defineExtensionSlotProvider, en as parseStreamParamsFormPatch, gt as deviceStatusCapability, ht as deviceStateCapability, ir as EventCategory, j as STREAM_PROFILE_META, jn as BaseAddon, kn as errMsg, ln as runtimeStatePolicyFor, mn as siteZoneKey, mt as deviceManagerCapability, o as CAMERA_SWITCH_ORDER, p as DAY_NAMES, pt as deviceExtensionCapability, q as buildStreamParamsConfigSchema, rr as sleep$1, s as CAP_NAMES_WITH_STATUS, st as createDeviceExtensionProvider, t as ALL_CAPABILITY_DEFINITIONS, wt as expandContainer, x as LocationIconIdSchema, yt as enumerateItemArrayFields } from "../../dist-BEuQPDk_.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-CQvG6B-Q.mjs";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
 //#region src/builtins/device-manager/adoption-job-engine.ts