@bett3r-dev/pv3 1.0.0 → 1.1.7

package/build/libraries/deployment-units/computeMDUs.js

@@ -0,0 +1,695 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeMDUs = void 0;
+const modulePath_1 = require("../modulePath");
+const path_1 = __importDefault(require("path"));
+// ---------------------------------------------------------------------------
+// Union-Find for connected components
+// ---------------------------------------------------------------------------
+class UnionFind {
+    parent = new Map();
+    rank = new Map();
+    add(id) {
+        if (!this.parent.has(id)) {
+            this.parent.set(id, id);
+            this.rank.set(id, 0);
+        }
+    }
+    find(id) {
+        let current = id;
+        while (this.parent.get(current) !== current) {
+            const grandparent = this.parent.get(this.parent.get(current));
+            this.parent.set(current, grandparent);
+            current = grandparent;
+        }
+        return current;
+    }
+    union(a, b) {
+        const rootA = this.find(a);
+        const rootB = this.find(b);
+        if (rootA === rootB)
+            return;
+        const rankA = this.rank.get(rootA);
+        const rankB = this.rank.get(rootB);
+        if (rankA < rankB) {
+            this.parent.set(rootA, rootB);
+        }
+        else if (rankA > rankB) {
+            this.parent.set(rootB, rootA);
+        }
+        else {
+            this.parent.set(rootB, rootA);
+            this.rank.set(rootA, rankA + 1);
+        }
+    }
+    getComponents() {
+        const components = new Map();
+        for (const id of this.parent.keys()) {
+            const root = this.find(id);
+            if (!components.has(root)) {
+                components.set(root, []);
+            }
+            components.get(root).push(id);
+        }
+        return components;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const makeRelativePath = (absolutePath, serviceRoot) => {
+    if (!absolutePath)
+        return '';
+    return path_1.default.relative(serviceRoot, absolutePath).replace(/\\/g, '/');
+};
+/**
+ * Derives the named export from an artifact's registered name.
+ * getStackTrace() captures the file-derived name (e.g. "ChartOfAccounts" from
+ * chartOfAccounts.aggregate.ts), but the actual export in the file typically
+ * includes a type suffix (e.g. "ChartOfAccountsAggregate").
+ *
+ * If the registered name already ends with the expected suffix, it's returned as-is.
+ * Otherwise the suffix is appended.
+ */
+const typeSuffixMap = {
+    aggregate: 'Aggregate',
+    externalSystem: 'System',
+    readmodel: 'Readmodel',
+    policy: 'Policy'
+};
+const deriveExportName = (name, type) => {
+    const suffix = typeSuffixMap[type];
+    if (!suffix)
+        return name; // endpoints and unknown types
+    // If name already ends with the suffix, return as-is
+    if (name.endsWith(suffix))
+        return name;
+    return `${name}${suffix}`;
+};
+/**
+ * The module a unit is addressed by (`<module>:<Name>` in `--lift`).
+ *
+ * The filesystem is authoritative: an artifact under `modules/billing/` belongs
+ * to billing whatever it declares. The declared subdomain is only a fallback for
+ * artifacts that sit outside a module directory, because subdomain answers a
+ * different question — it drives route authorization, and billing deliberately
+ * declares `.withSubdomain('')` (ADR-026) so its routes carry no `x-subdomain`.
+ * Reading the label off the subdomain made all 18 of those units `unknown:` and
+ * therefore unaddressable.
+ */
+const deriveModule = (filePath, subdomain) => {
+    return (0, modulePath_1.moduleFromPath)(filePath) || subdomain || 'unknown';
+};
+/** `healthSync.endpoints.ts` -> `healthSync`, mirroring `getStackTrace()`'s naming. */
+const fileDerivedName = (filePath) => path_1.default.basename(filePath).replace(/\..+$/, '');
+/**
+ * A route's identity: `<METHOD> <route>`, method defaulting to GET exactly as
+ * `registerOpenApiEndpoint` does for the same endpoint.
+ *
+ * This string is the join key. Teselly's manifest-coverage guard builds the
+ * other side of the comparison with the identical expression (`routeId` in
+ * `scripts/checkManifestCoverage.ts`), and a key that differs by so much as the
+ * default verb makes that join half-match in silence.
+ */
+const routeId = (endpoint) => `${(endpoint.method || 'GET').toUpperCase()} ${endpoint.route}`;
+const groupEndpointsByFile = (customEndpoints) => {
+    const groups = new Map();
+    for (const endpoint of customEndpoints) {
+        const group = groups.get(endpoint.filePath) || {
+            filePath: endpoint.filePath,
+            name: '',
+            subdomain: endpoint.subdomain,
+            linkedTo: [],
+            routes: [],
+            endpoints: []
+        };
+        group.endpoints.push(endpoint);
+        // One endpoint's declaration speaks for the whole file — see `linkedTo` on
+        // EndpointGroup. Its undeclared siblings ride along into the linked unit.
+        for (const target of endpoint.linkedTo || []) {
+            if (!group.linkedTo.includes(target))
+                group.linkedTo.push(target);
+        }
+        // Deduplicated by route id, because `registerEndpoint` stores an endpoint
+        // under TWO route-table keys when its path has an optional parameter, so a
+        // caller reading that table hands the same route in twice.
+        //
+        // The `route` guard is not for the port path — `route` is required on
+        // `ManifestEndpoint`, and `registerEndpoint` would throw on
+        // `endpoint.route.match( … )` immediately after the capture anyway, so a
+        // route-less endpoint never reaches the route table. It is for the OTHER
+        // caller class: one passing `customEndpoints` in directly, from untyped
+        // JavaScript (teselly's manifest fixtures do exactly this). Such an entry
+        // contributes nothing rather than a `"GET undefined"` line in a committed,
+        // drift-watched artifact.
+        if (endpoint.route) {
+            const id = routeId(endpoint);
+            if (!group.routes.includes(id))
+                group.routes.push(id);
+        }
+        groups.set(endpoint.filePath, group);
+    }
+    for (const group of groups.values()) {
+        const [declaringFunction, ...furtherDeclaringFunctions] = [
+            ...new Set(group.endpoints.map(e => e.exportName).filter((name) => !!name))
+        ];
+        // One declaring function is the shape the loader can honour — it calls that
+        // one export. Anything else falls back to the file name and leans on the
+        // loader's fuzzy export match.
+        group.name = declaringFunction && furtherDeclaringFunctions.length === 0
+            ? declaringFunction
+            : fileDerivedName(group.filePath);
+    }
+    return [...groups.values()];
+};
+// ---------------------------------------------------------------------------
+// computeMDUs — the main algorithm
+// ---------------------------------------------------------------------------
+const computeMDUs = (registeredEndpoints, serviceName, serviceRoot, customEndpoints) => {
+    const nodes = new Map();
+    const uf = new UnionFind();
+    const validationErrors = [];
+    // Node keys are type-prefixed to avoid collisions (e.g., an aggregate and
+    // policy can share the same registered name like "LanggraphAgentRunner")
+    const nodeKey = (type, name) => `${type}::${name}`;
+    // -----------------------------------------------------------------------
+    // 1. INITIALIZE nodes
+    // -----------------------------------------------------------------------
+    // Aggregates
+    for (const [name, data] of Object.entries(registeredEndpoints.aggregates)) {
+        const module = deriveModule(data.filePath, data.subdomain);
+        const key = nodeKey('aggregate', name);
+        nodes.set(key, {
+            name,
+            type: 'aggregate',
+            module,
+            filePath: data.filePath
+        });
+        uf.add(key);
+    }
+    // External systems
+    for (const [name, data] of Object.entries(registeredEndpoints.systems)) {
+        const module = deriveModule(data.filePath, data.subdomain);
+        const key = nodeKey('externalSystem', name);
+        nodes.set(key, {
+            name,
+            type: 'externalSystem',
+            module,
+            filePath: data.filePath
+        });
+        uf.add(key);
+    }
+    // Readmodels — registered under `projectors`, which since TV1-2275 also holds
+    // readmodels that project NOTHING. A query-only readmodel (`ReadmodelBuilder(
+    // Schema )` with no events namespace) serves a GET route and is therefore a
+    // deployment artifact like any other; it simply consumes nothing, so `events` is
+    // empty and it joins no component through an event edge. The map keeps the name:
+    // renaming it is a pv3-types breaking change across every consumer, for a naming
+    // gain.
+    for (const [name, data] of Object.entries(registeredEndpoints.projectors)) {
+        const module = deriveModule(data.filePath, data.subdomain);
+        const key = nodeKey('readmodel', name);
+        nodes.set(key, {
+            name,
+            type: 'readmodel',
+            module,
+            filePath: data.filePath,
+            events: data.events
+        });
+        uf.add(key);
+    }
+    // Policies
+    for (const [name, data] of Object.entries(registeredEndpoints.policies)) {
+        const module = deriveModule(data.filePath, data.subdomain);
+        const key = nodeKey('policy', name);
+        nodes.set(key, {
+            name,
+            type: 'policy',
+            module,
+            filePath: data.filePath,
+            commandHandlerName: data.commandHandlerName,
+            linkedTo: data.linkedTo,
+            isStandalone: data.isStandalone,
+            events: data.events
+        });
+        uf.add(key);
+    }
+    // The artifact that already owns a file, by path. A readmodel, aggregate,
+    // system or policy file may ALSO register manual routes at the top level of
+    // its factory (`featureFlags.readmodel.ts` registers two), and V8 then names
+    // the frame after that same factory — so a second node for it would carry the
+    // same filePath, name AND exportName as the first. Insertion order decides if
+    // one file somehow declares two artifacts; that order is the fixed
+    // aggregates -> systems -> readmodels -> policies walk above.
+    const artifactNodeByFilePath = new Map();
+    for (const [key, node] of nodes) {
+        if (!artifactNodeByFilePath.has(node.filePath))
+            artifactNodeByFilePath.set(node.filePath, key);
+    }
+    // Manually registered endpoints, one node per declaring file. Keyed by path
+    // rather than by name, so two files that derive the same name cannot collide
+    // and silently drop one of them.
+    const endpointGroups = groupEndpointsByFile(customEndpoints || []);
+    /**
+     * The node a declaring file resolves to: the artifact that already owns the
+     * file when there is one, otherwise the file's own endpoint node.
+     *
+     * One file is one unit. A file that already owns an artifact is already
+     * placed by it, and emitting a second artifact would put that file in two
+     * units — two pods requiring it, both running its factory, both registering
+     * every route in it. The routes are attached to the owning artifact instead,
+     * which keeps the route -> unit join whole.
+     */
+    const groupNodeKey = (group) => artifactNodeByFilePath.get(group.filePath) || nodeKey('endpoint', group.filePath);
+    for (const group of endpointGroups) {
+        const owningKey = artifactNodeByFilePath.get(group.filePath);
+        if (owningKey) {
+            nodes.get(owningKey).routes = group.routes;
+            continue;
+        }
+        const key = nodeKey('endpoint', group.filePath);
+        nodes.set(key, {
+            name: group.name,
+            type: 'endpoint',
+            module: deriveModule(group.filePath, group.subdomain),
+            filePath: group.filePath,
+            linkedTo: group.linkedTo,
+            routes: group.routes
+        });
+        uf.add(key);
+    }
+    // Every file in a module that declares no target — and owns no other artifact
+    // — joins ONE component, which below becomes `<module>:Endpoints`. Per module
+    // rather than per file because that id is hand-written into a topology intent
+    // and must survive a file rename — a filename-derived unit id makes a rename
+    // silently rewrite a persisted deployment identifier (and it is ~13 units
+    // instead of ~35).
+    const undeclaredEndpointsByModule = new Map();
+    for (const group of endpointGroups) {
+        if (group.linkedTo.length > 0)
+            continue;
+        if (artifactNodeByFilePath.has(group.filePath))
+            continue;
+        const key = nodeKey('endpoint', group.filePath);
+        const module = deriveModule(group.filePath, group.subdomain);
+        const first = undeclaredEndpointsByModule.get(module);
+        if (first === undefined)
+            undeclaredEndpointsByModule.set(module, key);
+        else
+            uf.union(first, key);
+    }
+    // Build a lookup of command handler names → node keys (aggregates + systems)
+    // Supports both file-derived names ("publications") and function-style names ("PublicationsAggregate")
+    const commandHandlerByName = new Map(); // registered name → node key
+    const commandHandlerNormalizedLookup = new Map(); // normalized → node key
+    const normalizeCommandHandlerName = (name) => name.toLowerCase().replace(/aggregate$|system$|externalsystem$/, '');
+    for (const [key, node] of nodes) {
+        if (node.type === 'aggregate' || node.type === 'externalSystem') {
+            commandHandlerByName.set(node.name, key);
+            commandHandlerNormalizedLookup.set(normalizeCommandHandlerName(node.name), key);
+        }
+    }
+    /** Resolves a command handler reference (name) to its node key */
+    const resolveCommandHandler = (ref) => {
+        if (commandHandlerByName.has(ref))
+            return commandHandlerByName.get(ref);
+        return commandHandlerNormalizedLookup.get(normalizeCommandHandlerName(ref));
+    };
+    // Readmodels, by their registered name. A SECOND map on purpose, read only by
+    // `resolveEndpointTarget` below — see there.
+    const readmodelByName = new Map();
+    for (const [key, node] of nodes) {
+        if (node.type === 'readmodel')
+            readmodelByName.set(node.name, key);
+    }
+    /**
+     * The node an ENDPOINT's `linkedTo` entry names — a command handler, or a
+     * readmodel, so a route can be pinned to a query pod and not only to a
+     * command one.
+     *
+     * This is deliberately NOT a widening of `resolveCommandHandler`, and the two
+     * must not be merged: the same word means different things on the two
+     * declarers. A policy's `linkedTo` asserts *"I dispatch commands here"*, which
+     * a readmodel cannot receive — one shared lookup would legalise a command
+     * aimed at something that can never take it, silently, at generation time. An
+     * endpoint's asserts *"serve me where this lives"*, which a query pod honours
+     * exactly as well as a command pod.
+     *
+     * Readmodels match by their REGISTERED NAME ONLY — no suffix-stripping
+     * counterpart to `normalizeCommandHandlerName`. That normalization exists so a
+     * declaration may name the export (`ItemsAggregate`) where the registration is
+     * file-derived (`Items`); every registered readmodel name already ends in
+     * `Readmodel`, so the equivalent buys nothing here. A miss is a loud
+     * generation error naming the reference, never a silent placement.
+     *
+     * Command handlers win a tie: a name that resolves as both keeps resolving to
+     * the aggregate it already did, so no existing declaration changes meaning.
+     */
+    const resolveEndpointTarget = (ref) => resolveCommandHandler(ref) || readmodelByName.get(ref);
+    // -----------------------------------------------------------------------
+    // 2. BUILD edges (command execution dependencies only)
+    // -----------------------------------------------------------------------
+    // For each policy: edges from commandHandlerName and linkedTo
+    for (const [key, node] of nodes) {
+        if (node.type !== 'policy')
+            continue;
+        const targetKeys = [];
+        if (node.commandHandlerName) {
+            const resolvedKey = resolveCommandHandler(node.commandHandlerName);
+            if (resolvedKey) {
+                targetKeys.push(resolvedKey);
+            }
+            else {
+                validationErrors.push(`Policy "${node.name}" references commandHandler "${node.commandHandlerName}" which does not exist in registeredEndpoints.`);
+            }
+        }
+        if (node.linkedTo) {
+            for (const target of node.linkedTo) {
+                const resolvedKey = resolveCommandHandler(target);
+                if (resolvedKey) {
+                    targetKeys.push(resolvedKey);
+                }
+                else {
+                    validationErrors.push(`Policy "${node.name}" has linkedTo "${target}" which does not exist in registeredEndpoints.`);
+                }
+            }
+        }
+        // VALIDATE: every policy must have commandHandlerName, linkedTo, or isStandalone
+        if (!node.commandHandlerName && (!node.linkedTo || node.linkedTo.length === 0) && !node.isStandalone) {
+            validationErrors.push(`Policy "${node.name}" has no dependency declaration. Use .linkedTo() or .standalone().`);
+        }
+        // Union the policy with each of its targets
+        for (const targetKey of targetKeys) {
+            uf.union(key, targetKey);
+        }
+    }
+    /** The targets of one endpoint, in declaration order, dropping unresolved ones. */
+    const resolveEndpointTargets = (endpoint) => (endpoint.linkedTo || [])
+        .map(target => resolveEndpointTarget(target))
+        .filter((key) => key !== undefined);
+    // For each custom endpoint: edges from linkedTo. Unioned per endpoint rather
+    // than per file, because the two cases are not the same declaration: ONE route
+    // naming several aggregates deliberately merges them (it writes to all of
+    // them), whereas two routes in one file pulling towards different units is an
+    // accident of file layout. Merging those silently would fuse two unrelated
+    // units, so the per-file check below has to be able to see them apart.
+    for (const group of endpointGroups) {
+        for (const endpoint of group.endpoints) {
+            for (const target of endpoint.linkedTo || []) {
+                if (!resolveEndpointTarget(target)) {
+                    validationErrors.push(`Endpoint "${endpoint.name}" has linkedTo "${target}" which does not exist in registeredEndpoints.`);
+                }
+            }
+            const [firstTarget, ...furtherTargets] = resolveEndpointTargets(endpoint);
+            for (const targetKey of furtherTargets) {
+                uf.union(firstTarget, targetKey);
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Fail fast on validation errors
+    // -----------------------------------------------------------------------
+    if (validationErrors.length > 0) {
+        throw new Error(`[deployment-units] Validation errors:\n${validationErrors.map(e => `  - ${e}`).join('\n')}`);
+    }
+    // -----------------------------------------------------------------------
+    // 2b. One file, one unit — then join the file's artifact to that unit
+    // -----------------------------------------------------------------------
+    for (const group of endpointGroups) {
+        const perEndpointRoots = group.endpoints
+            // An endpoint declaring nothing pulls the file nowhere: its file is placed
+            // by whatever its siblings declare, or — if none of them declares
+            // anything — by its module. Only a declaration can contradict another.
+            .filter(endpoint => resolveEndpointTargets(endpoint).length > 0)
+            .map(endpoint => {
+            // An endpoint's own targets were unioned above, so any one of them names
+            // the unit the endpoint resolves to.
+            const [firstTarget] = resolveEndpointTargets(endpoint);
+            return { endpoint, root: uf.find(firstTarget) };
+        });
+        if (new Set(perEndpointRoots.map(r => r.root)).size > 1) {
+            const declarations = perEndpointRoots
+                .map(r => `  - "${r.endpoint.name}" -> ${(r.endpoint.linkedTo || []).join(', ')}`)
+                .join('\n');
+            throw new Error(`[deployment-units] Endpoints declared in "${makeRelativePath(group.filePath, serviceRoot)}" ` +
+                `resolve to different deployment units:\n${declarations}\n` +
+                'A declaring file is one deployment artifact, so it can only belong to one unit. ' +
+                'Split the file so each unit\'s routes live in their own file.');
+        }
+        // `groupNodeKey` and not the endpoint key: a file that already owns an
+        // artifact has no endpoint node, and its `linkedTo` is a co-location claim
+        // made by the file — so it is that artifact which joins the target's unit.
+        const key = groupNodeKey(group);
+        for (const target of group.linkedTo) {
+            const resolvedKey = resolveEndpointTarget(target);
+            if (resolvedKey)
+                uf.union(key, resolvedKey);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 3. COMPUTE connected components
+    // -----------------------------------------------------------------------
+    const components = uf.getComponents();
+    // -----------------------------------------------------------------------
+    // 4. CLASSIFY MDUs and build units
+    // -----------------------------------------------------------------------
+    const units = {};
+    const merges = [];
+    const componentInfos = [];
+    for (const [, memberNames] of components) {
+        const componentNodes = memberNames
+            .map(n => nodes.get(n))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const hasCommandHandler = componentNodes.some(n => n.type === 'aggregate' || n.type === 'externalSystem');
+        const hasOnlyReadmodel = componentNodes.length === 1 && componentNodes[0].type === 'readmodel';
+        // Already sorted by name, so `[0]` is the alphabetically first readmodel —
+        // the same tie-break `hasCommandHandler` uses to pick among aggregates.
+        const readmodelNodes = componentNodes.filter(n => n.type === 'readmodel');
+        const isStandalonePolicy = componentNodes.length === 1 && componentNodes[0].type === 'policy' && componentNodes[0].isStandalone;
+        const hasOnlyEndpoints = componentNodes.every(n => n.type === 'endpoint');
+        let unitType;
+        let primaryNode;
+        if (hasOnlyReadmodel) {
+            unitType = 'readmodel';
+            primaryNode = componentNodes[0];
+        }
+        else if (hasCommandHandler) {
+            unitType = 'command-group';
+            // Primary is the first aggregate/system alphabetically
+            primaryNode = componentNodes.find(n => n.type === 'aggregate' || n.type === 'externalSystem');
+        }
+        else if (isStandalonePolicy) {
+            // Standalone policies become their own MDU as command-group (no aggregate)
+            unitType = 'command-group';
+            primaryNode = componentNodes[0];
+        }
+        else if (hasOnlyEndpoints) {
+            // A module's undeclared routes. Typed like the standalone policy beside
+            // it — a unit with no command handler that must still be liftable and
+            // routable — and deliberately NOT `readmodel`: nothing here projects an
+            // event, and teselly's topology generator reads this label when it
+            // decides what a module wildcard expands to.
+            unitType = 'command-group';
+            primaryNode = componentNodes[0];
+        }
+        else if (readmodelNodes.length > 0) {
+            // A query pod with routes pinned to it. It stays the READMODEL's unit —
+            // `<module>:<Readmodel>` is the id a topology intent already names and
+            // `--lift` already selects, and letting the fallthrough pick the
+            // alphabetically-first member instead renames that unit after whichever
+            // endpoint joined it (`register*` sorts before most readmodel names). A
+            // pinned route must not be able to rename the pod it asks to live in.
+            unitType = 'readmodel';
+            primaryNode = readmodelNodes[0];
+        }
+        else {
+            // Readmodel that ended up grouped (shouldn't happen, but handle gracefully)
+            unitType = 'readmodel';
+            primaryNode = componentNodes[0];
+        }
+        const primaryModule = primaryNode.module;
+        // `<module>:Endpoints` — stable across a rename of any file in it, unlike
+        // the first endpoint's name the fallthrough would otherwise pick.
+        const unitKey = hasOnlyEndpoints
+            ? `${primaryModule}:Endpoints`
+            : `${primaryModule}:${primaryNode.name}`;
+        // Build artifact entries
+        const artifacts = componentNodes.map(node => {
+            const entry = {
+                name: node.name,
+                type: node.type,
+                filePath: makeRelativePath(node.filePath, serviceRoot),
+                exportName: deriveExportName(node.name, node.type)
+            };
+            // For policies/endpoints, record what they link to
+            if (node.type === 'policy') {
+                const targets = [
+                    ...(node.commandHandlerName ? [node.commandHandlerName] : []),
+                    ...(node.linkedTo || [])
+                ].filter((v, i, a) => a.indexOf(v) === i).sort();
+                if (targets.length > 0) {
+                    entry.linkedTo = targets;
+                }
+            }
+            if (node.type === 'endpoint' && node.linkedTo && node.linkedTo.length > 0) {
+                entry.linkedTo = [...node.linkedTo].sort();
+            }
+            // Any artifact that manually registers routes, not just endpoint ones: a
+            // readmodel file that registers its own routes carries them here, because
+            // it is the artifact the loader brings up and therefore the one whose pod
+            // serves them.
+            //
+            // Sorted: `.deployment-units.json` is committed and drift-watched, so a
+            // list in declaration order reorders whenever a registration moves and
+            // dirties the tree for nothing.
+            if (node.routes && node.routes.length > 0) {
+                entry.routes = [...node.routes].sort();
+            }
+            return entry;
+        });
+        // Sort artifacts: by type priority then by name for determinism
+        const typePriority = {
+            aggregate: 0,
+            externalSystem: 1,
+            policy: 2,
+            endpoint: 3,
+            readmodel: 4
+        };
+        artifacts.sort((a, b) => {
+            const typeDiff = (typePriority[a.type] ?? 99) - (typePriority[b.type] ?? 99);
+            if (typeDiff !== 0)
+                return typeDiff;
+            return a.name.localeCompare(b.name);
+        });
+        // Collect consumed events (informational)
+        const consumes = [];
+        for (const node of componentNodes) {
+            if (node.events) {
+                for (const event of node.events) {
+                    if (!consumes.includes(event)) {
+                        consumes.push(event);
+                    }
+                }
+            }
+        }
+        consumes.sort();
+        const unit = {
+            type: unitType,
+            module: primaryModule,
+            artifacts
+        };
+        if (consumes.length > 0) {
+            unit.consumes = consumes;
+        }
+        units[unitKey] = unit;
+        componentInfos.push({
+            componentNodes,
+            unitKey,
+            type: unitType
+        });
+    }
+    // -----------------------------------------------------------------------
+    // 5. DETECT cross-module merges
+    // -----------------------------------------------------------------------
+    for (const info of componentInfos) {
+        const modules = new Set(info.componentNodes.map(n => n.module));
+        if (modules.size <= 1)
+            continue;
+        // Find which artifact triggered the cross-module merge
+        // This is the artifact that has linkedTo pointing to a different module
+        const triggers = [];
+        for (const node of info.componentNodes) {
+            if (node.type === 'policy' || node.type === 'endpoint') {
+                const targetRefs = [
+                    ...(node.commandHandlerName ? [node.commandHandlerName] : []),
+                    ...(node.linkedTo || [])
+                ];
+                for (const ref of targetRefs) {
+                    // Resolved the way the declarer's own edges were: an endpoint's
+                    // `linkedTo` may name a readmodel, and reading it back through the
+                    // narrow lookup leaves a merge THAT ENDPOINT CAUSED attributed to
+                    // `unknown` — the reason line is the only record of who joined two
+                    // modules.
+                    const resolvedKey = node.type === 'endpoint'
+                        ? resolveEndpointTarget(ref)
+                        : resolveCommandHandler(ref);
+                    const targetNode = resolvedKey ? nodes.get(resolvedKey) : undefined;
+                    if (targetNode && targetNode.module !== node.module) {
+                        triggers.push(node.name);
+                        break;
+                    }
+                }
+            }
+        }
+        // Determine what individual module units would have existed pre-merge
+        const mergedUnitKeys = [];
+        for (const mod of [...modules].sort()) {
+            const moduleAggregates = info.componentNodes
+                .filter(n => n.module === mod && (n.type === 'aggregate' || n.type === 'externalSystem'))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            if (moduleAggregates.length > 0) {
+                mergedUnitKeys.push(`${mod}:${moduleAggregates[0].name}`);
+            }
+        }
+        if (mergedUnitKeys.length > 1) {
+            const resultKey = info.unitKey;
+            const triggerName = triggers.length > 0 ? triggers.sort()[0] : 'unknown';
+            // Find the trigger node by scanning componentNodes (since triggerName is a display name, not a key)
+            const triggerNode = info.componentNodes.find(n => n.name === triggerName);
+            const reason = triggerNode
+                ? `${triggerNode.type} "${triggerName}" links to aggregates in modules: ${[...modules].sort().join(', ')}`
+                : `Cross-module dependency between modules: ${[...modules].sort().join(', ')}`;
+            merges.push({
+                reason,
+                trigger: triggerName,
+                mergedUnits: mergedUnitKeys.sort(),
+                resultUnit: resultKey
+            });
+        }
+    }
+    // Sort merges for determinism
+    merges.sort((a, b) => a.resultUnit.localeCompare(b.resultUnit));
+    // -----------------------------------------------------------------------
+    // 6. VALIDATE: every non-standalone policy is in a component with its target
+    // -----------------------------------------------------------------------
+    for (const [key, node] of nodes) {
+        if (node.type !== 'policy')
+            continue;
+        if (node.isStandalone)
+            continue;
+        const policyRoot = uf.find(key);
+        const targetRefs = [
+            ...(node.commandHandlerName ? [node.commandHandlerName] : []),
+            ...(node.linkedTo || [])
+        ];
+        for (const ref of targetRefs) {
+            const resolvedKey = resolveCommandHandler(ref);
+            if (!resolvedKey)
+                continue; // Already reported in earlier validation
+            const targetRoot = uf.find(resolvedKey);
+            if (policyRoot !== targetRoot) {
+                // This should never happen with union-find (union was applied), but guard defensively
+                throw new Error(`[deployment-units] Internal error: Policy "${node.name}" is not in the same component as its target "${ref}".`);
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Build sorted output
+    // -----------------------------------------------------------------------
+    const sortedUnits = {};
+    for (const key of Object.keys(units).sort()) {
+        sortedUnits[key] = units[key];
+    }
+    return {
+        version: '1.0',
+        generatedAt: new Date().toISOString(),
+        service: serviceName,
+        units: sortedUnits,
+        merges
+    };
+};
+exports.computeMDUs = computeMDUs;
+//# sourceMappingURL=computeMDUs.js.map