@mortice/mapwright 0.8.0

package/dist/comparison/candidates.js

@@ -0,0 +1,391 @@
+import { changeIdentityId } from "./identity.js";
+import { indexDomain } from "./projections.js";
+const GLOBAL_BUDGET = 50_000;
+const MAX_PER_REMOVED = 5;
+function symbolFields(rec) {
+    if (!rec)
+        return {};
+    const doc = rec.doc;
+    return {
+        language: rec.language,
+        kind: rec.kind,
+        name: rec.name,
+        packageId: rec.packageId,
+        modulePath: rec.modulePath,
+        qualifiedName: rec.qualifiedName,
+        qualifiedContainerPath: rec.qualifiedContainerPath,
+        signatureFingerprint: rec.signatureFingerprint,
+        implementationFingerprint: rec.implementationFingerprint,
+        docFp: doc?.text ? `doc:${doc.text.length}:${doc.text.slice(0, 32)}` : undefined,
+        capabilities: Array.isArray(rec.capabilities) ? rec.capabilities : undefined
+    };
+}
+function topologyBucket(modulePath) {
+    if (!modulePath)
+        return "";
+    const parts = modulePath.replaceAll("\\", "/").split("/");
+    if (parts.includes("src"))
+        return "src";
+    if (parts.includes("dist") || parts.includes("build") || parts.includes("out"))
+        return "generated";
+    return parts.slice(0, -1).join("/") || "root";
+}
+function scorePair(categories) {
+    let score = 0;
+    if (categories.has("signature_fingerprint"))
+        score += 40;
+    if (categories.has("implementation_fingerprint"))
+        score += 30;
+    if (categories.has("language_kind"))
+        score += 10;
+    if (categories.has("package_continuity"))
+        score += 10;
+    if (categories.has("module_topology"))
+        score += 8;
+    if (categories.has("qualified_container"))
+        score += 8;
+    if (categories.has("public_export_target"))
+        score += 12;
+    if (categories.has("relationship_neighbourhood"))
+        score += 10;
+    if (categories.has("linkage"))
+        score += 6;
+    if (categories.has("documentation_fingerprint"))
+        score += 4;
+    if (categories.has("exported_name"))
+        score += 5;
+    if (categories.has("import_path"))
+        score += 5;
+    return score;
+}
+function sufficientEvidence(categories) {
+    if (categories.size < 2)
+        return false;
+    // public surface: package + (name or import path)
+    if (categories.has("package_continuity") && (categories.has("exported_name") || categories.has("import_path"))) {
+        return true;
+    }
+    // package+name alone insufficient for symbol declaration matching
+    const onlyWeak = [...categories].every((c) => ["package_continuity", "exported_name", "basename", "documentation_fingerprint"].includes(c)) && !categories.has("signature_fingerprint") && !categories.has("implementation_fingerprint");
+    if (onlyWeak)
+        return false;
+    // module path + name alone insufficient
+    if (categories.size === 2 &&
+        categories.has("module_topology") &&
+        (categories.has("exported_name") || categories.has("basename"))) {
+        return false;
+    }
+    // one fingerprint + one structural signal OK when uniqueness proven later
+    if (categories.has("signature_fingerprint") || categories.has("implementation_fingerprint")) {
+        return categories.size >= 2;
+    }
+    // need ≥2 independent strong-ish categories including language_kind + package + something
+    return (categories.has("language_kind") &&
+        categories.has("package_continuity") &&
+        (categories.has("qualified_container") ||
+            categories.has("public_export_target") ||
+            categories.has("relationship_neighbourhood") ||
+            categories.has("linkage")));
+}
+function classifyKind(rem, add, reasons) {
+    const pathChanged = rem.modulePath !== add.modulePath ||
+        (rem.importPath != null && add.importPath != null && rem.importPath !== add.importPath);
+    const nameChanged = rem.name !== add.name;
+    if (pathChanged && nameChanged)
+        return "probable_move_and_rename";
+    if (pathChanged && !nameChanged)
+        return "probable_move";
+    if (!pathChanged && nameChanged)
+        return "probable_rename";
+    if (reasons.includes("exported_name_match") || reasons.includes("import_path_match")) {
+        return "public_surface_transition";
+    }
+    return "possible_replacement";
+}
+function collectDeclarationPairs(comparisonId, changes, base, head, budget, warnings) {
+    const removed = changes.filter((c) => c.domain === "symbols" && c.status === "removed");
+    const added = changes.filter((c) => c.domain === "symbols" && c.status === "added");
+    const baseIdx = indexDomain("symbols", base);
+    const headIdx = indexDomain("symbols", head);
+    const pairs = [];
+    for (const rem of removed) {
+        const baseRec = baseIdx.get(rem.baseRecordId ?? "");
+        const bf = symbolFields(baseRec);
+        for (const add of added) {
+            if (budget.remaining-- <= 0) {
+                warnings.push("candidate_work_budget_exhausted");
+                return pairs;
+            }
+            const headRec = headIdx.get(add.headRecordId ?? "");
+            const hf = symbolFields(headRec);
+            if (bf.language && hf.language && bf.language !== hf.language)
+                continue;
+            if (bf.kind && hf.kind && bf.kind !== hf.kind)
+                continue;
+            const categories = new Set();
+            const reasons = [];
+            const facets = [];
+            if (bf.language && hf.language && bf.kind && hf.kind && bf.language === hf.language && bf.kind === hf.kind) {
+                categories.add("language_kind");
+                reasons.push("language_kind_match");
+            }
+            if (bf.packageId && hf.packageId && bf.packageId === hf.packageId) {
+                categories.add("package_continuity");
+                reasons.push("package_continuity");
+            }
+            if (bf.name && hf.name && bf.name === hf.name) {
+                reasons.push("declaration_name_match");
+            }
+            if (bf.signatureFingerprint &&
+                hf.signatureFingerprint &&
+                bf.signatureFingerprint === hf.signatureFingerprint) {
+                categories.add("signature_fingerprint");
+                reasons.push("signature_fingerprint_match");
+            }
+            if (bf.implementationFingerprint &&
+                hf.implementationFingerprint &&
+                bf.implementationFingerprint === hf.implementationFingerprint) {
+                categories.add("implementation_fingerprint");
+                reasons.push("implementation_fingerprint_match");
+            }
+            if (bf.qualifiedContainerPath != null &&
+                hf.qualifiedContainerPath != null &&
+                bf.qualifiedContainerPath === hf.qualifiedContainerPath) {
+                categories.add("qualified_container");
+                reasons.push("qualified_container_match");
+            }
+            if (topologyBucket(bf.modulePath) && topologyBucket(bf.modulePath) === topologyBucket(hf.modulePath)) {
+                categories.add("module_topology");
+                reasons.push("module_topology_match");
+                if (bf.modulePath !== hf.modulePath)
+                    facets.push("module_path_changed");
+            }
+            if (bf.docFp && hf.docFp && bf.docFp === hf.docFp) {
+                categories.add("documentation_fingerprint");
+                reasons.push("documentation_fingerprint_match");
+            }
+            if (bf.capabilities &&
+                hf.capabilities &&
+                bf.capabilities.length > 0 &&
+                JSON.stringify([...bf.capabilities].sort()) === JSON.stringify([...hf.capabilities].sort())) {
+                categories.add("linkage");
+                reasons.push("capability_linkage_match");
+            }
+            // Name alone is not a category for sufficiency
+            if (!sufficientEvidence(categories))
+                continue;
+            // Still require name OR fingerprint continuity to avoid random package matches
+            const hasIdentityAnchor = categories.has("signature_fingerprint") ||
+                categories.has("implementation_fingerprint") ||
+                (reasons.includes("declaration_name_match") && categories.has("package_continuity") && categories.size >= 3);
+            if (!hasIdentityAnchor)
+                continue;
+            pairs.push({
+                rem,
+                add,
+                domain: "symbols",
+                reasons,
+                categories: [...categories],
+                facets,
+                kind: classifyKind(rem, add, reasons),
+                score: scorePair(categories)
+            });
+        }
+    }
+    return pairs;
+}
+function collectPublicSurfacePairs(changes, budget, warnings) {
+    const removed = changes.filter((c) => c.domain === "publicApis" && c.status === "removed");
+    const added = changes.filter((c) => c.domain === "publicApis" && c.status === "added");
+    const pairs = [];
+    for (const rem of removed) {
+        for (const add of added) {
+            if (budget.remaining-- <= 0) {
+                warnings.push("candidate_work_budget_exhausted");
+                return pairs;
+            }
+            const categories = new Set();
+            const reasons = [];
+            const facets = [];
+            if (rem.packageId && add.packageId && rem.packageId === add.packageId) {
+                categories.add("package_continuity");
+                reasons.push("package_continuity");
+            }
+            if (rem.name && add.name && rem.name === add.name) {
+                categories.add("exported_name");
+                reasons.push("exported_name_match");
+                if (rem.importPath !== add.importPath)
+                    facets.push("import_path_changed");
+            }
+            if (rem.importPath && add.importPath && rem.importPath === add.importPath) {
+                categories.add("import_path");
+                reasons.push("import_path_match");
+                if (rem.name !== add.name)
+                    facets.push("exported_name_changed");
+            }
+            if (!sufficientEvidence(categories))
+                continue;
+            pairs.push({
+                rem,
+                add,
+                domain: "publicApis",
+                reasons,
+                categories: [...categories],
+                facets,
+                kind: classifyKind(rem, add, reasons),
+                score: scorePair(categories)
+            });
+        }
+    }
+    return pairs;
+}
+function collectFilePairs(changes, base, head, budget, warnings) {
+    const removed = changes.filter((c) => c.domain === "files" && c.status === "removed");
+    const added = changes.filter((c) => c.domain === "files" && c.status === "added");
+    const baseIdx = indexDomain("files", base);
+    const headIdx = indexDomain("files", head);
+    const pairs = [];
+    for (const rem of removed) {
+        const baseRec = baseIdx.get(rem.baseRecordId ?? rem.modulePath ?? "");
+        for (const add of added) {
+            if (budget.remaining-- <= 0) {
+                warnings.push("candidate_work_budget_exhausted");
+                return pairs;
+            }
+            const headRec = headIdx.get(add.headRecordId ?? add.modulePath ?? "");
+            const categories = new Set();
+            const reasons = [];
+            const facets = [];
+            const baseHash = baseRec?.hash;
+            const headHash = headRec?.hash;
+            if (baseHash && headHash && baseHash === headHash) {
+                categories.add("implementation_fingerprint");
+                reasons.push("content_hash_match");
+            }
+            if (rem.packageId && add.packageId && rem.packageId === add.packageId) {
+                categories.add("package_continuity");
+                reasons.push("package_continuity");
+            }
+            const remBase = (rem.modulePath ?? rem.baseRecordId ?? "").split(/[/\\]/).pop();
+            const addBase = (add.modulePath ?? add.headRecordId ?? "").split(/[/\\]/).pop();
+            if (remBase && addBase && remBase === addBase) {
+                reasons.push("basename_match");
+                facets.push("file_path_changed");
+            }
+            // Require content hash + package (basename alone insufficient)
+            if (!categories.has("implementation_fingerprint") || !categories.has("package_continuity"))
+                continue;
+            pairs.push({
+                rem,
+                add,
+                domain: "files",
+                reasons,
+                categories: [...categories],
+                facets,
+                kind: "probable_move",
+                score: scorePair(categories)
+            });
+        }
+    }
+    return pairs;
+}
+/**
+ * Resolve eligible pairs globally: do not greedily consume added IDs per removed record.
+ */
+function resolveAmbiguity(pairs) {
+    const byRemoved = new Map();
+    const byAdded = new Map();
+    for (const pair of pairs) {
+        const rk = `${pair.domain}|${pair.rem.baseRecordId}`;
+        const ak = `${pair.domain}|${pair.add.headRecordId}`;
+        byRemoved.set(rk, [...(byRemoved.get(rk) ?? []), pair]);
+        byAdded.set(ak, [...(byAdded.get(ak) ?? []), pair]);
+    }
+    const out = [];
+    const emitted = new Set();
+    const removedKeys = [...byRemoved.keys()].sort();
+    for (const rk of removedKeys) {
+        const candidates = (byRemoved.get(rk) ?? []).sort((a, b) => b.score - a.score ||
+            (a.add.headRecordId ?? "").localeCompare(b.add.headRecordId ?? ""));
+        const limited = candidates.slice(0, MAX_PER_REMOVED);
+        for (const pair of limited) {
+            const ak = `${pair.domain}|${pair.add.headRecordId}`;
+            const remCount = limited.length;
+            const addCount = (byAdded.get(ak) ?? []).length;
+            const ambiguous = remCount > 1 || addCount > 1;
+            const idKey = `${pair.domain}|${pair.rem.baseRecordId}|${pair.add.headRecordId}|${pair.kind}`;
+            if (emitted.has(idKey))
+                continue;
+            emitted.add(idKey);
+            out.push({
+                id: "", // filled by caller with comparisonId
+                candidateKind: ambiguous ? "ambiguous_candidate" : pair.kind,
+                domain: pair.domain,
+                baseRecordId: pair.rem.baseRecordId,
+                headRecordId: pair.add.headRecordId,
+                confidence: ambiguous ? "ambiguous" : pair.score >= 50 ? "high" : "medium",
+                evidenceReasons: pair.reasons,
+                conflictingEvidence: ambiguous
+                    ? [
+                        ...(remCount > 1 ? ["multiple_eligible_head_records"] : []),
+                        ...(addCount > 1 ? ["multiple_eligible_base_records"] : [])
+                    ]
+                    : [],
+                alternativeCandidateIds: limited
+                    .filter((p) => p.add.headRecordId !== pair.add.headRecordId)
+                    .map((p) => p.add.headRecordId),
+                ambiguity: ambiguous,
+                transitionFacets: pair.facets
+            });
+        }
+    }
+    return out;
+}
+export function matchAllTransitionCandidates(comparisonId, changes, collisions, catalogues) {
+    const budget = { remaining: GLOBAL_BUDGET };
+    const warnings = [];
+    const base = catalogues?.base;
+    const head = catalogues?.head;
+    const pairs = [
+        ...collectPublicSurfacePairs(changes, budget, warnings),
+        ...(base && head ? collectDeclarationPairs(comparisonId, changes, base, head, budget, warnings) : []),
+        ...(base && head ? collectFilePairs(changes, base, head, budget, warnings) : [])
+    ];
+    const resolved = resolveAmbiguity(pairs);
+    const candidates = [];
+    for (const partial of resolved.sort((a, b) => a.domain.localeCompare(b.domain) ||
+        a.baseRecordId.localeCompare(b.baseRecordId) ||
+        a.headRecordId.localeCompare(b.headRecordId))) {
+        const id = changeIdentityId({
+            comparisonId,
+            domain: partial.domain,
+            baseRecordId: partial.baseRecordId,
+            headRecordId: partial.headRecordId,
+            factualChangeKind: "modified",
+            discriminator: partial.ambiguity
+                ? `ambiguous_${partial.candidateKind}:${partial.headRecordId}`
+                : partial.candidateKind
+        });
+        collisions.register(id, `${comparisonId}|cand|${partial.domain}|${partial.baseRecordId}|${partial.headRecordId}`);
+        const identityDiscriminator = partial.ambiguity
+            ? `ambiguous_${partial.candidateKind}:${partial.headRecordId}`
+            : partial.candidateKind;
+        candidates.push({ ...partial, id, identityDiscriminator });
+    }
+    if (warnings.includes("candidate_work_budget_exhausted")) {
+        // incomplete analysis — do not emit high-confidence results
+        for (const c of candidates) {
+            if (c.confidence === "high")
+                c.confidence = "medium";
+            c.conflictingEvidence = [...c.conflictingEvidence, "candidate_analysis_incomplete"];
+        }
+    }
+    return {
+        candidates: candidates.sort((a, b) => a.id.localeCompare(b.id)),
+        warnings: [...new Set(warnings)]
+    };
+}
+/** @deprecated Use matchAllTransitionCandidates */
+export function matchPublicSurfaceTransitions(comparisonId, changes, collisions) {
+    return matchAllTransitionCandidates(comparisonId, changes, collisions).candidates.filter((c) => c.domain === "publicApis");
+}

