@classytic/arc 2.41.1 → 2.44.0

package/dist/plan-CJGMKoui.mjs

@@ -0,0 +1,565 @@
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { createEventRouter, matchEventPattern } from "@classytic/primitives/events";
+//#region src/factory/module/graph.ts
+/**
+* The module graph — which modules are active, which events each OWNS, which it consumes — and
+* the boot-time checks that keep it honest.
+*
+* - A `kind: 'bridge'` module joins domains: it is ACTIVE only when every `dependsOn` module is
+*   composed, and dropped (with the reason recorded) otherwise — never a boot error. Switching a
+*   domain off therefore removes every bridge that touched it, with no gate code anywhere.
+* - `publishes` names the facts a module owns. What it consumes is DERIVED from its
+*   `eventHandlers`, so it is never declared twice.
+* - The graph is two incidence relations over modules × events — P (publishes) and C (consumes).
+*   `analyzeModuleGraph` resolves them ONCE (the pattern × event matching is the only real cost);
+*   verification, rendering and `dependentsOf` all read that one analysis.
+*/
+function moduleKind(m) {
+	return m.kind ?? "domain";
+}
+/** The event names a module owns. */
+function publishedEvents(m) {
+	return (m.publishes ?? []).map((e) => typeof e === "string" ? e : e.name);
+}
+/** `order` owns `order:placed` and `order.placed` — `:` for new events, `.` for kernels' existing ones. */
+function ownsEvent(namespace, event) {
+	return event.startsWith(`${namespace}:`) || event.startsWith(`${namespace}.`);
+}
+/**
+* Drop every bridge whose `dependsOn` is not fully composed — to a fixpoint, so a bridge that
+* depends on a dropped bridge is dropped too. Domain and platform modules are never dropped:
+* their missing dependencies stay a hard error in `orderModules`.
+*/
+function activateBridges(modules) {
+	let active = [...modules];
+	const skipped = [];
+	for (;;) {
+		const names = new Set(active.map((m) => m.name));
+		const drop = active.filter((m) => moduleKind(m) === "bridge" && (m.dependsOn ?? []).some((d) => !names.has(d)));
+		if (drop.length === 0) return {
+			active,
+			skipped
+		};
+		for (const m of drop) skipped.push({
+			name: m.name,
+			missing: (m.dependsOn ?? []).filter((d) => !names.has(d))
+		});
+		const dropped = new Set(drop.map((m) => m.name));
+		active = active.filter((m) => !dropped.has(m.name));
+	}
+}
+/**
+* The events arc auto-emits for a resource (`<name>.created|updated|deleted`) — only for
+* mutations that actually MOUNTED. Overstating would satisfy a consumer that never receives one.
+*/
+function crudEventsOf(r) {
+	if (!r.adapter || r.disableDefaultRoutes) return [];
+	const disabled = new Set(r.disabledRoutes ?? []);
+	return [
+		"create",
+		"update",
+		"delete"
+	].filter((op) => !disabled.has(op)).map((op) => `${r.name}.${op}d`);
+}
+function buildModuleGraph(modules, consumedByModule, skippedBridges, externalEvents = [], derived = /* @__PURE__ */ new Map()) {
+	return Object.freeze({
+		modules: Object.freeze(modules.map((m) => Object.freeze({
+			name: m.name,
+			kind: moduleKind(m),
+			namespaces: Object.freeze([.../* @__PURE__ */ new Set([...m.eventNamespace === void 0 ? [m.name] : [m.eventNamespace].flat(), ...derived.get(m.name)?.namespaces ?? []])]),
+			dependsOn: Object.freeze([...m.dependsOn ?? []]),
+			publishes: Object.freeze([.../* @__PURE__ */ new Set([...publishedEvents(m), ...derived.get(m.name)?.publishes ?? []])]),
+			consumes: Object.freeze([...new Set(consumedByModule.get(m.name) ?? [])])
+		}))),
+		skippedBridges: Object.freeze([...skippedBridges]),
+		externalEvents: Object.freeze([...externalEvents])
+	});
+}
+/** Resolve the graph's incidence once — every check and view reads this. */
+function analyzeModuleGraph(graph) {
+	const owners = /* @__PURE__ */ new Map();
+	for (const m of graph.modules) for (const event of m.publishes) {
+		const list = owners.get(event);
+		if (list) list.push(m.name);
+		else owners.set(event, [m.name]);
+	}
+	const router = createEventRouter();
+	const reaches = /* @__PURE__ */ new Map();
+	const coupling = /* @__PURE__ */ new Map();
+	for (const m of graph.modules) {
+		const byPattern = /* @__PURE__ */ new Map();
+		for (const pattern of m.consumes) {
+			byPattern.set(pattern, []);
+			router.add(pattern, {
+				module: m.name,
+				pattern
+			});
+		}
+		reaches.set(m.name, byPattern);
+		coupling.set(m.name, /* @__PURE__ */ new Map());
+	}
+	for (const [event, publishers] of owners) for (const sub of router.route(event)) {
+		reaches.get(sub.module)?.get(sub.pattern)?.push(event);
+		const byPublisher = coupling.get(sub.module);
+		for (const publisher of publishers) {
+			if (publisher === sub.module) continue;
+			const list = byPublisher.get(publisher);
+			if (!list) byPublisher.set(publisher, [event]);
+			else if (list[list.length - 1] !== event) list.push(event);
+		}
+	}
+	return {
+		owners,
+		reaches,
+		coupling
+	};
+}
+/** Every issue in the graph — empty when it is sound. */
+function verifyModuleGraph(graph, analysis = analyzeModuleGraph(graph)) {
+	const issues = [];
+	for (const [event, owners] of analysis.owners) for (const extra of owners.slice(1)) issues.push({
+		code: "duplicate-owner",
+		module: extra,
+		event,
+		message: `event "${event}" is published by both "${owners[0]}" and "${extra}" — an event has exactly one owner.`
+	});
+	for (const m of graph.modules) {
+		for (const event of m.publishes) {
+			if (m.namespaces.some((ns) => ownsEvent(ns, event))) continue;
+			issues.push({
+				code: "outside-namespace",
+				module: m.name,
+				event,
+				message: `module "${m.name}" publishes "${event}" outside its namespace(s) ${m.namespaces.map((n) => `"${n}"`).join(", ")} — a module publishes its OWN facts; a process joining two domains is a bridge with its own namespace.`
+			});
+		}
+		for (const [pattern, hit] of analysis.reaches.get(m.name) ?? []) {
+			if (hit.length > 0) continue;
+			if (graph.externalEvents.some((ext) => ext === pattern || matchEventPattern(ext, pattern))) continue;
+			issues.push({
+				code: "no-publisher",
+				module: m.name,
+				event: pattern,
+				message: `module "${m.name}" consumes "${pattern}", which no active module publishes — declare the owner's \`publishes\`, list it in \`moduleGraph.externalEvents\`, or make "${m.name}" a bridge of the module that owns it.`
+			});
+		}
+	}
+	return issues;
+}
+/** The events a module declares `durability: 'durable'` in its `publishes`. */
+function durablePublishes(m) {
+	return (m.publishes ?? []).flatMap((e) => typeof e !== "string" && "durability" in e && e.durability === "durable" ? [e.name] : []);
+}
+/**
+* A durable event's publisher must `dependsOn` a transactional outbox, and each of its handlers
+* must declare `durability` (`'retry'` rethrows to the relay; `'boundary'` may swallow).
+*/
+function verifyEventDurability(modules, facts) {
+	const issues = [];
+	const durable = /* @__PURE__ */ new Set();
+	for (const m of modules) {
+		const events = durablePublishes(m);
+		for (const event of events) durable.add(event);
+		if (events.length === 0 || (m.dependsOn ?? []).some((d) => facts.outboxModules.has(d))) continue;
+		for (const event of events) issues.push({
+			code: "durable-without-outbox",
+			module: m.name,
+			event,
+			message: `module "${m.name}" publishes durable "${event}" but depends on no outbox with transactionalSave — its row cannot commit with the write.`
+		});
+	}
+	if (durable.size === 0) return issues;
+	for (const [moduleName, handlers] of facts.handlers) for (const h of handlers) {
+		if (h.durability !== void 0) continue;
+		for (const event of durable) {
+			if (!h.patterns.some((p) => matchEventPattern(p, event))) continue;
+			issues.push({
+				code: "durable-consumer-undeclared",
+				module: moduleName,
+				event,
+				message: `handler "${h.label}" consumes durable "${event}" without declaring durability ('retry' or 'boundary').`
+			});
+		}
+	}
+	return issues;
+}
+/**
+* What stops working if `name` is switched off: modules consuming events only it publishes
+* (a column of the coupling matrix), and bridges that `dependsOn` it — which arc drops.
+*/
+function dependentsOf(graph, name, analysis = analyzeModuleGraph(graph)) {
+	const starved = [];
+	for (const [consumer, byPublisher] of analysis.coupling) {
+		const events = (byPublisher.get(name) ?? []).filter((e) => (analysis.owners.get(e) ?? []).length === 1);
+		if (events.length > 0) starved.push({
+			module: consumer,
+			events: [...new Set(events)]
+		});
+	}
+	return {
+		starved,
+		droppedBridges: graph.modules.filter((m) => m.kind === "bridge" && m.dependsOn.includes(name)).map((m) => m.name)
+	};
+}
+/**
+* The graph as Markdown — modules, the coupling between them, then every event with its owner
+* and consumers. Generate it into the repo so people and agents read the map instead of grepping.
+*/
+function renderModuleGraph(graph, analysis = analyzeModuleGraph(graph)) {
+	const lines = [
+		"# Module graph",
+		"",
+		"| module | kind | depends on | publishes | consumes |",
+		"|---|---|---|---|---|"
+	];
+	for (const m of graph.modules) lines.push(`| ${m.name} | ${m.kind} | ${list(m.dependsOn)} | ${list(m.publishes)} | ${list(m.consumes)} |`);
+	if (graph.skippedBridges.length > 0) {
+		lines.push("", "## Inactive bridges", "", "| bridge | missing |", "|---|---|");
+		for (const b of graph.skippedBridges) lines.push(`| ${b.name} | ${list(b.missing)} |`);
+	}
+	lines.push("", "## Coupling — whose facts each module consumes", "", "| consumer | publisher | events |", "|---|---|---|");
+	for (const [consumer, byPublisher] of analysis.coupling) for (const [publisher, events] of byPublisher) lines.push(`| ${consumer} | ${publisher} | ${list([...new Set(events)])} |`);
+	lines.push("", "## Events", "", "| event | owner | consumers |", "|---|---|---|");
+	const consumersOf = /* @__PURE__ */ new Map();
+	for (const [consumer, byPattern] of analysis.reaches) for (const hit of byPattern.values()) for (const event of hit) consumersOf.set(event, (consumersOf.get(event) ?? /* @__PURE__ */ new Set()).add(consumer));
+	for (const [event, owners] of [...analysis.owners].sort(([a], [b]) => a < b ? -1 : 1)) lines.push(`| ${event} | ${owners.join(", ")} | ${list([...consumersOf.get(event) ?? []])} |`);
+	return `${lines.join("\n")}\n`;
+}
+function list(items) {
+	return items.length === 0 ? "—" : items.map((i) => `\`${i}\``).join(", ");
+}
+/**
+* Divide the graph by its coupling: Tarjan's strongly connected components over D = C·Pᵀ.
+* A component of more than one module is an EVENT CYCLE — modules that consume each other's
+* facts and so can only be deployed, disabled or reasoned about together. `layers` is the
+* condensation in dependency order: each layer consumes only from layers before it, so a layer's
+* modules can be verified, tested or split out in parallel.
+*/
+function eventTopology(graph, analysis = analyzeModuleGraph(graph)) {
+	const names = graph.modules.map((m) => m.name);
+	const edges = (n) => [...analysis.coupling.get(n)?.keys() ?? []];
+	const index = /* @__PURE__ */ new Map();
+	const low = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const stack = [];
+	const components = [];
+	let counter = 0;
+	const visit = (v) => {
+		index.set(v, counter);
+		low.set(v, counter);
+		counter++;
+		stack.push(v);
+		onStack.add(v);
+		for (const w of edges(v)) if (!index.has(w)) {
+			visit(w);
+			low.set(v, Math.min(low.get(v), low.get(w)));
+		} else if (onStack.has(w)) low.set(v, Math.min(low.get(v), index.get(w)));
+		if (low.get(v) === index.get(v)) {
+			const component = [];
+			for (let w = stack.pop(); w !== void 0; w = stack.pop()) {
+				onStack.delete(w);
+				component.push(w);
+				if (w === v) break;
+			}
+			components.push(component.sort());
+		}
+	};
+	for (const n of names) if (!index.has(n)) visit(n);
+	const componentOf = /* @__PURE__ */ new Map();
+	components.forEach((c, i) => {
+		for (const n of c) componentOf.set(n, i);
+	});
+	const depth = components.map(() => 0);
+	components.forEach((c, i) => {
+		for (const n of c) for (const dep of edges(n)) {
+			const j = componentOf.get(dep);
+			if (j !== i) depth[i] = Math.max(depth[i], depth[j] + 1);
+		}
+	});
+	const layers = [];
+	components.forEach((c, i) => {
+		const d = depth[i];
+		const layer = layers[d] ?? [];
+		layer.push(...c);
+		layers[d] = layer;
+	});
+	return {
+		cycles: components.filter((c) => c.length > 1),
+		layers: layers.filter(Boolean).map((layer) => layer.sort())
+	};
+}
+//#endregion
+//#region src/factory/module/resolve.ts
+function isLazyBridge(input) {
+	return typeof input === "object" && input !== null && !(input instanceof Promise) && typeof input.load === "function";
+}
+/** Replace each active lazy bridge's declaration with the module it loads. */
+function loadActiveBridges(active, lazyByName) {
+	return Promise.all(active.map((m) => {
+		const lazy = lazyByName.get(m.name);
+		return lazy ? loadLazyBridge(lazy) : m;
+	}));
+}
+/**
+* Resolve every input and activate bridges WITHOUT loading a lazy bridge — its declaration
+* stands in for it. The shared first half of `resolveModules` and `planModules`.
+*/
+async function declareModules(inputs) {
+	const { active, skipped } = activateBridges(await Promise.all(inputs.map((input) => isLazyBridge(input) ? {
+		name: input.name,
+		kind: "bridge",
+		dependsOn: input.dependsOn,
+		...input.requires ? { requires: input.requires } : {}
+	} : resolveModule(input))));
+	return {
+		active,
+		skipped,
+		lazyByName: new Map(inputs.filter(isLazyBridge).map((b) => [b.name, b]))
+	};
+}
+/** The loaded module must be the bridge that was declared — activation was decided on the declaration. */
+async function loadLazyBridge(lazy) {
+	const m = await resolveModule(lazy.load);
+	const deps = [...m.dependsOn ?? []].sort().join(",");
+	if (m.name !== lazy.name || m.kind !== "bridge" || deps !== [...lazy.dependsOn].sort().join(",") || portsKey(m.requires) !== portsKey(lazy.requires)) throw new Error(`[arc] lazy bridge "${lazy.name}" loaded a module that does not match its declaration (got name "${m.name}", kind "${m.kind ?? "domain"}", dependsOn [${deps}], requires ${portsKey(m.requires)}). Activation and the requirement check were decided on the declared name + dependsOn + requires, so they must be identical.`);
+	return m;
+}
+/** A stable fingerprint of a `requires` declaration, for the declared-vs-loaded comparison. */
+function portsKey(requires) {
+	const list = (names) => [...names ?? []].sort().join(",");
+	return `ports[${list(requires?.ports)}] optional[${list(requires?.optionalPorts)}] modules[${list(requires?.modules)}]`;
+}
+/**
+* Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+* (this is where a dynamic `import()` fires); a promise (or plain module) is
+* awaited. Called once per module at the start of the bootstrap phase.
+*/
+async function resolveModule(input) {
+	if (isLazyBridge(input)) return loadLazyBridge(input);
+	const resolved = typeof input === "function" ? await input() : await input;
+	if (!resolved || typeof resolved !== "object" || typeof resolved.name !== "string") throw new Error("[arc] a `modules` entry resolved to something that is not an ArcModule (expected an object with a string `name`). Check dynamic-import thunks return `createXModule(deps)` (or the module object), not the namespace.");
+	if (resolved.name.trim().length === 0) throw new Error("[arc] a `modules` entry has an empty (or whitespace-only) `name`. A module's name is its graph key, its `arc.modules` export key, its `dependsOn` target, and its label in every boot diagnostic — give it a stable, non-empty identifier.");
+	return resolved;
+}
+/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
+async function resolveContribution(contribution, fastify) {
+	if (!contribution) return [];
+	return typeof contribution === "function" ? await contribution(fastify) : contribution;
+}
+/**
+* `resolveContribution` with module attribution — the form every arm collector
+* should use.
+*
+* A contribution factory closes over booted engines, so it throws for exactly
+* the reasons a bootstrap does ("connection unavailable", "engine not ready").
+* Bare, that message names neither the module nor the arm, which in a graph of
+* twenty modules turns a one-line fix into a bisect. Every other module
+* boundary (`plugins`, `bootstrap`, `resources`, `afterResources`) already
+* wraps with the owning module's name; this keeps the arms consistent with
+* them. The original error is preserved via `{ cause }`.
+*/
+async function resolveModuleArm(module, arm, contribution, fastify) {
+	let resolved;
+	try {
+		resolved = await resolveContribution(contribution, fastify);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`[arc] module "${module.name}" ${arm} factory threw: ${msg}`, { cause: err });
+	}
+	if (!Array.isArray(resolved)) throw new TypeError(`[arc] module "${module.name}" ${arm} factory must return an array — received ${resolved === null ? "null" : typeof resolved}.`);
+	return resolved;
+}
+//#endregion
+//#region src/factory/module/order.ts
+/**
+* Order modules for composition — a STABLE topological sort. Every later phase
+* (bootstrap, resources, afterResources, reverse-order onClose) iterates the
+* returned list, so a module's dependencies are always composed before it.
+*
+* Edges: each module's `dependsOn`, plus an implicit edge from every
+* `kind: 'aggregator'` module to every non-aggregator one. Among READY modules a
+* `kind: 'platform'` one is emitted first; otherwise list order breaks ties, so
+* declaring an edge never reorders an unrelated module.
+*
+* Throws on a duplicate name, a `dependsOn` name not composed, a self-reference,
+* or a cycle (reporting the concrete `a → b → … → a` path).
+*/
+function orderModules(modules) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const m of modules) {
+		if (byName.has(m.name)) throw new Error(`[arc] Duplicate module name "${m.name}" — composed twice; check your modules array.`);
+		byName.set(m.name, m);
+	}
+	for (const m of modules) for (const dep of m.dependsOn ?? []) {
+		if (dep === m.name) throw new Error(`[arc] module "${m.name}" dependsOn itself — remove the self-reference.`);
+		if (!byName.has(dep)) throw new Error(`[arc] module "${m.name}" dependsOn "${dep}", which is not composed. Add the "${dep}" module to createApp({ modules }) (before this one is fine — arc orders them), or drop the dependency. Composed modules: ${[...byName.keys()].join(", ") || "(none)"}.`);
+	}
+	const edges = effectiveEdges(modules);
+	const originalIndex = /* @__PURE__ */ new Map();
+	let nextIndex = 0;
+	for (const m of modules) originalIndex.set(m.name, nextIndex++);
+	const pendingDeps = new Map(modules.map((m) => [m.name, (edges.get(m.name) ?? []).length]));
+	const dependents = /* @__PURE__ */ new Map();
+	for (const m of modules) for (const dep of edges.get(m.name) ?? []) {
+		const list = dependents.get(dep);
+		if (list) list.push(m.name);
+		else dependents.set(dep, [m.name]);
+	}
+	const rank = (m) => (m.kind === "platform" ? 0 : modules.length) + (originalIndex.get(m.name) ?? 0);
+	const ordered = [];
+	const remaining = new Set(modules.map((m) => m.name));
+	while (remaining.size > 0) {
+		let pick;
+		let pickRank = Number.POSITIVE_INFINITY;
+		for (const name of remaining) {
+			if (pendingDeps.get(name) !== 0) continue;
+			const candidate = byName.get(name);
+			if (!candidate) continue;
+			const r = rank(candidate);
+			if (r < pickRank) {
+				pick = candidate;
+				pickRank = r;
+			}
+		}
+		if (pick === void 0) throw new Error(describeModuleCycle(remaining, edges));
+		ordered.push(pick);
+		remaining.delete(pick.name);
+		for (const dependent of dependents.get(pick.name) ?? []) pendingDeps.set(dependent, (pendingDeps.get(dependent) ?? 1) - 1);
+	}
+	return ordered;
+}
+/** Declared `dependsOn` plus each aggregator's implicit edge to every non-aggregator module. */
+function effectiveEdges(modules) {
+	const fleet = modules.filter((m) => m.kind !== "aggregator").map((m) => m.name);
+	return new Map(modules.map((m) => [m.name, m.kind === "aggregator" ? [.../* @__PURE__ */ new Set([...m.dependsOn ?? [], ...fleet])] : [...m.dependsOn ?? []]]));
+}
+/** Walk the still-unordered subgraph for one concrete cycle path. */
+function describeModuleCycle(remaining, edges) {
+	const stack = [];
+	const onStack = /* @__PURE__ */ new Set();
+	const done = /* @__PURE__ */ new Set();
+	let cycle = null;
+	const walk = (name) => {
+		if (cycle) return;
+		stack.push(name);
+		onStack.add(name);
+		for (const dep of edges.get(name) ?? []) {
+			if (!remaining.has(dep)) continue;
+			if (onStack.has(dep)) {
+				cycle = [...stack.slice(stack.indexOf(dep)), dep];
+				return;
+			}
+			if (!done.has(dep)) walk(dep);
+			if (cycle) return;
+		}
+		onStack.delete(name);
+		stack.pop();
+		done.add(name);
+	};
+	for (const name of remaining) {
+		if (!done.has(name)) walk(name);
+		if (cycle) break;
+	}
+	return `[arc] module dependency cycle: ${cycle ? cycle.join(" → ") : [...remaining].join(", ")}. Modules cannot dependsOn each other circularly — break it with a shared module both point at, declare the softer direction as \`requires.modules\` (presence only, no ordering edge), or wire it through an event/port. A module that dependsOn a \`kind: 'aggregator'\` module is always a cycle.`;
+}
+//#endregion
+//#region src/factory/module/plan.ts
+/** A port counts as supplied when it is an own key whose value is neither `undefined` nor `null`. */
+function isSupplied(ports, name) {
+	return Object.hasOwn(ports, name) && ports[name] !== void 0 && ports[name] !== null;
+}
+/**
+* Every problem in an ACTIVE module list (bridges already activated): duplicate names,
+* self/missing `dependsOn`, unmet `requires.modules`, unsupplied `requires.ports`. Cycles are
+* `orderModules`' to report, with their path.
+*/
+function compositionProblems(modules, ports = {}) {
+	const supplied = ports;
+	const composed = /* @__PURE__ */ new Set();
+	const problems = [];
+	const add = (code, module, target, message) => problems.push({
+		code,
+		module,
+		target,
+		message
+	});
+	for (const m of modules) {
+		if (composed.has(m.name)) add("duplicate-module", m.name, m.name, `Duplicate module name "${m.name}" — it is composed twice; remove the duplicate from createApp({ modules })`);
+		composed.add(m.name);
+	}
+	for (const m of modules) {
+		for (const dep of m.dependsOn ?? []) if (dep === m.name) add("self-dependency", m.name, dep, `module "${m.name}" dependsOn itself — remove the self-reference`);
+		else if (!composed.has(dep)) add("missing-dependency", m.name, dep, `module "${m.name}" dependsOn "${dep}", which is not composed — add the "${dep}" module to createApp({ modules }), or drop the dependency`);
+		for (const dep of m.requires?.modules ?? []) if (!composed.has(dep)) add("missing-module", m.name, dep, `module "${m.name}" requires "${dep}" to be composed — add the "${dep}" module to createApp({ modules })`);
+		for (const port of m.requires?.ports ?? []) if (!isSupplied(supplied, port)) add("missing-port", m.name, port, `module "${m.name}" requires port "${port}" — supply createApp({ ports: { ${port} } })`);
+	}
+	return problems;
+}
+/** Throw ONE error listing every composition problem, or return. */
+function assertComposable(modules, ports) {
+	const problems = compositionProblems(modules, ports);
+	if (problems.length === 0) return;
+	throw new Error(`[arc] cannot compose the module graph — nothing was booted (${problems.length} problem${problems.length === 1 ? "" : "s"}):\n` + problems.map((p) => `  - ${p.message}`).join("\n"));
+}
+/** The ports handed to one module's setup phases — only those it declared, frozen. */
+function portsForModule(module, ports = {}) {
+	const supplied = ports;
+	const own = {};
+	for (const name of [...module.requires?.ports ?? [], ...module.requires?.optionalPorts ?? []]) if (isSupplied(supplied, name)) own[name] = supplied[name];
+	return Object.freeze(own);
+}
+/**
+* Dry-run a composition: resolve inputs, activate bridges, order, check requirements — the same
+* functions `createApp` calls, so the plan fails where boot would and orders as boot would.
+*
+* Thunks ARE invoked (their result is the module); a `LazyBridge` is decided on its declaration
+* and never loaded.
+*/
+async function planModules(inputs, options = {}) {
+	const { active, skipped } = await declareModules(inputs);
+	assertComposable(active, options.ports);
+	const ordered = orderModules(active);
+	return Object.freeze({
+		order: Object.freeze(ordered.map((m) => m.name)),
+		activeBridges: Object.freeze(ordered.filter((m) => m.kind === "bridge").map((m) => m.name)),
+		skippedBridges: Object.freeze([...skipped])
+	});
+}
+/** Boot-time composition: `planModules`' steps, with active lazy bridges loaded. */
+async function composeModules(inputs, ports) {
+	const { active, skipped, lazyByName } = await declareModules(inputs);
+	assertComposable(active, ports);
+	return {
+		modules: orderModules(await loadActiveBridges(active, lazyByName)),
+		skipped
+	};
+}
+/**
+* The modules `roots` need to boot: their `dependsOn` and `requires.modules` closure, plus every
+* `kind: 'platform'` module (and its own closure). Returned in INPUT order, so ordering the result
+* matches ordering the full list.
+*
+* Bridges are not pulled in — a bridge joins domains, it is not needed by them. An aggregator
+* root brings only its declared edges: it reads whatever is composed.
+*
+* Throws on an unknown root, or an edge to a module that is not in `modules`.
+*/
+function resolveModuleClosure(modules, roots) {
+	const byName = new Map(modules.map((m) => [m.name, m]));
+	const unknown = roots.filter((r) => !byName.has(r));
+	if (unknown.length > 0) throw new Error(`[arc] resolveModuleClosure: unknown root module(s) ${unknown.map((r) => `"${r}"`).join(", ")}. Modules: ${[...byName.keys()].join(", ") || "(none)"}.`);
+	const included = /* @__PURE__ */ new Set();
+	const visit = (name, from) => {
+		if (included.has(name)) return;
+		const m = byName.get(name);
+		if (!m) throw new Error(`[arc] resolveModuleClosure: module "${from}" needs "${name}", which is not in the module list.`);
+		included.add(name);
+		for (const dep of m.dependsOn ?? []) visit(dep, name);
+		for (const dep of m.requires?.modules ?? []) visit(dep, name);
+	};
+	for (const root of roots) visit(root, void 0);
+	for (const m of modules) if (m.kind === "platform") visit(m.name, void 0);
+	return modules.filter((m) => included.has(m.name));
+}
+//#endregion
+export { dependentsOf as _, portsForModule as a, verifyEventDurability as b, declareModules as c, resolveModule as d, resolveModuleArm as f, crudEventsOf as g, buildModuleGraph as h, planModules as i, isLazyBridge as l, analyzeModuleGraph as m, composeModules as n, resolveModuleClosure as o, activateBridges as p, compositionProblems as r, orderModules as s, assertComposable as t, resolveContribution as u, eventTopology as v, verifyModuleGraph as x, renderModuleGraph as y };