@sdd-method/maintain-cli 0.0.0-stage → 0.1.0-rc.0

package/dist/lib/catalogue/aggregate.js

@@ -0,0 +1,2404 @@
+// Catalogue aggregator — `sdd-cli catalogue aggregate`.
+//
+// Implements the 8-step contract in
+// docs/method/methods/catalogue-builder-specification.md
+// §"Aggregator contract":
+//
+//   1. Discover sibling SDDs via aggregation-manifest.yaml.
+//   2. Pull each sibling's catalogues/ (filesystem only in v1).
+//   3. Verify schema-version alignment across SDDs.
+//   4. Concatenate per-catalogue rows.
+//   5. Stamp source_sdd_id on every node-catalogue row.
+//   6. Fail on duplicate primary keys.
+//   7. Run full FK validation including external references.
+//   8. Emit catalogues/ + aggregation-manifest.json.
+//
+// The ecosystem-root SDD itself contributes its own catalogues to the
+// aggregation alongside the siblings — it doesn't list itself in the
+// manifest. That's how single-SDD ecosystems and federated ecosystems
+// share the same code path: with zero siblings the aggregator just
+// re-emits the ecosystem-root's catalogues stamped with source_sdd_id.
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { CLI_VERSION } from "./cli-version.js";
+import { loadAggregationManifest, DEFAULT_AGGREGATION_MANIFEST_REL, } from "./aggregation-manifest-loader.js";
+import { isInRange, loadSddManifest } from "./manifest-loader.js";
+import { SCHEMA_COMPAT } from "./schema-compat.js";
+import { loadCanonicalSchema } from "./schema-loader.js";
+import { readCatalogueCsv, parseCatalogueCsv } from "./csv-reader.js";
+import { writeCatalogue } from "./csv-writer.js";
+import { buildLegacyContractIdMap } from "./contract-id.js";
+import { validatedPopulation, validateWithEngineToLog } from "./engine-validator.js";
+import { PLATFORM_STAMP_COLUMN, isPlatformScopedFk } from "./fk-validator.js";
+import { FindingsLog } from "./findings.js";
+import { readLockFile } from "../lock-file.js";
+import { mergeEdgeLabel } from "./builders/edge-label-merge.js";
+import { isAsyncContractType } from "./builders/product-platform-dependencies.js";
+import { resolveContractPaths } from "./contract-path-resolution.js";
+import { buildRepoEdges } from "./builders/repo-edges.js";
+import { buildCapabilitySpec } from "./builders/capability-spec.js";
+import { buildFeatureGrounding } from "./builders/feature-grounding.js";
+import { loadFeatureGroundingAliases } from "./feature-grounding-aliases-loader.js";
+import { buildFeatureContract } from "./builders/feature-contract.js";
+import { buildCapabilityEvent } from "./builders/event-edges.js";
+import { discoverVocabulary } from "./application-archetype/vocabulary.js";
+import { checkDataPlaneOverlayAtAggregation } from "./application-archetype/expectations.js";
+import { indexServiceArchitectures, readServiceMetadata, } from "./service-architecture-parser.js";
+export async function runCatalogueAggregate(inputs, write) {
+    const sddPath = resolve(inputs.sddPath ?? process.cwd());
+    const findings = new FindingsLog();
+    // 0. Load canonical schema.
+    const schema = await loadCanonicalSchema();
+    write(`sdd-cli catalogue aggregate (canonical schema ${schema.schemaVersion})\n`);
+    // 0a. Load ecosystem-root manifest.
+    const rootManifest = await loadSddManifest(sddPath, {
+        cliVersion: CLI_VERSION,
+    });
+    write(`  root: ${rootManifest.sddId}  profile: ${rootManifest.profile}  tier: ${rootManifest.profile === "organisation-profile" ? "organisation" : "platform"}\n`);
+    // 1. Resolve aggregation-manifest path + load.
+    //
+    // Two anchors, deliberately, because the terms are different KINDS of path:
+    //
+    //  * `inputs.manifestPath` is TYPED BY AN OPERATOR on the command line
+    //    (`--manifest`), so it anchors to the process cwd like every other CLI
+    //    operand. This is ON PURPOSE — do not "fix" it to follow --sdd-path.
+    //  * `aggregationManifestPath` is DECLARED in <sdd-path>/.sdd/sdd-manifest.yaml
+    //    and is documented relative to the SDD root, so it anchors to `sddPath`.
+    //    Anchoring it to cwd was the B3 defect: every real ecosystem root declares
+    //    it (the forward estate declares the default name verbatim), so running
+    //    `aggregate --sdd-path <root>` from anywhere else exited 1 naming a path
+    //    under the CALLER's directory — which reads as the default branch being
+    //    broken, though that branch was always anchored correctly (below, and
+    //    guarded by its own test).
+    const manifestPath = inputs.manifestPath !== undefined
+        ? resolve(inputs.manifestPath)
+        : rootManifest.aggregationManifestPath !== undefined
+            ? resolve(sddPath, rootManifest.aggregationManifestPath)
+            : join(sddPath, DEFAULT_AGGREGATION_MANIFEST_REL);
+    const aggManifest = await loadAggregationManifest(manifestPath, {
+        cliVersion: CLI_VERSION,
+        ecosystemRootPath: sddPath,
+    });
+    if (aggManifest.ecosystemRoot !== rootManifest.sddId) {
+        throw new Error(`aggregation manifest root_sdd_id="${aggManifest.ecosystemRoot}"\n` +
+            `  does not match the owning SDD's sdd_id="${rootManifest.sddId}"\n` +
+            `  (rule: root_sdd_id_consistent, M-ADR 0208 §4.3)\n` +
+            `  (manifest: ${manifestPath})`);
+    }
+    write(`  aggregation manifest: ${relative(sddPath, manifestPath)}\n`);
+    write(`  siblings: ${aggManifest.siblings.length}\n`);
+    // The work queue, reported rather than merely parseable: an audit asking "what is
+    // still pending authoring?" gets it from a normal aggregate run (M-ADR 0195 §4.3).
+    if (aggManifest.pendingMembers.length > 0) {
+        write(`  pending authoring: ${aggManifest.pendingMembers.length}\n`);
+        for (const p of aggManifest.pendingMembers) {
+            write(`    - ${p.sddId}: ${p.reason}${p.blockedOn ? ` [blocked on: ${p.blockedOn}]` : ""}\n`);
+        }
+    }
+    // 2. Pull (filesystem only in v1) — pre-checked at manifest load. Now
+    //    cross-check each sibling's own .sdd/sdd-manifest.yaml + its
+    //    vendored schema vs the aggregator's.
+    const crossCheck = await crossCheckSiblings(sddPath, aggManifest.siblings, schema, write);
+    if (aggManifest.rootFieldDeprecated) {
+        findings.add("convention", `aggregation manifest uses deprecated key \`ecosystem_root\` — rename to \`root_sdd_id\` (M-ADR 0208 §4.3; alias removed at 2.0.0)`);
+    }
+    // M-ADR 0208 §4.2/§4.4: the tier decides the platform_sdd_id fill rule.
+    const rootIsOrganisation = rootManifest.profile === "organisation-profile";
+    // 3. Schema-version alignment was checked in crossCheckSiblings.
+    // 4 + 5. Concatenate per-catalogue rows from the ecosystem-root + every
+    // sibling, stamping source_sdd_id on node catalogues as we go.
+    const rowsByCatalogue = new Map();
+    const perSiblingCounts = new Map();
+    for (const cat of schema.catalogues) {
+        rowsByCatalogue.set(cat.name, []);
+    }
+    perSiblingCounts.set(rootManifest.sddId, await mergeCatalogues(schema, rowsByCatalogue, join(sddPath, "catalogues"), rootManifest.sddId, rootIsOrganisation ? null : rootManifest.sddId));
+    // source_sdd_id -> the platform the §4.4 fill rule assigned it. Kept for the final
+    // pass (fillDerivedPlatformStamps): rows the aggregator itself constructs AFTER the
+    // node loader (0189 adjudication conversions, re-derived edges) set source_sdd_id
+    // explicitly and would otherwise leave platform_sdd_id empty under FK PASS —
+    // the same silent shape as the empty platform leg on cross_sdd_platform_capability.
+    const platformBySource = new Map();
+    if (!rootIsOrganisation)
+        platformBySource.set(rootManifest.sddId, rootManifest.sddId);
+    for (const sib of aggManifest.siblings) {
+        // M-ADR 0208 §4.4 fill rule, by pull path. An empty stamp is UNRESOLVED and is
+        // reported below by checkPlatformKindUniqueness; it is never a key value.
+        let platformSddId;
+        if (!rootIsOrganisation) {
+            platformSddId = rootManifest.sddId; // every row in a platform-tier aggregate belongs to it
+        }
+        else if (sib.level === "organisation") {
+            platformSddId = null; // arrived stamped from the child's own platform-tier run
+        }
+        else {
+            // CATEGORY decides root-ness, not profile: platform-subsystem is platform-profile
+            // too, but it is a MEMBER contained by exactly one platform (M-ADR 0208 §4.1).
+            const sibCategory = crossCheck.siblingCategories.get(sib.sddId);
+            const declared = crossCheck.siblingDeclaredPlatform.get(sib.sddId);
+            if (sibCategory === "platform-root") {
+                platformSddId = sib.sddId; // a platform-root is its own platform
+            }
+            else if (declared !== undefined) {
+                platformSddId = declared; // a member that declares its platform gets it
+            }
+            else {
+                platformSddId = null;
+                findings.add("coverage", `platform_sdd_id: sibling "${sib.sddId}" (${sibCategory ?? crossCheck.siblingProfiles.get(sib.sddId) ?? "?"}) is a MEMBER pulled directly at organisation tier with no declared platform — rows left unstamped (M-ADR 0208 §4.4; federate it under its platform's aggregate, or set platform_sdd_id in its manifest)`);
+            }
+        }
+        if (crossCheck.deprecatedPlatformField.has(sib.sddId)) {
+            findings.add("convention", `sibling "${sib.sddId}" manifest uses deprecated key \`ecosystem_root\` — rename to \`platform_sdd_id\` (M-ADR 0208 §4.3; alias removed at 2.0.0)`);
+        }
+        if (platformSddId !== null)
+            platformBySource.set(sib.sddId, platformSddId);
+        perSiblingCounts.set(sib.sddId, await mergeCatalogues(schema, rowsByCatalogue, sib.cataloguesPath, sib.sddId, platformSddId));
+    }
+    // @rule aggregate-cross-sdd-platform-capability-derivation
+    // 5a. Derive cross_sdd_platform_capability — federated edge, schema 2.9.0.
+    // Joins each consuming SDD's product_platform_dependencies rows against
+    // every platform SDD's capability_service rows on target_service_id ==
+    // capability_service.service_id, emitting one row per resolved
+    // (consuming-product, platform-capability) pair. Per-SDD builders
+    // emit nothing for this catalogue; the aggregator owns it entirely.
+    // See content/plans/v0-9-0-cohort-sweep-derived-bundle.md
+    // §"Cross-SDD platform-capability-edge" + ADR 0134.
+    const crossSddRows = deriveCrossSddPlatformCapability(rowsByCatalogue.get("product_platform_dependencies") ?? [], rowsByCatalogue.get("capability_service") ?? [], findings, rowsByCatalogue.get("capabilities") ?? []);
+    rowsByCatalogue.set("cross_sdd_platform_capability", crossSddRows);
+    // @rule aggregate-feature-integration-support
+    // 5a-di. Derive feature_integration_support (M-ADR 0216 §4.4): supply and demand come from
+    // different SDDs, so coverage is computed only here. The demand-declared fraction is printed
+    // beside the verdicts — a coverage table is only as complete as its demand side (§5).
+    const coverage = deriveFeatureIntegrationSupport(rowsByCatalogue);
+    rowsByCatalogue.set("feature_integration_support", coverage.rows);
+    write(`  data-item coverage (M-ADR 0216): ${coverage.stats.featuresWithRequirements} of ${coverage.stats.features} feature(s) declare a requirement; ` +
+        `${coverage.stats.integrationsWithSupply} of ${coverage.stats.integrations} integration(s) declare supply; ` +
+        `${coverage.rows.length} pair(s): ${Object.entries(coverage.stats.byVerdict).sort().map(([k, v]) => `${k} ${v}`).join(", ") || "none"} ` +
+        `(supported = reaches the canonical boundary, not end to end)\n`);
+    // Every SDD root in this aggregation, by sdd_id: the ecosystem root plus each
+    // sibling. This is precisely what the app tier does not have and cannot obtain.
+    const sddRootsById = new Map([
+        [rootManifest.sddId, sddPath],
+        ...aggManifest.siblings.map((sib) => [sib.sddId, sib.sddRoot]),
+    ]);
+    // The same roots, additionally reachable by DIRECTORY BASENAME. An author who
+    // writes a `platform/<name>/...` contract path is reading that name off the
+    // filesystem, so it is the directory — which is routinely not the sdd_id (one
+    // estate declares `experience-platform` in a directory named
+    // `sdd-experience-platform`). Kept separate from sddRootsById on purpose: the
+    // try-every-root pass must iterate each root ONCE, or a root reachable under two
+    // names would count as two hits and report a false ambiguity.
+    const sddRootAliases = new Map(sddRootsById);
+    for (const root of sddRootsById.values()) {
+        sddRootAliases.set(basename(root), root);
+    }
+    // 5a-quater. M-ADR 0204 §4.2–§4.3: corroborate off-platform rows. Their
+    // external-system id SHOULD match a c4_external_systems entry — WARNING when
+    // it does not, because the C4 surface may legitimately lag discovery, and a
+    // declared FK could only fail. A capability id surviving on such a row (a
+    // member built by a pre-0204 CLI can still carry one) is reported per §4.3.
+    {
+        const extIds = new Set((rowsByCatalogue.get("c4_external_systems") ?? []).map((r) => String(r["id"] ?? "").trim()));
+        let offPlatform = 0;
+        let corroborated = 0;
+        for (const ppd of rowsByCatalogue.get("product_platform_dependencies") ?? []) {
+            const locus = String(ppd["target_locus"] ?? "").trim().toLowerCase();
+            if (locus !== "external" && locus !== "legacy")
+                continue;
+            offPlatform++;
+            const who = `${String(ppd["source_sdd_id"] ?? "")}/${String(ppd["product_id"] ?? "")}`;
+            const extId = String(ppd["target_external_system_id"] ?? "").trim();
+            if (extId !== "" && extIds.has(extId)) {
+                corroborated++;
+            }
+            else if (extId !== "") {
+                findings.add("external", `product_platform_dependencies: ${who} targets ${locus} system "${extId}" with no corroborating c4_external_systems entry (M-ADR 0204 §4.2) — attested by the consumer only`);
+            }
+            else {
+                findings.add("external", `product_platform_dependencies: ${who} declares a ${locus} target with no external-system id — keyed by contract_path only`);
+            }
+            const capLeft = String(ppd["target_capability_id"] ?? "").trim();
+            if (capLeft !== "") {
+                findings.add("convention", `product_platform_dependencies: ${who} carries target_capability_id="${capLeft}" on a ${locus} row — an off-platform target has no platform capability (M-ADR 0204 §4.3)`);
+            }
+        }
+        if (offPlatform > 0) {
+            write(`  off-platform dependencies: ${offPlatform} declared, ${corroborated} corroborated by c4_external_systems\n`);
+        }
+    }
+    // 5a-ter. Resolve every declared contract_path (A2 step 5 / check 3b). The
+    // app-tier gate can only resolve a path against the ONE platform root it was
+    // given, so a contract owned by a sibling SDD is reported as missing when it
+    // exists — a false failure no app-tier fix can reach. Here every SDD root is
+    // present, so the resolution is possible for the first time.
+    //
+    // Findings only, no rows and no rewriting: an ambiguous path is reported and
+    // left alone rather than resolved to a guess.
+    const contractPathSummary = await resolveContractPaths(rowsByCatalogue.get("product_platform_dependencies") ?? [], sddRootsById, sddRootAliases, fileExists, findings);
+    // Stated, not merely computed. "0 unresolved" and "nothing was resolvable" are
+    // different results and must not print the same (M-ADR 0200 §4.3).
+    {
+        const c = contractPathSummary;
+        const declared = c.resolved + c.missing + c.ambiguous + c.nonPath;
+        write(`  contract paths: ${c.resolved} of ${declared} declared resolved` +
+            ` (${c.missing} missing, ${c.ambiguous} ambiguous, ${c.nonPath} not a path;` +
+            ` ${c.absent} dependency(ies) declare none) across ${sddRootsById.size} SDD root(s)\n`);
+    }
+    // 5a-bis. M-ADR 0198: re-derive the derived edges whose join can legitimately span
+    // sibling SDDs, over the merged rows above. Concatenation alone cannot produce a
+    // cross-SDD row for these — neither member holds both join inputs, so neither computes
+    // it, and appending finished per-member joins never creates a row no input produced.
+    //
+    // §4.1's rule (a catalogue qualifies when it is derived AND at least one join input can
+    // carry a cross-SDD reference) selects five: feature_repo, repo_capability, repo_contract,
+    // feature_contract, capability_event. One shared mechanism (rederiveAppend below) runs
+    // all five so a sixth qualifying catalogue is a new call, not new merge logic.
+    //
+    // feature_repo moved into scope under §4.1's "automatic movement" clause: its derived leg
+    // resolves free-text evidence tokens (M-ADR 0143 §4.4) against `repositories.id`, and the
+    // merged repositories table carries every sibling's repos — a platform spec that names a
+    // repo registered by a MEMBER SDD can only resolve here. The spec text is not a catalogue,
+    // so the derived leg is re-run the way §4.2 describes for every builder: the two feature
+    // extractors are invoked over each manifest-read contributor's docs with the MERGED
+    // repository / service / capability id sets as their resolution inputs. Only their
+    // feature_repo output is kept; feature rows and their per-row findings were already
+    // emitted at member tier and are not repeated. level:organisation siblings expose no docs
+    // (pre-built catalogues-aggregated/ only) and are skipped — their rows arrived from their
+    // own platform-tier run, where this pass has already happened.
+    //
+    // §4.2: only the derived leg is re-run — each builder is invoked with its authored-leg
+    // inputs (configs / manifests) empty, which runs zero iterations of that path and yields
+    // the derived rows alone; the authored rows are already correct via concatenation and are
+    // left untouched. §4.2/§4.3: rederiveAppend adds the result to what concatenation already
+    // produced, keeping the concatenated row on any primary-key collision — never a replace.
+    {
+        const mergedRepoIds = new Set((rowsByCatalogue.get("repositories") ?? []).map((r) => String(r["id"])));
+        const mergedServiceIds = new Set((rowsByCatalogue.get("services") ?? []).map((r) => String(r["id"])));
+        const mergedCapabilityIds = new Set((rowsByCatalogue.get("capabilities") ?? []).map((r) => String(r["id"])));
+        const mergedFeatureIds = new Set((rowsByCatalogue.get("features") ?? []).map((r) => String(r["id"])));
+        // Re-derivation FILLS ABSENCES; it does not widen. A feature its own member
+        // build already anchored keeps exactly those anchors: re-running bare-token
+        // resolution against every sibling's repo ids over an already-resolved row
+        // mostly finds collisions (measured on one estate: 13 of the 43 rows it would
+        // have added to anchored features resolved to repo ids like `web`, `proxy`,
+        // `service`, `batch` owned by unrelated SDDs; of the 261 rows added to
+        // UNANCHORED features, 4 did). The motivating case — and §4.1's clause — is a
+        // row no member could produce, which is exactly an unanchored feature.
+        const anchoredFeatureIds = new Set((rowsByCatalogue.get("feature_repo") ?? []).map((r) => String(r["feature_id"])));
+        const contributors = [
+            { sddPath, profile: rootManifest.profile, sddId: rootManifest.sddId },
+        ];
+        for (const sib of aggManifest.siblings) {
+            if (sib.level === "organisation")
+                continue;
+            const profile = crossCheck.siblingProfiles.get(sib.sddId);
+            if (profile === undefined)
+                continue;
+            contributors.push({ sddPath: sib.sddRoot, profile, sddId: sib.sddId });
+        }
+        const rederivedFeatureRepo = [];
+        // Both extractors, over several contributors, can yield the same edge (the same
+        // feature grounded in the same repo from two tables); rederiveAppend dedups only
+        // against the CONCATENATED rows, so dedup the re-derived set itself here or the
+        // duplicate-PK check fails the aggregate on two copies of one correct fact.
+        const rederivedIds = new Set();
+        const scratch = new FindingsLog(); // member-tier findings already emitted; not repeated
+        for (const c of contributors) {
+            const aliases = await loadFeatureGroundingAliases(c.sddPath);
+            const common = {
+                sddPath: c.sddPath,
+                findings: scratch,
+                profile: c.profile,
+                productId: c.sddId,
+                knownCapabilityIds: mergedCapabilityIds,
+                knownServiceIds: mergedServiceIds,
+                knownRepoKeys: mergedRepoIds,
+                // Against every sibling's ids a prose word collides with a repo that happens to be
+                // named like it ("templates"); here only identifier-shaped tokens name a repo.
+                repoTokenPolicy: "identifier",
+                existingFeatureIds: new Set(),
+                aliases,
+            };
+            const [grounding, spec] = await Promise.all([
+                buildFeatureGrounding(common),
+                buildCapabilitySpec(common),
+            ]);
+            for (const fr of [...grounding.featureRepoRows, ...spec.featureRepoRows]) {
+                const featureId = String(fr["feature_id"] ?? "");
+                if (!mergedFeatureIds.has(featureId))
+                    continue;
+                if (anchoredFeatureIds.has(featureId))
+                    continue;
+                const id = String(fr["id"] ?? "");
+                if (id === "" || rederivedIds.has(id))
+                    continue;
+                rederivedIds.add(id);
+                rederivedFeatureRepo.push(fr);
+            }
+        }
+        const before = (rowsByCatalogue.get("feature_repo") ?? []).length;
+        rederiveAppend(rowsByCatalogue, "feature_repo", rederivedFeatureRepo);
+        const added = (rowsByCatalogue.get("feature_repo") ?? []).length - before;
+        if (added > 0) {
+            findings.add("coverage", `feature_repo: ${added} row(s) re-derived at aggregate tier for features that had NO anchor at member tier — evidence tokens naming a repo registered by another contributor resolve only against the merged repositories; already-anchored features are not widened (M-ADR 0198 §4.1 as amended; ${contributors.length} contributor doc trees scanned)`);
+        }
+    }
+    const repoEdges = buildRepoEdges({
+        findings,
+        configs: [],
+        capabilityIdByPath: new Map(),
+        contractIdByPath: new Map(),
+        serviceRows: rowsByCatalogue.get("services") ?? [],
+        capabilityServiceRows: rowsByCatalogue.get("capability_service") ?? [],
+        serviceContractRows: rowsByCatalogue.get("service_contract") ?? [],
+        capabilityFeatureRows: rowsByCatalogue.get("capability_feature") ?? [],
+        featureRepoRows: rowsByCatalogue.get("feature_repo") ?? [],
+    });
+    rederiveAppend(rowsByCatalogue, "repo_capability", repoEdges.repoCapability);
+    rederiveAppend(rowsByCatalogue, "repo_contract", repoEdges.repoContract);
+    const featureContractRows = buildFeatureContract({
+        findings,
+        capabilityFeatureRows: rowsByCatalogue.get("capability_feature") ?? [],
+        capabilityContractRows: rowsByCatalogue.get("capability_contract") ?? [],
+        featureServiceRows: rowsByCatalogue.get("feature_service") ?? [],
+        serviceContractRows: rowsByCatalogue.get("service_contract") ?? [],
+    });
+    rederiveAppend(rowsByCatalogue, "feature_contract", featureContractRows);
+    const capabilityEventRows = buildCapabilityEvent({
+        findings,
+        manifests: [],
+        knownCapabilityIds: new Set((rowsByCatalogue.get("capabilities") ?? []).map((r) => String(r["id"]))),
+        knownEventIds: new Set((rowsByCatalogue.get("events") ?? []).map((r) => String(r["id"]))),
+        capabilityServiceRows: rowsByCatalogue.get("capability_service") ?? [],
+        serviceEventRows: rowsByCatalogue.get("service_event") ?? [],
+    });
+    rederiveAppend(rowsByCatalogue, "capability_event", capabilityEventRows);
+    // 5a-iii. Archetype data-plane expectations overlay (M-ADR 0191 §4.3) — the
+    // deviation-visible WARN + conformance surface, run at AGGREGATION tier where
+    // the reference-architecture bundle's `expected_bindings` resolve (the
+    // ecosystem-root repo caches it). Per-SDD builds deliberately do not run this
+    // — an app SDD may consume an adopter context-pack, not the RA bundle.
+    checkDataPlaneOverlayAtAggregation({
+        products: rowsByCatalogue.get("products") ?? [],
+        bindings: rowsByCatalogue.get("application_data_plane_bindings") ?? [],
+        deviations: rowsByCatalogue.get("application_data_plane_deviations") ?? [],
+        conformanceCoverage: rowsByCatalogue.get("application_conformance_coverage") ?? [],
+        vocab: await discoverVocabulary(sddPath),
+        findings,
+    });
+    // 5a-ii. Resolve cross-SDD screen_feature edges (schema 2.24.0, R3). App/
+    // integration builds emit screen_feature rows carrying the bare `realises:`
+    // slug when the feature lives in another SDD (the platform). Rewrite those
+    // to the resolved platform feature id by matching the slug against every
+    // merged feature's slug. One slug vocabulary per capability (ADR 0177), so
+    // a single match is authoritative; an ambiguous estate-wide match is refused
+    // with a divergence finding (never guessed); no match is an orphan finding.
+    rowsByCatalogue.set("screen_feature", resolveCrossSddScreenFeature(rowsByCatalogue.get("screen_feature") ?? [], rowsByCatalogue.get("features") ?? [], findings));
+    // @rule aggregate-external-system-dedup
+    // 5b. Dedup c4_external_systems by id (ADR 0155). External systems are
+    // inherently shared references — the same external (e.g. ext-google-maps)
+    // may be declared by multiple SDDs. This is the one narrowly-scoped
+    // exception to the duplicate-PK rule: identical rows merge (first-seen
+    // wins); conflicting attributes on the same id surface as a finding.
+    dedupExternalSystems(rowsByCatalogue, findings);
+    // @rule aggregate-external-exemption-dedup
+    // 5b-i-bis. Dedup external_system_exemption by PK (M-ADR 0189 §4.6) —
+    // shared external entities may be exempted by multiple SDDs; identical
+    // assertions merge, conflicting ones keep first-seen with a finding.
+    dedupExternalExemptions(rowsByCatalogue, findings);
+    // 5b-ii. Dedup method-scoped ADRs by id. ADRs under docs/method/adr/ are the
+    // shared method baseline — byte-identical across every method-based SDD. When
+    // two or more full SDDs federate (e.g. a second platform-root joins the org
+    // tier alongside an existing one), each contributes the same method ADR ids. Merge
+    // them (first-seen wins) rather than failing the duplicate-PK check. Platform
+    // / domain ADRs are NOT deduped — a collision there is a genuine error.
+    await dedupMethodScopedAdrs(rowsByCatalogue, findings, sddRootsById);
+    // @rule aggregate-federated-reverse-metadata-enrichment
+    // 5c. Federated reverse-metadata enrichment (ADR 0163 P2). Both reference
+    // adopters centralise the service inventory in the platform-root, but for
+    // reverse-method federations the per-service evidence (service-architecture.md)
+    // lives one federation hop away, in member SDDs. The platform-root's own
+    // build can't see those docs, so those service rows carry empty reverse
+    // metadata. Here — the one place that can reach every member's repos/ —
+    // fill ONLY the empty reverse columns from each member's arch doc.
+    // Fill-if-empty: platform-root-local metadata always wins, order-independent
+    // across members. Cross-member slug ambiguity is refused, not guessed.
+    await enrichFederatedServiceMetadata(rowsByCatalogue, aggManifest.siblings, findings);
+    // @rule aggregate-successor-orphan
+    // 5d. Successor-reference orphan check (schema 2.22.0). products.successor_sdd_id
+    // is a soft reference in sdd_id vocabulary — resolve against the sdd_ids
+    // visible at this tier (direct contributors plus source_sdd_ids stamped at a
+    // lower tier, so org-tier re-aggregation sees through cohort roots). A miss
+    // is a finding, never a failure: the successor may live outside this
+    // aggregation's scope.
+    checkSuccessorReferences(rowsByCatalogue.get("products") ?? [], new Set(perSiblingCounts.keys()), findings);
+    // @rule aggregate-sibling-identity-duplicate
+    // 5e. Sibling-identity duplicate check (M-ADR 0189 §4.5.3): c4_systems
+    // rows sharing name+description — the syndicated-L1 overwrite class that
+    // PK/FK gates cannot see (the id is right, every other column is wrong).
+    checkDuplicateSystemIdentity(rowsByCatalogue.get("c4_systems") ?? [], findings);
+    // @rule aggregate-external-system-adjudication
+    // 5f. M-ADR 0189 §4.4 — adjudicate external-system candidates against the
+    // merged estate: internal-system resolutions convert to
+    // system_system_dependency; container resolutions are tier-contradiction
+    // findings; integration-kind resolutions are provider-pair collisions and
+    // stay external. Runs before the dup-PK/FK gates so the rewritten rows
+    // are what gets validated and emitted.
+    const adjudication = adjudicateExternalSystems(rowsByCatalogue, findings);
+    write(`  adjudication (M-ADR 0189 §4.4): ${adjudication.converted} candidates → internal ` +
+        `(${adjudication.edgesRewritten} edges → system_system_dependency), ` +
+        `${adjudication.providerPairsKept} provider pairs kept external, ` +
+        `${adjudication.uncorroboratedKept} uncorroborated holds, ` +
+        `${adjudication.uncertainHolds} uncertain holds, ` +
+        `${adjudication.ambiguousHolds} ambiguous holds, ` +
+        `${adjudication.tierContradictions} tier contradictions asserted, ` +
+        `${adjudication.containerConverted} container conversions (${adjudication.containerEdgesRewritten} edges → container_dependency, ` +
+        `${adjudication.systemFallbackEdges} stuck edges → system_system_dependency at L1), ` +
+        `${adjudication.exempted} exempted, ${adjudication.unverified} unverified\n`);
+    // 5f-bis. Rows constructed at THIS tier after the node loader (adjudication
+    // conversions, re-derived edges) carry source_sdd_id but no platform stamp.
+    // Fill them now that every derivation has run (M-ADR 0208 §4.4 as applied to
+    // aggregator-constructed rows); whatever stays empty is reported, never keyed on.
+    fillDerivedPlatformStamps(schema, rowsByCatalogue, platformBySource, findings);
+    // @rule aggregate-platform-kind-uniqueness
+    // 5g. Platform-kind uniqueness (M-ADR 0133 §4.2c open hygiene).
+    checkPlatformKindUniqueness(rowsByCatalogue.get("c4_systems") ?? [], findings, rootIsOrganisation ? "organisation" : "platform");
+    // @rule aggregate-contract-id-rekey
+    // 5h. M-ADR 0203 §4.4 cross-SDD re-key: the contract-id migration derives
+    // per-SDD, but contract-FK edges cross SDD boundaries — a federated SDD
+    // that owns no contracts has an empty map, so its references keep the 2.x
+    // kindless ids (measured on the first rehearsal probe: 170 dangling FKs
+    // over 6 old ids). This tier sees every contract row, so the old form is
+    // decidable here and nowhere earlier.
+    const contractRekey = rekeyLegacyContractRefs(schema, rowsByCatalogue, findings);
+    // Always emitted: an absent line is indistinguishable from a check that
+    // never ran (M-ADR 0200 §4.3 — a zero must be affirmable). Measured: the
+    // first all-zero estate correctly refused to report "0" for a line that
+    // was never printed.
+    write(`  contract-id cut window (M-ADR 0203 §4.4): ${contractRekey.rekeyed} cross-SDD reference(s) re-keyed, ` +
+        `${contractRekey.deduped} duplicate fact(s) dropped, ${contractRekey.ambiguous} ambiguous left dangling\n`);
+    // @rule aggregate-duplicate-primary-key
+    // 6. Duplicate primary key check. M-ADR 0208 §4.4 (F-D): at organisation
+    // tier the key of `domains` is (platform_sdd_id, id) — two platforms may
+    // each own `identity`. Everywhere else, and for every other catalogue,
+    // the scalar pk. An empty stamp is unresolved, never a key.
+    const platformScopedTargets = rootIsOrganisation ? PLATFORM_SCOPED_AT_ORGANISATION : [];
+    const duplicates = findDuplicatePrimaryKeys(schema, rowsByCatalogue, platformScopedTargets);
+    if (duplicates.length > 0) {
+        write(`\nDuplicate primary keys (${duplicates.length}) — aggregation fails:\n`);
+        for (const d of duplicates) {
+            write(`  ${d.catalogue}.${d.primaryKey}="${d.value}" contributed by [${d.sources.join(", ")}]\n`);
+        }
+        return finalise({
+            schema,
+            ecosystemRoot: rootManifest.sddId,
+            aggManifest,
+            rowsByCatalogue,
+            perSiblingCounts,
+            aggregatedFkPass: false,
+            findings,
+            outDir: resolveOutDir(sddPath, inputs.outDir),
+            manifestPath,
+            writeOutputs: false,
+            duplicateCount: duplicates.length,
+            write,
+            strict: inputs.strict === true,
+        });
+    }
+    // 7. Full FK validation, treating external as internal.
+    const { fk: fkRaw } = await validateWithEngineToLog(schema, rowsByCatalogue, findings, { treatExternalAsInternal: true, platformScopedTargets }, 
+    // The aggregation tier has never emitted enum findings; the cutover
+    // changes no tier's finding surface (M-ADR 0205 §4.4).
+    { logEnumFindings: false });
+    // @rule aggregate-tier-aware-external-deferral
+    // 7a. Tier-aware external resolution (M-ADR 0134 §4.3 as read under M-ADR
+    // 0208's organisation tier). 0134 wrote "the aggregator validates external
+    // FKs after merge" for a world with ONE aggregate. With an organisation tier
+    // above the platform-roots, a platform-root's OWN dependency on something it
+    // does not own — a row SOURCED BY THE ROOT ITSELF whose external FK dangles
+    // at its own platform-tier aggregate — is a cross-platform dependency by
+    // construction: no sibling at this tier can hold the target, and the tier
+    // that can is the organisation root. Such a row is deferred there as an
+    // `external` finding, not failed here. Rows sourced by MEMBERS still fail:
+    // their targets are the platform's own and are supposed to be present. At
+    // organisation tier nothing is deferred — there is no tier above.
+    // Measured shape: a packaged-SaaS platform-root depending on three of the
+    // reference platform's capabilities through two of its services — 4 dangling
+    // at its own aggregate, all present at the organisation root.
+    const fk = rootIsOrganisation
+        ? fkRaw
+        : deferRootSourcedCrossPlatformExternals(schema, rowsByCatalogue, fkRaw, rootManifest.sddId, findings, write);
+    // 7b. M-ADR 0208 §4.4 (F-D): report the domain-key state at organisation
+    // tier. Always emitted there — an absent line is indistinguishable from a
+    // check that never ran (M-ADR 0200 §4.3).
+    if (rootIsOrganisation) {
+        checkPlatformScopedKeyAmbiguity(schema, rowsByCatalogue, platformScopedTargets, findings, write);
+    }
+    // 8. Emit aggregated catalogues + aggregation-manifest.json.
+    const outDir = resolveOutDir(sddPath, inputs.outDir);
+    const rowCounts = new Map();
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        const result = await writeCatalogue({ outDir, catalogue: cat, rows });
+        rowCounts.set(cat.name, result.rowCount);
+        // A preserved file is data this build could not reproduce. Saying nothing
+        // would move the silence rather than close it: the previous behaviour was
+        // also silent, and that is why 26 SDDs lost their conformance evidence
+        // while their registries went on citing it.
+        if (result.preserved) {
+            findings.add("convention", `catalogues/${cat.name}.csv: this build produced NO rows for it, and the file on disk ` +
+                `holds ${result.preservedRows}. The existing file was LEFT UNTOUCHED rather than ` +
+                `replaced with a bare header. Either the catalogue has no producer in this CLI — in ` +
+                `which case its rows are authored data, not build output, and nothing here will ever ` +
+                `regenerate them — or a builder that used to emit rows has stopped. Both are worth ` +
+                `resolving; neither is worth deleting the rows over.`);
+        }
+    }
+    await writeAggregationManifestJson({
+        outDir,
+        schemaVersion: schema.schemaVersion,
+        ecosystemRoot: rootManifest.sddId,
+        siblings: aggManifest.siblings,
+        perSiblingCounts,
+        aggregatedRowCounts: rowCounts,
+        cliVersion: CLI_VERSION,
+    });
+    // Report.
+    write("\nAggregated row counts:\n");
+    for (const [name, count] of rowCounts) {
+        if (count > 0)
+            write(`  ${name}: ${count}\n`);
+    }
+    const emptyCount = [...rowCounts.values()].filter((c) => c === 0).length;
+    write(`  (${emptyCount} headers-only)\n`);
+    const findingsText = findings.render();
+    if (findingsText)
+        write(`\n${findingsText}\n`);
+    if (fk.internalPass) {
+        write(`\nAggregated FK validation: PASS (${validatedPopulation(rowsByCatalogue)})\n`);
+    }
+    else {
+        write(`\nAggregated FK validation: FAIL (${fk.internalFailures.length} dangling)\n`);
+        for (const f of fk.internalFailures) {
+            const sourceSdd = findSourceSdd(rowsByCatalogue, f.catalogue, f.referencingRow);
+            write(`  ${f.catalogue}.${f.column}: row pk=${f.referencingRow} → ${f.target}=${f.value || "<empty>"}` +
+                (sourceSdd ? ` (from ${sourceSdd})\n` : "\n"));
+        }
+    }
+    const strictFail = inputs.strict === true && findings.count() > 0;
+    const exitCode = !fk.internalPass || strictFail ? 1 : 0;
+    return {
+        exitCode,
+        schemaVersion: schema.schemaVersion,
+        ecosystemRoot: rootManifest.sddId,
+        siblingCount: aggManifest.siblings.length,
+        rowCounts,
+        perSiblingCounts,
+        aggregatedFkPass: fk.internalPass,
+        findingsCount: findings.count(),
+        outDir,
+    };
+}
+// ADR 0155: c4_external_systems rows dedup by id across SDDs rather than
+// failing the duplicate-PK check. First-seen row wins; a `source_sdd_id`
+// already stamped is preserved. Conflicting name/technology/description on
+// the same id emits a `convention` finding so authors can reconcile.
+function dedupExternalExemptions(rowsByCatalogue, findings) {
+    const rows = rowsByCatalogue.get("external_system_exemption");
+    if (rows === undefined || rows.length === 0)
+        return;
+    const byId = new Map();
+    for (const row of rows) {
+        const id = String(row["id"] ?? "");
+        if (id === "")
+            continue;
+        const existing = byId.get(id);
+        if (existing === undefined) {
+            byId.set(id, row);
+            continue;
+        }
+        if (String(existing["reason"]) !== String(row["reason"]) ||
+            String(existing["note"]) !== String(row["note"])) {
+            findings.add("convention", `external_system_exemption: "${id}" asserted with conflicting reason/note across SDDs — first-seen kept`);
+        }
+    }
+    rowsByCatalogue.set("external_system_exemption", [...byId.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"]))));
+}
+// M-ADR 0198 §4.2/§4.3: append a re-derived catalogue's rows to whatever concatenation
+// already produced for it, keeping the concatenated row on any primary-key collision. One
+// shared mechanism for every re-derived catalogue, so adding a fifth is a call to this
+// function with that catalogue's builder output, not new merge logic.
+function rederiveAppend(rowsByCatalogue, catalogueName, rederivedRows) {
+    const concatenated = rowsByCatalogue.get(catalogueName) ?? [];
+    const existingIds = new Set(concatenated.map((r) => String(r["id"])));
+    const added = rederivedRows.filter((r) => !existingIds.has(String(r["id"])));
+    rowsByCatalogue.set(catalogueName, [...concatenated, ...added]);
+}
+export function dedupExternalSystems(rowsByCatalogue, findings) {
+    const rows = rowsByCatalogue.get("c4_external_systems");
+    if (rows === undefined || rows.length === 0)
+        return;
+    const byId = new Map();
+    const namesById = new Map();
+    for (const row of rows) {
+        const id = String(row["id"] ?? "");
+        if (id === "")
+            continue;
+        const name = String(row["name"] ?? "");
+        const names = namesById.get(id);
+        if (names) {
+            if (name !== "" && !names.includes(name))
+                names.push(name);
+        }
+        else {
+            namesById.set(id, name === "" ? [] : [name]);
+        }
+        const existing = byId.get(id);
+        if (existing === undefined) {
+            byId.set(id, row);
+            continue;
+        }
+        for (const attr of ["technology", "description"]) {
+            const a = String(existing[attr] ?? "");
+            const b = String(row[attr] ?? "");
+            if (a !== "" && b !== "" && a !== b) {
+                findings.add("convention", `c4_external_systems: id "${id}" has conflicting ${attr} across SDDs [${String(existing["source_sdd_id"] ?? "?")}, ${String(row["source_sdd_id"] ?? "?")}] — first-seen kept`);
+            }
+        }
+    }
+    // M-ADR 0203 §4.2's second fallout detector — the mirror image of the
+    // same-name split. With identity now the DECLARED entry id, a generic
+    // diagram-local mnemonic shared across SDDs merges DIFFERENT real-world
+    // systems into one row (measured before this shipped: 17 integration
+    // SDDs each declaring their provider under one shared mnemonic — 17
+    // providers, one surviving row). A merge whose display names corroborate
+    // (compact-equal or token-subset — benign label variance on one
+    // referent) stays the quiet dedup this catalogue is designed for; a
+    // merge whose names DON'T corroborate is likely N referents under one
+    // entry id, and every hidden referent is named. Rename the diagram entry
+    // ids apart — a diagram edit, the M-ADR 0189 §4.2 sanctioned opt-out.
+    const compactName = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const nameTokens = (s) => new Set(s
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t !== ""));
+    const namesCorroborate = (a, b) => {
+        if (compactName(a) === compactName(b))
+            return true;
+        const ta = nameTokens(a);
+        const tb = nameTokens(b);
+        const subset = (x, y) => x.size > 0 && [...x].every((t) => y.has(t));
+        return subset(ta, tb) || subset(tb, ta);
+    };
+    for (const [id, names] of namesById) {
+        if (names.length < 2)
+            continue;
+        const anchor = names[0];
+        const strangers = names.slice(1).filter((n) => !namesCorroborate(anchor, n));
+        if (strangers.length === 0) {
+            // Corroborating label variance — keep the plain per-attr conflict
+            // shape the pre-3.0.0 dedup reported.
+            findings.add("convention", `c4_external_systems: id "${id}" has conflicting name across SDDs [${names.join(", ")}] — first-seen kept`);
+            continue;
+        }
+        findings.add("divergence", `c4_external_systems: declared id "${id}" merges ${names.length} rows whose display names do not corroborate ` +
+            `[${names.join(" | ")}] — likely DIFFERENT systems under one shared diagram entry id; ` +
+            `first-seen kept and ${names.length - 1} referent(s) are hidden by this merge. ` +
+            `Rename the diagram entry ids apart (M-ADR 0203 §4.2 / M-ADR 0189 §4.2)`);
+    }
+    rowsByCatalogue.set("c4_external_systems", [...byId.values()]);
+}
+// Method-DISTRIBUTED ADRs are the shared method baseline, identical across
+// method-based SDDs. Dedupe by id (first-seen wins), preserving order and leaving
+// adopter-AUTHORED platform/domain ADRs untouched — a collision there is a genuine
+// error and MUST still fail the duplicate-PK check. Mirrors dedupExternalSystems.
+//
+// WHAT COUNTS AS METHOD-DISTRIBUTED (M-ADR 0208 / gov F-E): a row whose doc_path is
+// BUNDLE-MANAGED in the contributing SDD's method-baseline.lock. Provenance, not
+// path prefix. The earlier test `startsWith("docs/method/adr/")` was a proxy for
+// the same property and it failed the first time two platform-roots aggregated:
+// the baseline also distributes docs/method/platform-adr/ (13 ADR-emitting files
+// in platform-baseline v2.3.28), which the prefix missed, so identical
+// bundle-managed rows from two roots collided as if adopter-authored. A prefix
+// extension would have passed every test available that day and merged genuinely
+// authored platform ADRs the next time an adopter wrote a colliding one; the lock
+// already records exactly the property we mean.
+//
+// FALLBACK: a contributing SDD with no lock (fixtures; a repo that has never been
+// synced) keeps the historical prefix test, so it is never LESS deduped than before.
+// @rule aggregate-method-adr-dedup
+async function dedupMethodScopedAdrs(rowsByCatalogue, findings, sddRootsById) {
+    const rows = rowsByCatalogue.get("adrs");
+    if (rows === undefined || rows.length === 0)
+        return;
+    // source_sdd_id -> set of bundle-managed paths, or null when that SDD has no lock.
+    const managedBySdd = new Map();
+    for (const [sddId, root] of sddRootsById) {
+        const lock = await readLockFile(root);
+        if (lock === null) {
+            managedBySdd.set(sddId, null);
+            continue;
+        }
+        const managed = new Set();
+        for (const b of lock.bundles)
+            for (const mp of b.managedPaths)
+                managed.add(mp);
+        managedBySdd.set(sddId, managed);
+    }
+    const isMethodDistributed = (row) => {
+        const docPath = String(row["doc_path"] ?? "");
+        if (docPath === "")
+            return false;
+        const managed = managedBySdd.get(String(row["source_sdd_id"] ?? ""));
+        if (managed === undefined || managed === null) {
+            // No lock for this contributor: historical prefix test.
+            return docPath.startsWith("docs/method/adr/");
+        }
+        return managed.has(docPath);
+    };
+    const seen = new Map();
+    const out = [];
+    for (const row of rows) {
+        const id = String(row["id"] ?? "");
+        if (!isMethodDistributed(row) || id === "") {
+            out.push(row);
+            continue;
+        }
+        const existing = seen.get(id);
+        if (existing === undefined) {
+            seen.set(id, row);
+            out.push(row);
+            continue;
+        }
+        for (const attr of ["title", "status"]) {
+            const a = String(existing[attr] ?? "");
+            const b = String(row[attr] ?? "");
+            if (a !== "" && b !== "" && a !== b) {
+                findings.add("convention", `adrs: method-distributed id "${id}" has conflicting ${attr} across SDDs [${String(existing["source_sdd_id"] ?? "?")}, ${String(row["source_sdd_id"] ?? "?")}] — first-seen kept`);
+            }
+        }
+        // duplicate method-distributed ADR — already kept first-seen; drop this copy.
+    }
+    rowsByCatalogue.set("adrs", out);
+}
+// ADR 0163 P2: the reverse-derived metadata columns that a member SDD's
+// service-architecture.md can backfill onto a platform-root service row.
+const FEDERATED_META_COLS = [
+    "runtime_type",
+    "language",
+    "status",
+    "confidence",
+    "description",
+];
+/**
+ * Backfill empty reverse-metadata columns on the aggregated `services`
+ * rows from member SDDs' `service-architecture.md` docs.
+ *
+ * Mechanism (Option 1 per the coordination analysis — no schema change):
+ * the aggregator already knows each sibling's repo root (`sib.sddRoot`),
+ * so it indexes `<sddRoot>/repos/**​/docs/service-architecture.md` per
+ * member and matches by repo slug == service id. Only cells that are empty
+ * after the per-SDD builds are filled (platform-root-local metadata is never
+ * overwritten), so the pass is idempotent and order-independent.
+ *
+ * Safety: a slug whose arch doc exists in more than one member is
+ * **ambiguous** — we cannot know which doc describes the single inventory
+ * row — so it is skipped with a finding rather than guessed.
+ */
+async function enrichFederatedServiceMetadata(rowsByCatalogue, siblings, findings) {
+    const services = rowsByCatalogue.get("services");
+    if (services === undefined || services.length === 0)
+        return;
+    const hasEmptyCell = (row) => FEDERATED_META_COLS.some((c) => String(row[c] ?? "") === "");
+    // Service ids that still want metadata after the per-SDD builds.
+    const needed = new Set();
+    for (const row of services) {
+        if (!hasEmptyCell(row))
+            continue;
+        const id = String(row["id"] ?? "");
+        if (id !== "")
+            needed.add(id);
+    }
+    if (needed.size === 0)
+        return;
+    // Index each member's arch docs, but keep only slugs we actually need.
+    // A slug → the members whose repos/ carry an arch doc for it (collision
+    // detection lives in the >1 case below).
+    const bySlug = new Map();
+    for (const sib of siblings) {
+        let index;
+        try {
+            index = await indexServiceArchitectures(sib.sddRoot);
+        }
+        catch {
+            continue; // member without a repos/ tree contributes nothing
+        }
+        for (const [slug, archPath] of index) {
+            if (!needed.has(slug))
+                continue;
+            const list = bySlug.get(slug) ?? [];
+            list.push({ sddId: sib.sddId, archPath });
+            bySlug.set(slug, list);
+        }
+    }
+    if (bySlug.size === 0)
+        return;
+    const metaCache = new Map();
+    const enrichingMembers = new Set();
+    let rowsEnriched = 0;
+    let cellsFilled = 0;
+    const enriched = [];
+    for (const row of services) {
+        const id = String(row["id"] ?? "");
+        const members = id !== "" ? bySlug.get(id) : undefined;
+        if (members === undefined || !hasEmptyCell(row)) {
+            enriched.push(row);
+            continue;
+        }
+        if (members.length > 1) {
+            findings.add("convention", `services: federated metadata for "${id}" is ambiguous — ` +
+                `service-architecture.md exists in ${members.length} member SDDs ` +
+                `[${members.map((m) => m.sddId).join(", ")}]; enrichment skipped`);
+            enriched.push(row);
+            continue;
+        }
+        const { sddId, archPath } = members[0];
+        let meta = metaCache.get(archPath);
+        if (meta === undefined) {
+            meta = await readServiceMetadata(archPath);
+            metaCache.set(archPath, meta);
+        }
+        const next = {
+            ...row,
+        };
+        let filledThisRow = false;
+        for (const col of FEDERATED_META_COLS) {
+            if (String(row[col] ?? "") === "" && meta[col] !== "") {
+                next[col] = meta[col];
+                cellsFilled++;
+                filledThisRow = true;
+            }
+        }
+        if (filledThisRow) {
+            rowsEnriched++;
+            enrichingMembers.add(sddId);
+        }
+        enriched.push(filledThisRow ? next : row);
+    }
+    if (rowsEnriched > 0) {
+        const stillEmpty = enriched.filter(hasEmptyCell).length;
+        findings.add("coverage", `services: federated reverse-metadata enrichment filled ${cellsFilled} ` +
+            `empty cell(s) across ${rowsEnriched} service row(s) from ` +
+            `${enrichingMembers.size} member SDD(s); ${stillEmpty} row(s) still ` +
+            `carry empty reverse metadata`);
+        rowsByCatalogue.set("services", enriched);
+    }
+}
+/**
+ * M-ADR 0208 §4.4: the catalogues whose organisation-tier key is
+ * `(platform_sdd_id, <pk>)`. Only `domains` — a domain is a bounded context
+ * OF a platform, so the pair is its natural key; every other catalogue's ids
+ * are already platform-qualified by construction or are method-scoped.
+ */
+import { PLATFORM_SCOPED_AT_ORGANISATION } from "./platform-scope.js";
+import { deriveFeatureIntegrationSupport } from "./data-item-coverage.js";
+export { PLATFORM_SCOPED_AT_ORGANISATION };
+export function findDuplicatePrimaryKeys(schema, rowsByCatalogue, platformScopedTargets = []) {
+    const out = [];
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        // Scoped iff asked for AND the catalogue carries the stamp column.
+        const scoped = isPlatformScopedFk(cat, cat, { platformScopedTargets });
+        const byKey = new Map();
+        const stampsByKey = new Map();
+        for (const row of rows) {
+            const pk = row[cat.primaryKey];
+            if (pk === undefined || pk === null || pk === "")
+                continue;
+            const value = String(pk);
+            const sourceSdd = String(row["source_sdd_id"] ?? "");
+            const list = byKey.get(value) ?? [];
+            list.push(sourceSdd || "<unknown>");
+            byKey.set(value, list);
+            if (scoped) {
+                const stamps = stampsByKey.get(value) ?? [];
+                stamps.push(String(row[PLATFORM_STAMP_COLUMN] ?? "").trim());
+                stampsByKey.set(value, stamps);
+            }
+        }
+        for (const [value, sources] of byKey) {
+            if (sources.length > 1 && scoped) {
+                // n rows are distinct under (stamp, pk) iff every stamp is present
+                // and all differ. An EMPTY stamp is unresolved, never a key: it
+                // collides with everything (§4.4 — "two children contributing
+                // (∅, identity) must produce a finding, not a silent merge").
+                // Mirrors ddl-generator pkQuery's HAVING clause.
+                const stamps = stampsByKey.get(value) ?? [];
+                const distinctNonEmpty = new Set(stamps.filter((st) => st !== "")).size;
+                if (distinctNonEmpty === stamps.length)
+                    continue;
+                out.push({
+                    catalogue: cat.name,
+                    primaryKey: `(${PLATFORM_STAMP_COLUMN}, ${cat.primaryKey})`,
+                    value: `${value} [stamps: ${stamps.map((st) => st || "∅").join(", ")}] — an empty stamp is unresolved, never a key (M-ADR 0208 §4.4)`,
+                    sources,
+                });
+                continue;
+            }
+            if (sources.length > 1) {
+                out.push({
+                    catalogue: cat.name,
+                    primaryKey: cat.primaryKey,
+                    value,
+                    sources,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * M-ADR 0208 §4.4 (F-D), organisation tier. For each platform-scoped
+ * catalogue: which pks are owned by more than one platform, and how many
+ * referencing rows carry such a pk with NO stamp of their own — those
+ * references resolve by scalar fallback (the FK check cannot fail them
+ * without inventing a platform) but they are AMBIGUOUS, and this says so.
+ * One line per scoped catalogue, always written; a coverage finding only
+ * when ambiguity exists. Fires zero on an estate where no id is shared.
+ */
+export function checkPlatformScopedKeyAmbiguity(schema, rowsByCatalogue, platformScopedTargets, findings, write) {
+    for (const target of schema.catalogues) {
+        if (!isPlatformScopedFk(target, target, { platformScopedTargets }))
+            continue;
+        const owners = new Map();
+        for (const row of rowsByCatalogue.get(target.name) ?? []) {
+            const pk = String(row[target.primaryKey] ?? "");
+            if (pk === "")
+                continue;
+            const set = owners.get(pk) ?? new Set();
+            set.add(String(row[PLATFORM_STAMP_COLUMN] ?? "").trim() || "∅");
+            owners.set(pk, set);
+        }
+        const shared = new Set([...owners].filter(([, o]) => o.size > 1).map(([pk]) => pk));
+        let ambiguous = 0;
+        const where = [];
+        for (const cat of schema.catalogues) {
+            for (const fk of cat.foreignKeys) {
+                if (fk.references.split(".")[0] !== target.name)
+                    continue;
+                if (!isPlatformScopedFk(cat, target, { platformScopedTargets }))
+                    continue;
+                let n = 0;
+                for (const row of rowsByCatalogue.get(cat.name) ?? []) {
+                    const v = String(row[fk.column] ?? "");
+                    if (v === "" || !shared.has(v))
+                        continue;
+                    if (String(row[PLATFORM_STAMP_COLUMN] ?? "").trim() === "")
+                        n++;
+                }
+                if (n > 0) {
+                    ambiguous += n;
+                    where.push(`${cat.name}.${fk.column}=${n}`);
+                }
+            }
+        }
+        write(`  ${target.name} key at organisation tier is (${PLATFORM_STAMP_COLUMN}, ${target.primaryKey}) (M-ADR 0208 §4.4): ` +
+            `${shared.size} id(s) owned by more than one platform, ${ambiguous} unstamped referencing row(s) ambiguous\n`);
+        if (ambiguous > 0) {
+            findings.add("coverage", `${target.name}: ${ambiguous} referencing row(s) with EMPTY ${PLATFORM_STAMP_COLUMN} name an id owned by more than one platform [${[...shared].sort().join(", ")}] (${where.join(", ")}) — resolved by scalar fallback, AMBIGUOUS until the row is stamped (M-ADR 0208 §4.4)`);
+        }
+    }
+}
+async function mergeCatalogues(schema, rowsByCatalogue, cataloguesDir, sourceSddId, 
+/** M-ADR 0208 §4.4: value to fill into `platform_sdd_id` when empty; null = do not fill. */
+platformSddId) {
+    const counts = new Map();
+    let dirExists = true;
+    try {
+        const s = await stat(cataloguesDir);
+        if (!s.isDirectory())
+            dirExists = false;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            dirExists = false;
+        else
+            throw err;
+    }
+    if (!dirExists) {
+        throw new Error(`catalogues/ directory not found at ${cataloguesDir}\n` +
+            `  Run \`sdd-cli catalogue build\` in that SDD before aggregating.`);
+    }
+    for (const cat of schema.catalogues) {
+        const filePath = join(cataloguesDir, `${cat.name}.csv`);
+        let parsed;
+        try {
+            parsed = await readCatalogueCsv(filePath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                counts.set(cat.name, 0);
+                continue;
+            }
+            throw err;
+        }
+        const stamped = stampColumn(cat, stampColumn(cat, parsed.rows, "source_sdd_id", sourceSddId), "platform_sdd_id", platformSddId);
+        rowsByCatalogue.get(cat.name).push(...stamped);
+        counts.set(cat.name, stamped.length);
+    }
+    return counts;
+}
+/**
+ * Stamp `column` = `value` on every row that does not already carry one
+ * (preserve-if-set — chained aggregation, M-ADR 0134 §4.5 step 4). Used for
+ * `source_sdd_id` and, per M-ADR 0208 §4.4, for `platform_sdd_id`. A null value
+ * means "do not fill" (organisation tier, where the stamp arrived from below or
+ * is legitimately unresolved). No-op when the catalogue lacks the column.
+ */
+function stampColumn(catalogue, rows, column, value) {
+    const hasColumn = catalogue.columns.some((c) => c.name === column);
+    if (!hasColumn || value === null)
+        return rows.map((r) => ({ ...r }));
+    return rows.map((r) => {
+        if (String(r[column] ?? "").trim() !== "")
+            return { ...r };
+        return { ...r, [column]: value };
+    });
+}
+async function crossCheckSiblings(ecosystemRootPath, siblings, aggregatorSchema, write) {
+    const findings = new FindingsLog();
+    const siblingProfiles = new Map();
+    const siblingCategories = new Map();
+    const siblingDeclaredPlatform = new Map();
+    const deprecatedPlatformField = new Set();
+    for (const sib of siblings) {
+        let sibProfile;
+        if (sib.level === "organisation") {
+            // Organisation-level sibling: pre-built catalogues-aggregated/, no manifest.
+            sibProfile = "organisation";
+        }
+        else {
+            // Platform / app / integration: require manifest and cross-check sdd_id.
+            let sibManifest;
+            try {
+                sibManifest = await loadSddManifest(sib.sddRoot, {
+                    cliVersion: CLI_VERSION,
+                });
+            }
+            catch (err) {
+                throw new Error(`aggregator: sibling "${sib.sddId}" at ${relative(ecosystemRootPath, sib.sddRoot)}\n` +
+                    `  failed to load .sdd/sdd-manifest.yaml: ${err.message}`);
+            }
+            if (sibManifest.sddId !== sib.sddId) {
+                throw new Error(`aggregator: sibling "${sib.sddId}" in aggregation manifest\n` +
+                    `  but its own .sdd/sdd-manifest.yaml declares sdd_id="${sibManifest.sddId}"\n` +
+                    `  (rule: sibling_id_matches_sibling_manifest)`);
+            }
+            sibProfile = sibManifest.profile;
+            siblingCategories.set(sib.sddId, sibManifest.category);
+            if (sibManifest.platformSddId)
+                siblingDeclaredPlatform.set(sib.sddId, sibManifest.platformSddId);
+            if (sibManifest.platformFieldDeprecated)
+                deprecatedPlatformField.add(sib.sddId);
+        }
+        siblingProfiles.set(sib.sddId, sibProfile);
+        // Cross-check sibling's vendored catalogue-schema.yaml against the
+        // declared compat range. The aggregator's own canonical schema is the
+        // source of truth; the sibling's vendored copy is informational and
+        // only fails the cross-check if it falls outside SCHEMA_COMPAT (i.e.
+        // a major-version mismatch). Minor-version drift inside `^X.Y.Z` is
+        // tolerated — sibling at 2.1.0 against aggregator at 2.2.0 is fine
+        // because both satisfy ^2.0.0.
+        const sibSchemaPath = await findVendoredSchema(sib.sddRoot);
+        if (sibSchemaPath !== "") {
+            const text = await readFile(sibSchemaPath, "utf-8");
+            const m = /^schema_version:\s*"?([0-9.]+)"?/m.exec(text);
+            const sibVersion = m?.[1] ?? "";
+            if (sibVersion !== "" && !isInRange(sibVersion, SCHEMA_COMPAT.catalogue_schema)) {
+                throw new Error(`aggregator: sibling "${sib.sddId}" vendored catalogue-schema.yaml\n` +
+                    `  is at ${sibVersion}, outside the declared compat range\n` +
+                    `  ${SCHEMA_COMPAT.catalogue_schema} (aggregator at ${aggregatorSchema.schemaVersion}).\n` +
+                    `  Major-version mismatch — upgrade sdd-cli or sync the sibling\n` +
+                    `  against a matching forward-baseline (rule: schema_version_alignment).`);
+            }
+        }
+        write(`    ✓ ${sib.sddId} (${sibProfile})\n`);
+    }
+    return { findings, siblingProfiles, siblingCategories, siblingDeclaredPlatform, deprecatedPlatformField };
+}
+async function findVendoredSchema(sddRoot) {
+    // Adopters typically vendor canonical schema indirectly via sdd-cli.
+    // Some SDDs pin a copy at docs/method/methods/catalogue-schema.yaml.
+    for (const candidate of [
+        "docs/method/methods/catalogue-schema.yaml",
+    ]) {
+        const path = join(sddRoot, candidate);
+        try {
+            const s = await stat(path);
+            if (s.isFile())
+                return path;
+        }
+        catch {
+            // not present — try next
+        }
+    }
+    return "";
+}
+function resolveOutDir(sddPath, override) {
+    if (override !== undefined)
+        return resolve(override);
+    return join(sddPath, "catalogues-aggregated");
+}
+/**
+ * Platform tier only: reclassify dangling references on EXTERNAL FKs whose
+ * referencing row is sourced by the platform-root itself as deferred to the
+ * organisation tier. Returns the FK result with those failures removed and an
+ * `external` finding per deferred reference. See step 7a for the reasoning.
+ */
+function deferRootSourcedCrossPlatformExternals(schema, rowsByCatalogue, fk, rootSddId, findings, write) {
+    if (fk.internalFailures.length === 0)
+        return fk;
+    const externalByCatalogue = new Map();
+    for (const cat of schema.catalogues) {
+        const ext = new Set(cat.foreignKeys.filter((f) => f.external).map((f) => f.column));
+        if (ext.size > 0)
+            externalByCatalogue.set(cat.name, ext);
+    }
+    const kept = [];
+    let deferred = 0;
+    for (const f of fk.internalFailures) {
+        const isExternal = externalByCatalogue.get(f.catalogue)?.has(f.column) === true;
+        const source = findSourceSdd(rowsByCatalogue, f.catalogue, f.referencingRow);
+        if (isExternal && f.value !== "" && source === rootSddId) {
+            deferred++;
+            findings.add("external", `${f.catalogue}.${f.column} → ${f.target}=${f.value} (referencing row pk=${f.referencingRow}, sourced by the platform-root itself — a cross-platform dependency; resolves at organisation tier, M-ADR 0208)`);
+            continue;
+        }
+        kept.push(f);
+    }
+    if (deferred > 0) {
+        write(`  cross-platform externals deferred to organisation tier: ${deferred} (root-sourced rows on external FKs)\n`);
+    }
+    return { internalPass: kept.length === 0, internalFailures: kept, externalFindings: fk.externalFindings + deferred };
+}
+function findSourceSdd(rowsByCatalogue, catalogue, pkValue) {
+    const rows = rowsByCatalogue.get(catalogue) ?? [];
+    for (const row of rows) {
+        if (String(row["id"] ?? "") === pkValue) {
+            const src = String(row["source_sdd_id"] ?? "");
+            return src;
+        }
+    }
+    return "";
+}
+async function writeAggregationManifestJson(inputs) {
+    const out = {
+        schema_version: inputs.schemaVersion,
+        cli_version: inputs.cliVersion,
+        ecosystem_root: inputs.ecosystemRoot,
+        siblings: inputs.siblings.map((s) => ({
+            sdd_id: s.sddId,
+            description: s.description,
+            catalogues_path: s.relativeCataloguesPath,
+            pre_merge_row_counts: counts(inputs.perSiblingCounts.get(s.sddId)),
+        })),
+        ecosystem_root_pre_merge_row_counts: counts(inputs.perSiblingCounts.get(inputs.ecosystemRoot)),
+        aggregated_row_counts: counts(inputs.aggregatedRowCounts),
+    };
+    await writeFile(join(inputs.outDir, "aggregation-manifest.json"), JSON.stringify(out, null, 2) + "\n", "utf-8");
+}
+function counts(map) {
+    const out = {};
+    if (!map)
+        return out;
+    for (const [k, v] of [...map.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        out[k] = v;
+    }
+    return out;
+}
+async function finalise(inputs) {
+    const rowCounts = new Map();
+    for (const cat of inputs.schema.catalogues) {
+        rowCounts.set(cat.name, (inputs.rowsByCatalogue.get(cat.name) ?? []).length);
+    }
+    return {
+        exitCode: 1,
+        schemaVersion: inputs.schema.schemaVersion,
+        ecosystemRoot: inputs.ecosystemRoot,
+        siblingCount: inputs.aggManifest.siblings.length,
+        rowCounts,
+        perSiblingCounts: inputs.perSiblingCounts,
+        aggregatedFkPass: inputs.aggregatedFkPass,
+        findingsCount: inputs.findings.count(),
+        outDir: inputs.outDir,
+    };
+}
+/**
+ * Recover a feature's slug from its catalogue row. `features.id` is
+ * `{capability_id|product_id}-{slug}` (per the features builder), and both
+ * prefixes are columns — so the slug is the id with the owning prefix stripped.
+ * Falls back to the full id when no prefix is recoverable.
+ */
+function featureSlugOf(row) {
+    const id = String(row["id"] ?? "");
+    const cap = String(row["capability_id"] ?? "");
+    const prod = String(row["product_id"] ?? "");
+    const prefix = cap !== "" ? cap : prod;
+    if (prefix !== "" && id.startsWith(`${prefix}-`)) {
+        return id.slice(prefix.length + 1);
+    }
+    return id;
+}
+/**
+ * Resolve cross-SDD `screen_feature` edges (schema 2.24.0, R3).
+ *
+ * App/integration per-SDD builds emit `screen_feature` rows whose `feature_id`
+ * is the bare `realises:` slug when the feature lives in another SDD (the
+ * platform — MFE-over-platform). Here, post-merge, each such row (feature_id
+ * not already a feature PK) is resolved to the platform feature id by matching
+ * the slug against every merged feature's recovered slug:
+ *   - exactly one match  → rewrite feature_id (and the composite PK).
+ *   - >1 match           → ambiguous; refuse (divergence finding), leave as-is
+ *                          so the FK pass surfaces it. ADR 0177 guarantees one
+ *                          slug per *capability*, not estate-wide, so cross-
+ *                          capability slug clashes are possible and not guessed.
+ *   - 0 matches          → orphan finding, leave as-is.
+ * Rows that already resolve (local features; forward/app-owned estates) pass
+ * through untouched.
+ *
+ * Exported for testing.
+ */
+export function resolveCrossSddScreenFeature(screenFeatures, features, findings) {
+    const featureIds = new Set();
+    for (const f of features) {
+        const id = String(f["id"] ?? "");
+        if (id !== "")
+            featureIds.add(id);
+    }
+    const idsBySlug = new Map();
+    for (const f of features) {
+        const slug = featureSlugOf(f);
+        if (slug === "")
+            continue;
+        const bucket = idsBySlug.get(slug);
+        if (bucket === undefined)
+            idsBySlug.set(slug, [String(f["id"])]);
+        else
+            bucket.push(String(f["id"]));
+    }
+    const out = [];
+    const seenPk = new Set();
+    for (const row of screenFeatures) {
+        const featureId = String(row["feature_id"] ?? "");
+        // Already resolves (local feature, or an already-full id) — pass through.
+        if (featureId === "" || featureIds.has(featureId)) {
+            out.push(row);
+            continue;
+        }
+        const matches = idsBySlug.get(featureId) ?? [];
+        const screenId = String(row["screen_id"] ?? "");
+        if (matches.length === 1) {
+            const resolved = matches[0];
+            const pk = `${screenId}__${resolved}`;
+            if (seenPk.has(pk))
+                continue; // dedupe if another SDD already produced it
+            seenPk.add(pk);
+            out.push({ ...row, id: pk, feature_id: resolved });
+        }
+        else if (matches.length > 1) {
+            findings.add("divergence", `screen_feature: ${screenId} realises slug "${featureId}" resolves ambiguously ` +
+                `to ${matches.length} features ecosystem-wide (${matches.join(", ")}) — left unresolved; ` +
+                `qualify the realises ref or disambiguate the slug vocabulary`);
+            out.push(row);
+        }
+        else {
+            findings.add("orphan", `screen_feature: ${screenId} realises "${featureId}" — no feature resolves it ecosystem-wide`);
+            out.push(row);
+        }
+    }
+    return out;
+}
+/**
+ * Orphan-check `products.successor_sdd_id` soft references (schema 2.22.0).
+ *
+ * A deprecated product's successor pointer resolves when the named sdd_id is
+ * visible at this aggregation tier: either a direct contributor (root or
+ * sibling) or a `source_sdd_id` stamped on any products row by a lower tier
+ * (org-tier re-aggregation of cohort outputs). Unresolved pointers emit an
+ * `orphan` finding and nothing else — the successor may legitimately live
+ * outside the current aggregation scope, so this is never a hard FK failure.
+ *
+ * Exported for testing.
+ */
+export function checkSuccessorReferences(products, contributorSddIds, findings) {
+    const visible = new Set(contributorSddIds);
+    for (const p of products) {
+        const stamped = String(p["source_sdd_id"] ?? "");
+        if (stamped !== "")
+            visible.add(stamped);
+        const own = String(p["id"] ?? "");
+        if (own !== "")
+            visible.add(own);
+    }
+    for (const p of products) {
+        const successor = String(p["successor_sdd_id"] ?? "");
+        if (successor === "")
+            continue;
+        if (!visible.has(successor)) {
+            findings.add("orphan", `products: ${String(p["id"])} declares successor_sdd_id="${successor}" ` +
+                `but no contributing SDD resolves it at this tier (soft reference — ` +
+                `the successor may live outside this aggregation scope)`);
+        }
+    }
+}
+/**
+ * M-ADR 0189 §4.4 — adjudicate external-system candidates against the
+ * merged estate. A `System_Ext` in a domain-scoped L2 is a scope-relative
+ * REFERENCE (§4.1), and even L1 declarations may name something the estate
+ * owns (measured: 39% of one estate's dependency edges pointed at an
+ * external-system row denoting its own platform). Identity is the declared
+ * diagram entry id (§4.2) — at schema 3.0.0 the row id derives from it
+ * (M-ADR 0203 §4.2) — with the display name only as a unique-match
+ * fallback.
+ *
+ * Outcomes per candidate:
+ *  - resolves to an internal system of kind platform/subsystem/application:
+ *    the candidate row is dropped and its system_external_dependency edges
+ *    are rewritten onto system_system_dependency (§4.3). A name-fallback
+ *    resolution adds a `convention` finding (label-keyed identity, §4.2);
+ *    a would-be self-edge is refused with a finding.
+ *  - resolves to an internal system of kind `integration`: a PROVIDER-PAIR
+ *    COLLISION, not a reference (a connector SDD named after its genuinely
+ *    external provider — the kind discriminator measured on both estates).
+ *    Kept external; silent when self-declared, `convention` finding
+ *    otherwise.
+ *  - resolves to an internal container: tier contradiction — `coverage`
+ *    finding, row kept (the tier cannot be auto-corrected).
+ *  - resolves to nothing: genuinely external, unchanged.
+ *
+ * Exported for testing.
+ */
+export function adjudicateExternalSystems(rowsByCatalogue, findings) {
+    const systems = rowsByCatalogue.get("c4_systems") ?? [];
+    const exts = rowsByCatalogue.get("c4_external_systems") ?? [];
+    const containers = rowsByCatalogue.get("c4_containers") ?? [];
+    const deps = rowsByCatalogue.get("system_external_dependency") ?? [];
+    // Camel humps split BEFORE lowercasing (F11a): most SDD ids are
+    // hyphenated, and `bvfmGatewayFramework` must be able to declare
+    // `bvfm-gateway-framework`.
+    const norm = (s) => s
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const compact = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const systemIds = new Set(systems.map((s) => String(s["id"])));
+    const kindById = new Map(systems.map((s) => [String(s["id"]), String(s["kind"])]));
+    const sddById = new Map(systems.map((s) => [String(s["id"]), String(s["product_id"] ?? "")]));
+    const systemByProduct = new Map(systems
+        .filter((s) => String(s["product_id"] ?? "") !== "")
+        .map((s) => [String(s["product_id"]), String(s["id"])]));
+    // Name index — names ambiguous across systems are excluded from matching
+    // (post-F7 duplicates are themselves a finding).
+    const systemsByName = new Map();
+    for (const s of systems) {
+        const key = compact(String(s["name"] ?? ""));
+        if (key === "")
+            continue;
+        const ids = systemsByName.get(key);
+        if (ids)
+            ids.push(String(s["id"]));
+        else
+            systemsByName.set(key, [String(s["id"])]);
+    }
+    // Container indexes (F11b): keys (names + slug aliases) are confident
+    // only within the DECLARING SDD's own system; across the estate, only a
+    // full display-name match counts, and only when it is unique — a
+    // diagram-local alias like `emailService` must never bind to an
+    // unrelated SDD's container, and an ambiguous name asserts no referent.
+    const containerKeysBySystem = new Map();
+    const containersByName = new Map();
+    for (const c of containers) {
+        const cid = String(c["id"]);
+        const sysId = String(c["system_id"] ?? "");
+        const slugPart = sysId !== "" && cid.startsWith(`${sysId}-`) ? cid.slice(sysId.length + 1) : cid;
+        let own = containerKeysBySystem.get(sysId);
+        if (own === undefined) {
+            own = new Map();
+            containerKeysBySystem.set(sysId, own);
+        }
+        for (const key of [compact(String(c["name"] ?? "")), compact(slugPart)]) {
+            if (key !== "" && !own.has(key))
+                own.set(key, cid);
+        }
+        const nameKey = compact(String(c["name"] ?? ""));
+        if (nameKey !== "") {
+            const ids = containersByName.get(nameKey);
+            if (ids)
+                ids.push(cid);
+            else
+                containersByName.set(nameKey, [cid]);
+        }
+    }
+    const resolveSystem = (ext) => {
+        // Schema 3.0.0: the row id itself derives from the declared entry id
+        // (M-ADR 0203 §4.2), so the id-slug IS declared identity — it backstops
+        // an empty declared_id cell, and a hit through it is a declared hit
+        // (corroboration-gated), never a label-keyed one.
+        const declared = norm(String(ext["declared_id"] ?? "")) || String(ext["id"]).replace(/^ext-/, "");
+        if (declared !== "") {
+            for (const cand of [declared, `${declared}-system`]) {
+                if (systemIds.has(cand))
+                    return { id: cand, method: "declared" };
+            }
+            const viaProduct = systemByProduct.get(declared);
+            if (viaProduct !== undefined)
+                return { id: viaProduct, method: "declared" };
+        }
+        // NAME evidence, per M-ADR 0189 §4.2's ratified fallback ("the
+        // display-name slug remains only as a fallback for entries whose id
+        // resolves to nothing"). Under 2.x the row id WAS the name slug, so
+        // the id-slug path carried this; at 3.0.0 the slug must be derived
+        // from the name itself or the fallback silently narrows — measured on
+        // the first forward-estate probe: 35 of 38 internal platform edges
+        // reclassified external because `System_Ext(platform, "Acme
+        // Platform", …)` stopped resolving against the `acme-platform`
+        // product. Every hit here is method "name" (label-keyed — the
+        // conversion emits the §4.2 convention finding).
+        const nameSlug = norm(String(ext["name"] ?? ""));
+        if (nameSlug !== "") {
+            for (const cand of [nameSlug, `${nameSlug}-system`]) {
+                if (systemIds.has(cand))
+                    return { id: cand, method: "name" };
+            }
+            const viaNameProduct = systemByProduct.get(nameSlug);
+            if (viaNameProduct !== undefined)
+                return { id: viaNameProduct, method: "name" };
+        }
+        const byName = systemsByName.get(compact(String(ext["name"] ?? "")));
+        if (byName !== undefined && byName.length === 1) {
+            return { id: byName[0], method: "name" };
+        }
+        return null;
+    };
+    // Estate-wide declared-key index: key → container ids across ALL systems.
+    const containersByKey = new Map();
+    for (const [, own] of containerKeysBySystem) {
+        for (const [key, cid] of own) {
+            const ids = containersByKey.get(key);
+            if (ids) {
+                if (!ids.includes(cid))
+                    ids.push(cid);
+            }
+            else
+                containersByKey.set(key, [cid]);
+        }
+    }
+    const containerNameById = new Map(containers.map((c) => [String(c["id"]), String(c["name"] ?? "")]));
+    const containerSystemById = new Map(containers.map((c) => [String(c["id"]), String(c["system_id"] ?? "")]));
+    // F12: containers follow the SAME precedence as systems — declared id
+    // first, corroborated by the display name; the name alone only as a
+    // unique fallback. 0.73.0 inverted this (name-equality only, declared id
+    // discarded) and traded two false positives for five silent true
+    // contradictions. Silence is not the remedy for a false reason; a true
+    // reason is — every held candidate below states why it is held.
+    const resolveContainer = (ext) => {
+        const declarerSystem = systemByProduct.get(String(ext["source_sdd_id"] ?? ""));
+        if (declarerSystem !== undefined) {
+            const own = containerKeysBySystem.get(declarerSystem);
+            if (own !== undefined) {
+                // The id-slug key duplicates the declared key at 3.0.0 (the row id
+                // derives from the entry id) but backstops an empty declared_id.
+                for (const key of [
+                    compact(String(ext["declared_id"] ?? "")),
+                    compact(String(ext["id"]).replace(/^ext-/, "")),
+                    compact(String(ext["name"] ?? "")),
+                ]) {
+                    const cid = key !== "" ? own.get(key) : undefined;
+                    if (cid !== undefined)
+                        return { kind: "own", containerId: cid };
+                }
+            }
+        }
+        const extName = String(ext["name"] ?? "");
+        const declaredKey = compact(String(ext["declared_id"] ?? "")) ||
+            compact(String(ext["id"]).replace(/^ext-/, ""));
+        const byKey = declaredKey !== "" ? containersByKey.get(declaredKey) : undefined;
+        if (byKey !== undefined) {
+            const corroborating = byKey.filter((cid) => corroboratesLabel(extName, containerNameById.get(cid) ?? "", ""));
+            if (corroborating.length > 1) {
+                return { kind: "ambiguous", candidates: [...corroborating].sort((a, b) => a.localeCompare(b)) };
+            }
+            if (corroborating.length === 1) {
+                if (isUncertainLabel(extName)) {
+                    return { kind: "uncertain", containerId: corroborating[0] };
+                }
+                return { kind: "cross", containerId: corroborating[0] };
+            }
+            // Declared key matches, name disagrees — held, loudly.
+            return { kind: "uncorroborated", containerId: byKey[0] };
+        }
+        const nameKey = compact(extName);
+        const byName = nameKey !== "" ? containersByName.get(nameKey) : undefined;
+        if (byName !== undefined) {
+            if (byName.length === 1) {
+                if (isUncertainLabel(extName)) {
+                    return { kind: "uncertain", containerId: byName[0] };
+                }
+                return { kind: "cross", containerId: byName[0] };
+            }
+            return { kind: "ambiguous", candidates: [...byName].sort((a, b) => a.localeCompare(b)) };
+        }
+        return null;
+    };
+    // F11a/F12 corroboration: a declared-id hit converts (or binds) only when
+    // the display name agrees with the target — diagram entry ids are
+    // conventionally local, and an old mnemonic that happens to equal an
+    // estate id must not convert silently. Comparison is TOKEN-level, not
+    // substring (F12): "Tachograph Service" must not corroborate `tacho`
+    // (shared prefix, different entity), while "Engine (telematics
+    // processor)" must corroborate a container named "Engine" (a richer
+    // label must not defeat the match) and three-letter names like "CWS"
+    // must work (no length floor). Corroborated = compact equality with the
+    // target's name or id, or every token of either appearing among the
+    // label's tokens. A declared id that corroborates is an assertion the
+    // author is accountable for (M-ADR 0189 §4.2); renaming the mnemonic
+    // opts out.
+    const tokens = (s) => s
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t !== "");
+    const tokenSubset = (target, label) => {
+        const ts = tokens(target);
+        return ts.length > 0 && ts.every((t) => label.has(t));
+    };
+    const corroboratesLabel = (extName, targetName, targetId) => {
+        const en = compact(extName);
+        if (en === "")
+            return false;
+        const labelTokens = new Set(tokens(extName));
+        for (const t of [targetName, targetId]) {
+            if (t === "")
+                continue;
+            if (en === compact(t))
+                return true;
+            if (tokenSubset(t, labelTokens))
+                return true;
+        }
+        return false;
+    };
+    const nameBysystem = new Map(systems.map((s) => [String(s["id"]), String(s["name"] ?? "")]));
+    const corroborates = (ext, sysId) => corroboratesLabel(String(ext["name"] ?? ""), nameBysystem.get(sysId) ?? "", sddById.get(sysId) ?? "");
+    // A bracketed qualifier ("Email Service [unknown]") is the author
+    // declaring uncertainty — it must never be rendered as a confident
+    // referent (F11b/F12): held, with the uncertainty as the stated reason.
+    const isUncertainLabel = (name) => /\[[^\]]*\]/.test(name);
+    const keptExts = [];
+    const dropExtIds = new Map();
+    const outcomeByExtId = new Map();
+    let converted = 0;
+    let tierContradictions = 0;
+    let providerPairsKept = 0;
+    let uncorroboratedKept = 0;
+    let uncertainHolds = 0;
+    let ambiguousHolds = 0;
+    let unverified = 0;
+    let exempted = 0;
+    let containerConverted = 0;
+    let containerEdgesRewritten = 0;
+    let systemFallbackEdges = 0;
+    // (F17) edges per candidate, split by whether the member build resolved
+    // the Rel's non-external endpoint to a local container — the datum that
+    // decides whether a container-bound candidate can convert without
+    // destroying an edge.
+    const edgesByExtId = new Map();
+    for (const dep of deps) {
+        const key = String(dep["external_system_id"]);
+        let bucket = edgesByExtId.get(key);
+        if (bucket === undefined) {
+            bucket = { convertible: [], stuck: [] };
+            edgesByExtId.set(key, bucket);
+        }
+        if (String(dep["from_container_id"] ?? "") !== "")
+            bucket.convertible.push(dep);
+        else
+            bucket.stuck.push(dep);
+    }
+    const containerTargetByExtId = new Map();
+    const containerDroppedByExtId = new Map();
+    for (const ext of exts) {
+        const extId = String(ext["id"]);
+        const declaredBy = String(ext["source_sdd_id"] ?? "");
+        const sys = resolveSystem(ext);
+        if (sys !== null) {
+            const kind = kindById.get(sys.id) ?? "";
+            if (kind === "integration") {
+                providerPairsKept++;
+                outcomeByExtId.set(extId, "provider-pair collision");
+                keptExts.push(ext);
+                const ownerSdd = sddById.get(sys.id) ?? "";
+                if (declaredBy !== "" && declaredBy === ownerSdd) {
+                    // Self-declared provider pair — the connector SDD declaring its
+                    // genuinely-external provider. Silent by design.
+                }
+                else {
+                    findings.add("convention", `c4_external_systems: "${extId}" collides with integration-kind system "${sys.id}" — ` +
+                        `likely a provider pair (connector named after its external provider); kept external (M-ADR 0189 §4.4)`);
+                }
+                continue;
+            }
+            if (sys.method === "declared" && !corroborates(ext, sys.id)) {
+                // F11a: declared-id hit without name corroboration — a collision
+                // between a diagram-local mnemonic and an estate id, not a
+                // reference. Kept external, loudly.
+                uncorroboratedKept++;
+                outcomeByExtId.set(extId, "uncorroborated hold");
+                keptExts.push(ext);
+                findings.add("convention", `c4_external_systems: "${extId}" declared_id resolves to internal system "${sys.id}" ` +
+                    `but the display name does not corroborate — kept external; align the entry id or name to convert (M-ADR 0189 §4.2 / F11a)`);
+                continue;
+            }
+            if (isUncertainLabel(String(ext["name"] ?? ""))) {
+                // Declared uncertainty never converts (F12) — held with the
+                // uncertainty as the stated reason.
+                uncertainHolds++;
+                outcomeByExtId.set(extId, "uncertain hold");
+                keptExts.push(ext);
+                findings.add("coverage", `c4_external_systems: "${extId}" resolves to internal system "${sys.id}" but the label declares uncertainty — ` +
+                    `held, not converted; resolve the uncertainty to convert (M-ADR 0189 §4.4 / F12)`);
+                continue;
+            }
+            // Internal reference — convert.
+            dropExtIds.set(extId, { toSystem: sys.id });
+            converted++;
+            if (sys.method === "name") {
+                findings.add("convention", `c4_external_systems: "${extId}" resolved to internal system "${sys.id}" by display-name fallback — ` +
+                    `label-keyed identity; declare the entry id to make this exact (M-ADR 0189 §4.2)`);
+            }
+            continue;
+        }
+        const containerRes = resolveContainer(ext);
+        if (containerRes !== null) {
+            outcomeByExtId.set(extId, containerRes.kind === "uncorroborated"
+                ? "uncorroborated hold"
+                : containerRes.kind === "uncertain"
+                    ? "uncertain hold"
+                    : containerRes.kind === "ambiguous"
+                        ? "ambiguous hold"
+                        : "tier contradiction");
+            if (containerRes.kind === "uncorroborated") {
+                uncorroboratedKept++;
+                findings.add("convention", `c4_external_systems: "${extId}"${declaredBy !== "" ? ` (declared by ${declaredBy})` : ""} ` +
+                    `declared_id matches internal container "${containerRes.containerId}" but the display name does not corroborate — ` +
+                    `no referent asserted; align the entry id or name to bind (M-ADR 0189 §4.2 / F12)`);
+                keptExts.push(ext);
+                continue;
+            }
+            if (containerRes.kind === "uncertain") {
+                uncertainHolds++;
+                // (already marked as an outcome above)
+                findings.add("coverage", `c4_external_systems: "${extId}"${declaredBy !== "" ? ` (declared by ${declaredBy})` : ""} ` +
+                    `matches internal container "${containerRes.containerId}" but the label declares uncertainty — ` +
+                    `held, not asserted; resolve the uncertainty to bind (M-ADR 0189 §4.4 / F12)`);
+                keptExts.push(ext);
+                continue;
+            }
+            if (containerRes.kind === "ambiguous") {
+                ambiguousHolds++;
+                findings.add("coverage", `c4_external_systems: "${extId}"${declaredBy !== "" ? ` (declared by ${declaredBy})` : ""} ` +
+                    `name-matches ${containerRes.candidates.length} internal containers [${containerRes.candidates.join(", ")}] — ` +
+                    `ambiguous tier contradiction, no referent asserted, row kept (M-ADR 0189 §4.4 / F11b)`);
+            }
+            else {
+                // F17: a bound candidate CONVERTS — its edges rewrite onto
+                // container_dependency where the from-endpoint is known. Only a
+                // candidate with unconvertible edges is kept, with the
+                // contradiction finding stating exactly what blocks it. No edge
+                // is ever destroyed to make a build quieter.
+                containerTargetByExtId.set(extId, containerRes.containerId);
+                const bucket = edgesByExtId.get(extId);
+                // F24 (F17's residue): a stuck edge whose from-SYSTEM differs from
+                // the target container's owning system is a correct C4 L1 edge —
+                // it rewrites onto system_system_dependency (from-system → owning
+                // system). Only a stuck edge WITHIN the owning system truly blocks
+                // conversion: it would be an L1 self-edge, and the candidate is
+                // kept for it.
+                const owner = containerSystemById.get(containerRes.containerId) ?? "";
+                const trulyStuck = (bucket?.stuck ?? []).filter((d) => String(d["c4_system_id"]) === owner).length;
+                if (trulyStuck === 0) {
+                    containerConverted++;
+                    containerDroppedByExtId.set(extId, containerRes.containerId);
+                    outcomeByExtId.set(extId, "container conversion");
+                    continue; // row dropped — a phantom duplicate of the container
+                }
+                tierContradictions++;
+                findings.add("coverage", `c4_external_systems: "${extId}"${declaredBy !== "" ? ` (declared by ${declaredBy})` : ""} ` +
+                    `resolves to ${containerRes.kind === "own" ? "its declarer's own" : "an"} internal container "${containerRes.containerId}" — ` +
+                    `tier contradiction, row kept: ${trulyStuck} same-system dependency edge(s) have no member-resolved from-container and would be L1 self-edges (M-ADR 0189 §4.4 / F17/F24)`);
+            }
+        }
+        keptExts.push(ext);
+    }
+    // Rewrite dependency edges whose external endpoint converted — to a
+    // system (§4.4) or, one tier down, to a container (F17).
+    const keptDeps = [];
+    const newEdges = new Map();
+    const newContainerEdges = new Map();
+    let edgesRewritten = 0;
+    for (const dep of deps) {
+        const extKey = String(dep["external_system_id"]);
+        const containerTarget = containerTargetByExtId.get(extKey);
+        if (containerTarget !== undefined) {
+            const fromContainer = String(dep["from_container_id"] ?? "");
+            if (fromContainer === "") {
+                // F24: no member-resolved from-container. Across systems this is a
+                // correct C4 L1 edge — from-system → the container's owning system.
+                // Within the owning system it would be an L1 self-edge: kept, and
+                // its candidate row was kept for it.
+                const owner = containerSystemById.get(containerTarget) ?? "";
+                const fromSystem = String(dep["c4_system_id"]);
+                if (owner !== "" && fromSystem !== owner) {
+                    const sid = `${fromSystem}__${owner}`;
+                    const existingFE = newEdges.get(sid);
+                    if (existingFE !== undefined) {
+                        mergeEdgeLabel(existingFE, String(dep["interaction"] ?? ""), "system_system_dependency", findings);
+                    }
+                    else {
+                        newEdges.set(sid, {
+                            id: sid,
+                            from_system_id: fromSystem,
+                            to_system_id: owner,
+                            interaction: String(dep["interaction"] ?? ""),
+                            source_sdd_id: sddById.get(fromSystem) ?? "",
+                        });
+                    }
+                    systemFallbackEdges++;
+                    continue;
+                }
+                keptDeps.push(dep); // truly stuck — its candidate row was kept for it
+                continue;
+            }
+            if (fromContainer === containerTarget) {
+                findings.add("coverage", `container_dependency: refused self-edge ${fromContainer} → ${containerTarget} ` +
+                    `(external declaration resolved to the declaring container itself; M-ADR 0189 §4.4 / F17)`);
+                continue;
+            }
+            const cid = `${fromContainer}__${containerTarget}`;
+            const existingCE = newContainerEdges.get(cid);
+            if (existingCE !== undefined) {
+                mergeEdgeLabel(existingCE, String(dep["interaction"] ?? ""), "container_dependency", findings);
+            }
+            else {
+                newContainerEdges.set(cid, {
+                    id: cid,
+                    from_container_id: fromContainer,
+                    to_container_id: containerTarget,
+                    interaction: String(dep["interaction"] ?? ""),
+                    source_sdd_id: sddById.get(String(dep["c4_system_id"])) ?? "",
+                });
+            }
+            containerEdgesRewritten++;
+            continue;
+        }
+        const target = dropExtIds.get(extKey);
+        if (target === undefined) {
+            keptDeps.push(dep);
+            continue;
+        }
+        const from = String(dep["c4_system_id"]);
+        if (from === target.toSystem) {
+            findings.add("coverage", `system_system_dependency: refused self-edge ${from} → ${target.toSystem} ` +
+                `(external declaration resolved to the declaring system itself; M-ADR 0189 §4.4)`);
+            continue;
+        }
+        const id = `${from}__${target.toSystem}`;
+        const existingSE = newEdges.get(id);
+        if (existingSE !== undefined) {
+            mergeEdgeLabel(existingSE, String(dep["interaction"] ?? ""), "system_system_dependency", findings);
+        }
+        else {
+            newEdges.set(id, {
+                id,
+                from_system_id: from,
+                to_system_id: target.toSystem,
+                interaction: String(dep["interaction"] ?? ""),
+                source_sdd_id: sddById.get(from) ?? "",
+            });
+        }
+        edgesRewritten++;
+    }
+    // §4.6 (WS15): exemptions vs outcomes, then the coverage predicate.
+    // An exemption on a CONVERTED candidate contradicts the adjudication —
+    // reported and dropped (it would also dangle). A kept candidate with no
+    // outcome and no exemption is the silent bucket L4 lived in: reported
+    // unverified, one finding per candidate, retired by declared identity
+    // or by an asserted exemption.
+    // F15: the builder docstring — "each row retires exactly one unverified
+    // finding, and nothing else" — is enforced here, not assumed. A kept
+    // exemption MUST retire exactly one unverified finding; one that retires
+    // nothing (its candidate converted, or already has an adjudication
+    // outcome of any class) is reported and DROPPED, so that
+    // |external_system_exemption| == exempted holds as an invariant rather
+    // than a check someone has to remember.
+    const exemptionRows = rowsByCatalogue.get("external_system_exemption") ?? [];
+    const keptExtIds = new Set(keptExts.map((e) => String(e["id"])));
+    const keptExemptions = [];
+    const exemptedIds = new Set();
+    for (const ex of exemptionRows) {
+        const target = String(ex["external_system_id"] ?? "");
+        const conv = dropExtIds.get(target);
+        if (conv !== undefined) {
+            findings.add("convention", `external_system_exemption: "${target}" is asserted genuinely external but adjudication resolved it to ` +
+                `internal system "${conv.toSystem}" — contradiction; exemption dropped (M-ADR 0189 §4.6)`);
+            continue;
+        }
+        const containerDrop = containerDroppedByExtId.get(target);
+        if (containerDrop !== undefined) {
+            findings.add("convention", `external_system_exemption: "${target}" is asserted genuinely external but adjudication resolved it to ` +
+                `internal container "${containerDrop}" — contradiction; exemption dropped (M-ADR 0189 §4.6 / F17)`);
+            continue;
+        }
+        const outcome = outcomeByExtId.get(target);
+        if (outcome !== undefined) {
+            findings.add("convention", `external_system_exemption: "${target}" retires nothing — the candidate already has an adjudication ` +
+                `outcome (${outcome}); exemption dropped (M-ADR 0189 §4.6 / F15)`);
+            continue;
+        }
+        if (!keptExtIds.has(target)) {
+            findings.add("convention", `external_system_exemption: "${target}" names no kept external-system candidate — exemption dropped (M-ADR 0189 §4.6 / F15)`);
+            continue;
+        }
+        keptExemptions.push(ex);
+        exemptedIds.add(target);
+    }
+    rowsByCatalogue.set("external_system_exemption", keptExemptions);
+    for (const ext of keptExts) {
+        const extId = String(ext["id"]);
+        if (outcomeByExtId.has(extId))
+            continue;
+        if (exemptedIds.has(extId)) {
+            exempted++;
+            continue;
+        }
+        unverified++;
+        findings.add("coverage", `c4_external_systems: "${extId}" resolved to no internal system or container and carries no exemption — ` +
+            `kept external, unverified (M-ADR 0189 §4.6)`);
+    }
+    const existingCD = rowsByCatalogue.get("container_dependency") ?? [];
+    const mergedCD = [...existingCD];
+    const existingCDIds = new Set(existingCD.map((r) => String(r["id"])));
+    const existingCDById = new Map(existingCD.map((r) => [String(r["id"]), r]));
+    for (const row of [...newContainerEdges.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))) {
+        const member = existingCDById.get(String(row["id"]));
+        if (member !== undefined) {
+            mergeEdgeLabel(member, String(row["interaction"] ?? ""), "container_dependency", findings);
+            continue;
+        }
+        if (!existingCDIds.has(String(row["id"])))
+            mergedCD.push(row);
+    }
+    rowsByCatalogue.set("container_dependency", mergedCD);
+    const existingSSD = rowsByCatalogue.get("system_system_dependency") ?? [];
+    const merged = [...existingSSD];
+    const existingIds = new Set(existingSSD.map((r) => String(r["id"])));
+    const existingSSDById = new Map(existingSSD.map((r) => [String(r["id"]), r]));
+    for (const row of [...newEdges.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))) {
+        const member = existingSSDById.get(String(row["id"]));
+        if (member !== undefined) {
+            mergeEdgeLabel(member, String(row["interaction"] ?? ""), "system_system_dependency", findings);
+            continue;
+        }
+        if (!existingIds.has(String(row["id"])))
+            merged.push(row);
+    }
+    // M-ADR 0203 §4.2's detector for its own fallout: with row identity now
+    // the DECLARED entry id, SDDs that declared different entry ids for one
+    // real-world external system split into distinct rows — where the 2.x
+    // name-slug ids silently merged them. Measured before this shipped: 5 old
+    // ids deriving 2-3 conflicting new ids across one estate's SDDs. The
+    // split must be loud, not latent: one display name held by several kept
+    // declared identities is either one estate entity (converge the diagram
+    // entry ids — the rename is a diagram edit, the sanctioned opt-out) or
+    // genuinely several (rename the labels apart). Convention, not an error:
+    // the aggregator cannot know which.
+    const keptByName = new Map();
+    for (const ext of keptExts) {
+        const key = compact(String(ext["name"] ?? ""));
+        if (key === "")
+            continue;
+        const ids = keptByName.get(key);
+        if (ids)
+            ids.push(String(ext["id"]));
+        else
+            keptByName.set(key, [String(ext["id"])]);
+    }
+    for (const [, ids] of [...keptByName.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        if (ids.length < 2)
+            continue;
+        const sorted = [...ids].sort((a, b) => a.localeCompare(b));
+        findings.add("convention", `c4_external_systems: one display name "${String(keptExts.find((e) => String(e["id"]) === sorted[0])?.["name"] ?? "")}" is held by ${sorted.length} declared identities [${sorted.join(", ")}] — ` +
+            `either one estate entity split by divergent diagram entry ids (converge the entry ids) ` +
+            `or several entities sharing a label (rename the labels apart) (M-ADR 0203 §4.2)`);
+    }
+    rowsByCatalogue.set("c4_external_systems", keptExts);
+    rowsByCatalogue.set("system_external_dependency", keptDeps);
+    rowsByCatalogue.set("system_system_dependency", merged);
+    return {
+        converted,
+        edgesRewritten,
+        tierContradictions,
+        providerPairsKept,
+        uncorroboratedKept,
+        uncertainHolds,
+        ambiguousHolds,
+        unverified,
+        exempted,
+        containerConverted,
+        containerEdgesRewritten,
+        systemFallbackEdges,
+    };
+}
+/**
+ * M-ADR 0203 §4.4's cross-SDD detector-and-re-key, cut window only.
+ *
+ * Every FK referencing `contracts.id` (schema-driven, so a future contract
+ * edge is covered without touching this) is scanned over the merged rows: a
+ * value that resolves to no contract, but whose `${value}-${kind}` form
+ * resolves via the legacy map built from the MERGED contracts rows, is a
+ * provably tool-authored 2.x id — regenerable, not drift. The value re-keys
+ * and the composite row id's embedded `__`-delimited component re-keys with
+ * it. A re-keyed row whose id then collides with an existing row is the
+ * same fact asserted under both eras — deduped, counted. An old id that was
+ * a 2.x cross-family collision maps to several contracts: loud and left
+ * dangling for FK validation to report (the author qualifies; never a
+ * guess). Exported for testing.
+ */
+export function rekeyLegacyContractRefs(schema, rowsByCatalogue, findings) {
+    const contracts = rowsByCatalogue.get("contracts") ?? [];
+    const contractIds = new Set(contracts.map((r) => String(r["id"])));
+    const legacyMap = buildLegacyContractIdMap(contracts);
+    let rekeyed = 0;
+    let deduped = 0;
+    let ambiguous = 0;
+    if (legacyMap.size === 0)
+        return { rekeyed, deduped, ambiguous };
+    for (const cat of schema.catalogues) {
+        const fkCols = cat.foreignKeys
+            .filter((fk) => fk.references === "contracts.id")
+            .map((fk) => fk.column);
+        if (fkCols.length === 0 || cat.name === "contracts")
+            continue;
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length === 0)
+            continue;
+        const perOldId = new Map();
+        const ambiguousOld = new Map();
+        const kept = [];
+        const idsAfter = new Set(rows.map((r) => String(r["id"])));
+        for (const row of rows) {
+            let dropped = false;
+            let current = row;
+            for (const col of fkCols) {
+                const value = String(current[col] ?? "");
+                if (value === "" || contractIds.has(value))
+                    continue;
+                const mapped = legacyMap.get(value);
+                if (mapped === undefined)
+                    continue;
+                if (mapped.length > 1) {
+                    ambiguousOld.set(value, mapped);
+                    continue;
+                }
+                const newVal = mapped[0];
+                const oldRowId = String(current["id"] ?? "");
+                const newRowId = oldRowId
+                    .split("__")
+                    .map((part) => (part === value ? newVal : part))
+                    .join("__");
+                if (newRowId !== oldRowId && idsAfter.has(newRowId)) {
+                    // The same edge fact already exists under the new id (typically
+                    // the owning SDD's own re-keyed row) — one fact, two eras.
+                    deduped++;
+                    dropped = true;
+                    break;
+                }
+                const replaced = {
+                    ...current,
+                    [col]: newVal,
+                };
+                if (newRowId !== oldRowId) {
+                    idsAfter.delete(oldRowId);
+                    idsAfter.add(newRowId);
+                    replaced["id"] = newRowId;
+                }
+                current = replaced;
+                perOldId.set(value, (perOldId.get(value) ?? 0) + 1);
+                rekeyed++;
+            }
+            if (!dropped)
+                kept.push(current);
+        }
+        rowsByCatalogue.set(cat.name, kept);
+        for (const [oldId, count] of [...perOldId.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            findings.add("inferred", `${cat.name}: ${count} cross-SDD reference(s) to "${oldId}" re-keyed to "${legacyMap.get(oldId)[0]}" — ` +
+                `2.x kindless contract id migrated per the 3.0.0 map (regenerable, not drift; M-ADR 0203 §4.4)`);
+        }
+        for (const [oldId, targets] of [...ambiguousOld.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            ambiguous++;
+            findings.add("convention", `${cat.name}: references to "${oldId}" map to ${targets.length} contracts at 3.0.0 [${targets.join(", ")}] — ` +
+                `a 2.x cross-family collision; the referencing SDD must qualify with the kind-suffixed id; left dangling (M-ADR 0203 §4.4)`);
+        }
+    }
+    return { rekeyed, deduped, ambiguous };
+}
+/**
+ * Fill `platform_sdd_id` on rows the aggregator constructed after the node
+ * loader stamped its inputs (M-ADR 0208 §4.4). The node loader stamps every
+ * row it MERGES; rows built at this tier from those inputs — 0189 §4.4
+ * adjudication conversions into system_system_dependency / container_dependency,
+ * re-derived edges — set source_sdd_id explicitly and were emitted with an empty
+ * platform stamp under FK PASS (measured: 38 of 38 system_system_dependency rows
+ * and 2 of 208 container_dependency rows on the forward reference estate, the
+ * other 206 stamped by the loader; 26 of 26 and 13 of 194 on the reverse estate's
+ * platform tier). Resolution order per row: the §4.4 fill-rule platform recorded
+ * for its source_sdd_id; else the single stamp already observed on that source's
+ * rows anywhere in the aggregate (a source whose rows carry two different stamps
+ * is ambiguous and is NOT guessed). Whatever remains empty is reported as
+ * coverage — an empty stamp is unresolved, never a key value. Exported for testing.
+ */
+export function fillDerivedPlatformStamps(schema, rowsByCatalogue, platformBySource, findings) {
+    const stamped = schema.catalogues.filter((c) => c.columns.some((col) => col.name === "platform_sdd_id") &&
+        c.columns.some((col) => col.name === "source_sdd_id"));
+    const observed = new Map();
+    for (const cat of stamped) {
+        for (const r of rowsByCatalogue.get(cat.name) ?? []) {
+            const src = String(r["source_sdd_id"] ?? "").trim();
+            const pf = String(r["platform_sdd_id"] ?? "").trim();
+            if (src === "" || pf === "")
+                continue;
+            if (!observed.has(src))
+                observed.set(src, new Set());
+            observed.get(src).add(pf);
+        }
+    }
+    const resolve = (src) => {
+        const ruled = platformBySource.get(src);
+        if (ruled !== undefined)
+            return ruled;
+        const seen = observed.get(src);
+        if (seen !== undefined && seen.size === 1)
+            return [...seen][0];
+        return null;
+    };
+    let filled = 0;
+    const unresolved = [];
+    for (const cat of stamped) {
+        const rows = rowsByCatalogue.get(cat.name);
+        if (rows === undefined || rows.length === 0)
+            continue;
+        let catEmpty = 0;
+        const next = rows.map((r) => {
+            if (String(r["platform_sdd_id"] ?? "").trim() !== "")
+                return r;
+            const src = String(r["source_sdd_id"] ?? "").trim();
+            const value = src === "" ? null : resolve(src);
+            if (value === null) {
+                catEmpty++;
+                return r;
+            }
+            filled++;
+            return { ...r, platform_sdd_id: value };
+        });
+        rowsByCatalogue.set(cat.name, next);
+        if (catEmpty > 0)
+            unresolved.push(`${cat.name} ${catEmpty}`);
+    }
+    if (filled > 0) {
+        findings.add("inferred", `platform_sdd_id: ${filled} aggregator-constructed row(s) stamped from their source_sdd_id after derivation (M-ADR 0208 §4.4) — the node loader stamps only the rows it merges`);
+    }
+    if (unresolved.length > 0) {
+        findings.add("coverage", `platform_sdd_id: rows still EMPTY after the final pass [${unresolved.join(", ")}] — source unknown to the fill rule, or its rows carry more than one stamp; unresolved, not a key (M-ADR 0208 §4.4)`);
+    }
+}
+/**
+ * M-ADR 0133 §4.2c open hygiene, shipped with M-ADR 0189 §4.4, TIER-GATED by
+ * M-ADR 0208 §4.2 — gated, not skipped: a skipped check fails toward success.
+ *   platform tier:      exactly one row with kind "platform" in the aggregate.
+ *   organisation tier:  exactly one "platform" row PER DISTINCT platform_sdd_id,
+ *                       and every "platform" row must carry a stamp — an empty
+ *                       stamp is unresolved, never a key (0208 §4.4).
+ * Exported for testing.
+ */
+export function checkPlatformKindUniqueness(systems, findings, tier = "platform") {
+    const plats = systems.filter((s) => String(s["kind"]) === "platform");
+    if (tier === "platform") {
+        const ids = plats.map((s) => String(s["id"])).sort((a, b) => a.localeCompare(b));
+        if (ids.length > 1) {
+            findings.add("convention", `c4_systems: ${ids.length} rows with kind "platform" [${ids.join(", ")}] — ` +
+                `exactly one per platform (M-ADR 0208 §4.2); this is a platform-tier aggregate`);
+        }
+        return;
+    }
+    const unstamped = plats
+        .filter((s) => String(s["platform_sdd_id"] ?? "").trim() === "")
+        .map((s) => String(s["id"]))
+        .sort((a, b) => a.localeCompare(b));
+    if (unstamped.length > 0) {
+        findings.add("coverage", `c4_systems: ${unstamped.length} "platform" row(s) with EMPTY platform_sdd_id at organisation tier [${unstamped.join(", ")}] — unresolved, not a key (M-ADR 0208 §4.4)`);
+    }
+    const byPlatform = new Map();
+    for (const s of plats) {
+        const key = String(s["platform_sdd_id"] ?? "").trim();
+        if (key === "")
+            continue;
+        const list = byPlatform.get(key) ?? [];
+        list.push(String(s["id"]));
+        byPlatform.set(key, list);
+    }
+    for (const [platform, ids] of byPlatform) {
+        if (ids.length > 1) {
+            findings.add("convention", `c4_systems: platform "${platform}" has ${ids.length} rows with kind "platform" [${ids.sort((a, b) => a.localeCompare(b)).join(", ")}] — exactly one per platform (M-ADR 0208 §4.2)`);
+        }
+    }
+}
+/**
+ * Flag c4_systems rows that share name AND description (M-ADR 0189 §4.5.3).
+ * PK uniqueness and FK validation cannot see this class: when a sibling's
+ * identity is sourced from a syndicated copy of the platform L1, the id is
+ * right and every other column is wrong. Measured at 29 of 60 systems on one
+ * estate and 17 of 40 on another before the 0.68.0 identity-sourcing fix;
+ * this is the aggregation-tier backstop.
+ *
+ * Exported for testing.
+ */
+export function checkDuplicateSystemIdentity(systems, findings) {
+    const byIdentity = new Map();
+    for (const s of systems) {
+        const name = String(s["name"] ?? "");
+        const description = String(s["description"] ?? "");
+        if (name === "")
+            continue;
+        const key = JSON.stringify([name, description]);
+        const group = byIdentity.get(key);
+        if (group)
+            group.ids.push(String(s["id"]));
+        else
+            byIdentity.set(key, { name, ids: [String(s["id"])] });
+    }
+    for (const group of byIdentity.values()) {
+        if (group.ids.length < 2)
+            continue;
+        findings.add("convention", `c4_systems: ${group.ids.length} rows share name "${group.name}" and an ` +
+            `identical description [${group.ids.sort((a, b) => a.localeCompare(b)).join(", ")}] — ` +
+            `sibling identity likely sourced from a syndicated platform L1`);
+    }
+}
+/**
+ * Does a file exist at this absolute path? `stat` rather than `access` to match
+ * the rest of this module's imports; a directory is deliberately NOT a hit — a
+ * contract_path names a contract file.
+ */
+async function fileExists(absPath) {
+    try {
+        const st = await stat(absPath);
+        return st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Derive `cross_sdd_platform_capability` rows by joining each consuming
+ * SDD's `product_platform_dependencies` rows against every platform SDD's
+ * `capability_service` rows on `target_service_id == service_id`.
+ *
+ * Emits one row per resolved (consuming-product, platform-capability)
+ * pair. A consuming dependency whose `target_service_id` doesn't resolve
+ * against any `capability_service` row is logged as an `orphan` finding
+ * and produces no row.
+ *
+ * ASYNC shared-stream dependencies (M-ADR 0192) — a dependency whose
+ * `contract_type` is in the async set (`event`/`event-stream`/`stream`) — have
+ * no single realiser service and carry an empty `target_service_id`. The F18
+ * synchronous realiser-join does not apply to them: instead they resolve via
+ * the capability leg (`target_capability_id` against any `capability_service`
+ * row for that capability) and emit the (consuming-product, platform-capability)
+ * edge with an empty `service_id`. A capability that resolves to no
+ * `capability_service` row ecosystem-wide is an `orphan` finding.
+ *
+ * Duplicate composite ids (same consuming-product → same platform-capability
+ * → same service) are deduped silently — they would arise only when the
+ * same service belongs to multiple capabilities on the platform side,
+ * which is itself a platform-side data quality concern surfaced elsewhere.
+ *
+ * Exported for testing.
+ */
+export function deriveCrossSddPlatformCapability(productPlatformDeps, capabilityServices, findings, capabilities = []) {
+    // The edge's PLATFORM LEG. `capability_service` has no source_sdd_id column
+    // (schema: id, capability_id, service_id, role), so the row that knows which
+    // platform owns a capability is `capabilities` — its platform_sdd_id
+    // (M-ADR 0208 §4.4) or, on pre-0208 output, its source_sdd_id. From
+    // 2.9.0 (v0.22.0) until 1.19.2 this read `match["source_sdd_id"]` off the
+    // capability_service row and was therefore "" on every emitted row, in
+    // every estate — the id carried a visible empty slot (`a__b____cap__svc`).
+    const platformByCapability = new Map();
+    for (const cap of capabilities) {
+        const id = String(cap["id"] ?? "").trim();
+        if (id === "")
+            continue;
+        const leg = String(cap["platform_sdd_id"] ?? "").trim() ||
+            String(cap["source_sdd_id"] ?? "").trim();
+        if (leg !== "" && !platformByCapability.has(id))
+            platformByCapability.set(id, leg);
+    }
+    const unresolvedLegs = new Set();
+    const resolvePlatformLeg = (match) => {
+        const capId = String(match["capability_id"] ?? "");
+        const leg = platformByCapability.get(capId) ?? String(match["source_sdd_id"] ?? "").trim();
+        if (leg === "" && capId !== "")
+            unresolvedLegs.add(capId);
+        return leg;
+    };
+    // Index capability_service rows by service_id for O(1) lookup. A service
+    // may belong to multiple capabilities — keep them all so a dependency
+    // can resolve into every capability that owns its service. Filter out
+    // rows whose service_id OR capability_id is empty up front, so that
+    // the "no valid join" orphan check below fires when only-malformed
+    // matches exist.
+    const byServiceId = new Map();
+    // Also index by capability_id, for the async capability-leg resolution
+    // (M-ADR 0192) — an async dependency has no service to join on.
+    const byCapabilityId = new Map();
+    for (const cs of capabilityServices) {
+        const svc = String(cs["service_id"] ?? "");
+        const cap = String(cs["capability_id"] ?? "");
+        if (svc === "" || cap === "")
+            continue;
+        const svcBucket = byServiceId.get(svc);
+        if (svcBucket === undefined) {
+            byServiceId.set(svc, [cs]);
+        }
+        else {
+            svcBucket.push(cs);
+        }
+        const capBucket = byCapabilityId.get(cap);
+        if (capBucket === undefined) {
+            byCapabilityId.set(cap, [cs]);
+        }
+        else {
+            capBucket.push(cs);
+        }
+    }
+    const rows = [];
+    const seenIds = new Set();
+    for (const ppd of productPlatformDeps) {
+        // M-ADR 0204: an off-platform row has no realiser to join — its FK columns
+        // are empty by construction, and its validation is §4.2 corroboration, not
+        // this derivation. Explicit skip rather than falling through to the empty-
+        // service branches, so the reason is structural and not incidental.
+        const locus = String(ppd["target_locus"] ?? "").trim().toLowerCase();
+        if (locus === "external" || locus === "legacy")
+            continue;
+        const consumingSddId = String(ppd["source_sdd_id"] ?? "");
+        const consumingProductId = String(ppd["product_id"] ?? "");
+        const targetServiceId = String(ppd["target_service_id"] ?? "");
+        const targetCapabilityId = String(ppd["target_capability_id"] ?? "");
+        const contractType = String(ppd["contract_type"] ?? "");
+        if (consumingProductId === "")
+            continue;
+        // M-ADR 0192: an async shared-stream dependency has no realiser service.
+        // The F18 pair-join cannot apply — resolve via the capability leg and emit
+        // the (consuming-product, platform-capability) edge with an empty service.
+        if (isAsyncContractType(contractType)) {
+            if (targetCapabilityId === "")
+                continue;
+            const capMatches = byCapabilityId.get(targetCapabilityId);
+            if (capMatches === undefined || capMatches.length === 0) {
+                findings.add("orphan", `cross_sdd_platform_capability: ${consumingSddId}/${consumingProductId} declares an async dependency on target_capability_id="${targetCapabilityId}" (contract_type="${contractType}") but no capability_service row realises it ecosystem-wide`);
+                continue;
+            }
+            for (const match of capMatches) {
+                const platformSddId = resolvePlatformLeg(match);
+                const id = [
+                    consumingSddId,
+                    consumingProductId,
+                    platformSddId,
+                    targetCapabilityId,
+                    "",
+                ].join("__");
+                if (seenIds.has(id))
+                    continue;
+                seenIds.add(id);
+                rows.push({
+                    id,
+                    consuming_sdd_id: consumingSddId,
+                    consuming_product_id: consumingProductId,
+                    platform_sdd_id: platformSddId,
+                    platform_capability_id: targetCapabilityId,
+                    service_id: "",
+                });
+            }
+            continue;
+        }
+        // SYNCHRONOUS dependency — the realiser-join path. A row with no service is
+        // a single-sided / malformed entry the builder would not emit; skip it.
+        if (targetServiceId === "")
+            continue;
+        const matches = byServiceId.get(targetServiceId);
+        if (matches === undefined || matches.length === 0) {
+            findings.add("orphan", `cross_sdd_platform_capability: ${consumingSddId}/${consumingProductId} declares target_service_id="${targetServiceId}" but no capability_service row resolves it ecosystem-wide`);
+            continue;
+        }
+        // F18: validate the declared PAIR, not each column alone. Both columns
+        // resolving independently while no capability_service row binds them
+        // is a false pairing accepted in silence — the evidence table for the
+        // pair exists and was never consulted.
+        const declaredCapability = targetCapabilityId;
+        if (declaredCapability !== "") {
+            const pairBound = matches.some((m) => String(m["capability_id"]) === declaredCapability);
+            if (!pairBound) {
+                const actual = [...new Set(matches.map((m) => String(m["capability_id"])))]
+                    .sort((a, b) => a.localeCompare(b))
+                    .join(", ");
+                findings.add("divergence", `product_platform_dependencies: ${consumingSddId}/${consumingProductId} declares the pair ` +
+                    `(target_capability_id="${declaredCapability}", target_service_id="${targetServiceId}") but no ` +
+                    `capability_service row binds them — the service resolves to [${actual}] (F18)`);
+            }
+        }
+        for (const match of matches) {
+            const platformSddId = resolvePlatformLeg(match);
+            const platformCapabilityId = String(match["capability_id"] ?? "");
+            if (platformCapabilityId === "")
+                continue;
+            const id = [
+                consumingSddId,
+                consumingProductId,
+                platformSddId,
+                platformCapabilityId,
+                targetServiceId,
+            ].join("__");
+            if (seenIds.has(id))
+                continue;
+            seenIds.add(id);
+            rows.push({
+                id,
+                consuming_sdd_id: consumingSddId,
+                consuming_product_id: consumingProductId,
+                platform_sdd_id: platformSddId,
+                platform_capability_id: platformCapabilityId,
+                service_id: targetServiceId,
+            });
+        }
+    }
+    if (unresolvedLegs.size > 0) {
+        const caps = [...unresolvedLegs].sort((a, b) => a.localeCompare(b));
+        findings.add("coverage", `cross_sdd_platform_capability: platform leg (platform_sdd_id) unresolved for ${caps.length} capability id(s) [${caps.join(", ")}] — no capabilities row carries platform_sdd_id or source_sdd_id for them; the edge id has an empty slot`);
+    }
+    return rows;
+}
+// Used by tests that want to round-trip CSV through the aggregator's
+// stamping logic without writing files.
+export const __test_only__ = { stampColumn, parseCatalogueCsv };
+//# sourceMappingURL=aggregate.js.map