package/dist/comparison/compare.d.ts

@@ -0,0 +1,15 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import { recordKey } from "./projections.js";
+import type { ComparisonOptions, ComparisonSnapshot, ComparisonError } from "./schema.js";
+export type CompareResult = {
+    ok: true;
+    comparison: ComparisonSnapshot;
+} | {
+    ok: false;
+    error: ComparisonError;
+};
+/**
+ * Compare two in-memory Schema 2 catalogues deterministically.
+ */
+export declare function compareCatalogues(base: CatalogueSnapshot, head: CatalogueSnapshot, options?: ComparisonOptions): CompareResult;
+export { recordKey };

package/dist/comparison/compare.js

@@ -0,0 +1,240 @@
+import { MAPWRIGHT_GENERATOR_VERSION } from "../catalogue/version.js";
+import { changeIdentityId, comparisonIdentityId, ComparisonCollisionTracker, encodeComparisonPreimage } from "./identity.js";
+import { indexDomain, projectFacets, displayFields, recordKey } from "./projections.js";
+import { orderChangeRecords } from "./ordering.js";
+import { validateCataloguePair } from "./validate.js";
+import { validateReferentialIntegrity } from "./integrity.js";
+import { analyzePublicApiCompatibility } from "./compatibility.js";
+import { matchAllTransitionCandidates } from "./candidates.js";
+import { normalizeEndpointKind } from "./relationshipPolicy.js";
+import { COMPARISON_SCHEMA_VERSION, CHANGE_CONTRACT_VERSION, COMPATIBILITY_RULE_VERSION, COMPARISON_IDENTITY_SCHEME, COMPARISON_PROJECTION_VERSION, CANDIDATE_DETECTION_POLICY_VERSION } from "./version.js";
+import { DEFAULT_COMPARISON_OPTIONS } from "./schema.js";
+function emptyUnchanged() {
+    return {
+        packages: 0,
+        files: 0,
+        symbols: 0,
+        publicApis: 0,
+        tests: 0,
+        examples: 0,
+        capabilities: 0,
+        relationships: 0,
+        diagnostics: 0
+    };
+}
+function buildGraphIndex(snapshot) {
+    const seen = new Set();
+    const edges = [];
+    for (const r of snapshot.relationships) {
+        const fromKind = normalizeEndpointKind(r.from.kind);
+        const toKind = normalizeEndpointKind(r.to.kind);
+        const fromId = r.from.id;
+        const toId = r.to.id;
+        // Prefer canonical symbol endpoints when present on symbol records
+        let canonicalFrom = fromId;
+        let canonicalTo = toId;
+        if (fromKind === "symbol") {
+            const sym = snapshot.symbols.find((s) => s.id === fromId);
+            if (sym?.canonicalSymbolId)
+                canonicalFrom = sym.canonicalSymbolId;
+        }
+        if (toKind === "symbol") {
+            const sym = snapshot.symbols.find((s) => s.id === toId);
+            if (sym?.canonicalSymbolId)
+                canonicalTo = sym.canonicalSymbolId;
+        }
+        const key = [
+            r.type,
+            fromKind,
+            canonicalFrom,
+            toKind,
+            canonicalTo,
+            r.localDiscriminant ?? ""
+        ].join("|");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({
+            id: r.id,
+            type: r.type,
+            fromKind,
+            fromId: canonicalFrom,
+            toKind,
+            toId: canonicalTo,
+            provenance: r.provenance?.source,
+            localDiscriminant: r.localDiscriminant ?? null,
+            confidence: r.confidence
+        });
+    }
+    return edges.sort((a, b) => `${a.type}|${a.fromKind}:${a.fromId}|${a.toKind}:${a.toId}`.localeCompare(`${b.type}|${b.fromKind}:${b.fromId}|${b.toKind}:${b.toId}`));
+}
+/**
+ * Compare two in-memory Schema 2 catalogues deterministically.
+ */
+export function compareCatalogues(base, head, options = DEFAULT_COMPARISON_OPTIONS) {
+    const validated = validateCataloguePair(base, head);
+    if (!validated.ok) {
+        return validated;
+    }
+    const baseIntegrity = validateReferentialIntegrity(base, "base");
+    if (baseIntegrity)
+        return { ok: false, error: baseIntegrity };
+    const headIntegrity = validateReferentialIntegrity(head, "head");
+    if (headIntegrity)
+        return { ok: false, error: headIntegrity };
+    const comparisonId = comparisonIdentityId({
+        baseCatalogueId: base.catalogueId,
+        headCatalogueId: head.catalogueId,
+        options
+    });
+    const collisions = new ComparisonCollisionTracker();
+    collisions.register(comparisonId, encodeComparisonPreimage([comparisonId, base.catalogueId, head.catalogueId]));
+    const changes = [];
+    const unchanged = emptyUnchanged();
+    const domains = options.enabledDomains;
+    for (const domain of domains) {
+        const baseMap = indexDomain(domain, base);
+        const headMap = indexDomain(domain, head);
+        const keys = new Set([...baseMap.keys(), ...headMap.keys()]);
+        for (const key of [...keys].sort()) {
+            const baseRec = baseMap.get(key);
+            const headRec = headMap.get(key);
+            if (baseRec && !headRec) {
+                const id = changeIdentityId({
+                    comparisonId,
+                    domain,
+                    baseRecordId: key,
+                    headRecordId: null,
+                    factualChangeKind: "removed"
+                });
+                collisions.register(id, `${comparisonId}|${domain}|${key}|removed`);
+                changes.push({
+                    id,
+                    domain,
+                    status: "removed",
+                    baseRecordId: key,
+                    headRecordId: null,
+                    identityDiscriminator: null,
+                    facets: [],
+                    ...displayFields(domain, baseRec)
+                });
+                continue;
+            }
+            if (!baseRec && headRec) {
+                const id = changeIdentityId({
+                    comparisonId,
+                    domain,
+                    baseRecordId: null,
+                    headRecordId: key,
+                    factualChangeKind: "added"
+                });
+                collisions.register(id, `${comparisonId}|${domain}|${key}|added`);
+                changes.push({
+                    id,
+                    domain,
+                    status: "added",
+                    baseRecordId: null,
+                    headRecordId: key,
+                    identityDiscriminator: null,
+                    facets: [],
+                    ...displayFields(domain, headRec)
+                });
+                continue;
+            }
+            if (baseRec && headRec) {
+                const facets = projectFacets(domain, baseRec, headRec);
+                if (facets.length === 0) {
+                    unchanged[domain] += 1;
+                    if (options.includeUnchanged) {
+                        const id = changeIdentityId({
+                            comparisonId,
+                            domain,
+                            baseRecordId: key,
+                            headRecordId: key,
+                            factualChangeKind: "unchanged"
+                        });
+                        collisions.register(id, `${comparisonId}|${domain}|${key}|unchanged`);
+                        changes.push({
+                            id,
+                            domain,
+                            status: "unchanged",
+                            baseRecordId: key,
+                            headRecordId: key,
+                            identityDiscriminator: null,
+                            facets: [],
+                            ...displayFields(domain, headRec)
+                        });
+                    }
+                }
+                else {
+                    const id = changeIdentityId({
+                        comparisonId,
+                        domain,
+                        baseRecordId: key,
+                        headRecordId: key,
+                        factualChangeKind: "modified"
+                    });
+                    collisions.register(id, `${comparisonId}|${domain}|${key}|modified`);
+                    changes.push({
+                        id,
+                        domain,
+                        status: "modified",
+                        baseRecordId: key,
+                        headRecordId: key,
+                        identityDiscriminator: null,
+                        facets,
+                        ...displayFields(domain, headRec)
+                    });
+                }
+            }
+        }
+    }
+    const orderedChanges = orderChangeRecords(changes);
+    const { candidates, warnings: candidateWarnings } = matchAllTransitionCandidates(comparisonId, orderedChanges, collisions, { base, head });
+    const { findings, aggregate } = analyzePublicApiCompatibility({
+        comparisonId,
+        changes: orderedChanges,
+        candidates,
+        base,
+        head,
+        collisions
+    });
+    return {
+        ok: true,
+        comparison: {
+            manifest: {
+                comparisonSchemaVersion: COMPARISON_SCHEMA_VERSION,
+                changeContractVersion: CHANGE_CONTRACT_VERSION,
+                compatibilityRuleVersion: COMPATIBILITY_RULE_VERSION,
+                comparisonIdentityScheme: COMPARISON_IDENTITY_SCHEME,
+                comparisonProjectionVersion: COMPARISON_PROJECTION_VERSION,
+                candidateDetectionPolicyVersion: CANDIDATE_DETECTION_POLICY_VERSION,
+                comparisonId,
+                baseCatalogueId: base.catalogueId,
+                headCatalogueId: head.catalogueId,
+                baseGeneratorVersion: base.generator?.version ?? null,
+                headGeneratorVersion: head.generator?.version ?? null,
+                comparisonGeneratorVersion: MAPWRIGHT_GENERATOR_VERSION,
+                options,
+                counts: {
+                    added: orderedChanges.filter((c) => c.status === "added").length,
+                    removed: orderedChanges.filter((c) => c.status === "removed").length,
+                    modified: orderedChanges.filter((c) => c.status === "modified").length,
+                    unchanged,
+                    compatibilityFindings: findings.length,
+                    candidates: candidates.length
+                },
+                aggregateCompatibility: aggregate
+            },
+            changes: orderedChanges,
+            compatibilityFindings: findings,
+            candidates,
+            graphIndex: {
+                base: buildGraphIndex(base),
+                head: buildGraphIndex(head)
+            },
+            warnings: candidateWarnings.length > 0 ? candidateWarnings : undefined
+        }
+    };
+}
+export { recordKey };

package/dist/comparison/compatibility.d.ts

@@ -0,0 +1,26 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import { type ComparisonCollisionTracker } from "./identity.js";
+import type { ChangeRecord, CompatibilityFinding, CompatibilityClassification, TransitionCandidate } from "./schema.js";
+type Stability = "stable" | "experimental" | "deprecated" | "internal" | string;
+/**
+ * Versioned stability transition matrix (compatibilityRuleVersion 1 corrective).
+ */
+export declare function classifyStabilityTransition(from: Stability | null | undefined, to: Stability | null | undefined): {
+    classification: CompatibilityClassification;
+    ruleId: string;
+} | null;
+/**
+ * Conservative public API compatibility analysis (rule version 1).
+ */
+export declare function analyzePublicApiCompatibility(input: {
+    comparisonId: string;
+    changes: ChangeRecord[];
+    candidates: TransitionCandidate[];
+    base: CatalogueSnapshot;
+    head: CatalogueSnapshot;
+    collisions: ComparisonCollisionTracker;
+}): {
+    findings: CompatibilityFinding[];
+    aggregate: CompatibilityClassification | null;
+};
+export {};