@descryy/core 0.1.0

package/dist/multipr/migration-heads.js

@@ -0,0 +1,212 @@
+/**
+ * §14.6 — two open changes each adding a migration from the same parent, caught
+ * before the merge that turns it into a broken deploy.
+ *
+ * ## What this computes, and why it is the real computation rather than a proxy
+ *
+ * Migrations form a DAG: each revision names its parent(s), and a **head** is a
+ * revision nothing else descends from. Every migration runner refuses to run
+ * with more than one — Alembic's *"Multiple head revisions are present"* is the
+ * canonical spelling, and the equivalent exists in every tool that versions
+ * migrations at all.
+ *
+ * The obvious shortcut is to group migrations by declared parent and flag any
+ * parent claimed by two different changes. **That is wrong**, and wrong in the
+ * direction that produces false findings: a merge migration declaring two
+ * parents exists precisely to resolve such a fork, and the shortcut cannot see
+ * it. So this computes heads over the union the way the runner does. The check
+ * is only worth its Class A ceiling if it computes what the tool computes.
+ *
+ * ## Nothing here names a framework, and that is §14.6's own argument
+ *
+ * §14.6 says the SQL adapter makes this work identically across ORMs and raw-SQL
+ * tooling "rather than being written once per framework". So the input is a
+ * revision, its declared parents and where it came from — the shape every
+ * migration tool has, whatever it calls the fields. Reading `down_revision` out
+ * of an Alembic file, `dependencies` out of a Django one or a timestamp chain
+ * out of a Rails one is producer work. Rule 1: none of those words appear below
+ * this sentence.
+ *
+ * ## The class, and a disagreement with §15.2 that is already settled
+ *
+ * §15.2 lists "migration head conflict" as **Class A — deterministically
+ * verifiable, a structural fact, not an inference**. That is right about the
+ * *inference*: given both parent lists, the conclusion follows with no
+ * judgement at all. It is not right unconditionally, because the parent lists
+ * still have to be obtained, and reading `down_revision` with a regex is R0
+ * evidence however certain the arithmetic on top of it.
+ *
+ * This is the same disagreement the env/config check hit, and §15.3 already
+ * records the resolution: **the Class column is a ceiling, not a floor** —
+ * "corrected after the env/config check was built and the two disagreed". So A
+ * is what this check reaches when the records come from the framework's own
+ * migration history (DEC-115's promotion path, R3), and a source-read set lands
+ * where its evidence lands. DEC-058 at the finding level: the claim carries the
+ * resolution of its own evidence, not of the run.
+ *
+ * That is now the second check to disagree with §15.2's column in the same
+ * direction, which is worth someone's attention as a pattern rather than as two
+ * incidents.
+ *
+ * ## An unread migration is not a migration with no parents
+ *
+ * An initial migration genuinely has zero parents. A migration whose parent line
+ * could not be read has *unknown* parents. Both are "no parents in the record",
+ * and collapsing them silently corrupts the head computation — an unread
+ * migration might be exactly the merge that resolves the fork being reported.
+ *
+ * So `parents` is `readonly string[] | "unknown"` and the empty array cannot be
+ * used to mean the second thing. The distinction is made unrepresentable at the
+ * type rather than handled downstream, which is the repair
+ * `bench/lib/README.md` asks for at construction time rather than afterwards.
+ */
+import { reliabilityCap, reliabilityNote } from "@descryy/ir";
+/**
+ * Head conflicts across a set of in-flight changes.
+ *
+ * Pure over records: no store, no graph, no framework. The producer that reads
+ * migration files decides `resolution`; this function propagates it.
+ */
+export function findMigrationHeadConflicts(records, options = {}) {
+    const notes = [];
+    const changes = new Set(records.map((r) => r.prId)).size;
+    if (records.length === 0) {
+        notes.push("No change in this set adds a migration, so no head computation was performed. That is " +
+            "not a finding that the migrations are consistent — there are none to be consistent.");
+        return {
+            conflict: null,
+            dependencies: [],
+            duplicateRevisions: [],
+            analysed: false,
+            complete: true,
+            checked: { changes, migrations: 0, withUnknownParents: 0, heads: 0 },
+            notes,
+        };
+    }
+    const unknown = records.filter((r) => r.parents === "unknown");
+    const known = records.filter((r) => r.parents !== "unknown");
+    const complete = unknown.length === 0;
+    // Two changes minting the same revision id is a defect on its own, and it also
+    // makes the DAG ill-formed — so it is detected before the heads are computed
+    // rather than being allowed to distort them.
+    const byRevision = new Map();
+    for (const r of records) {
+        const list = byRevision.get(r.revision);
+        if (list === undefined)
+            byRevision.set(r.revision, [r]);
+        else
+            list.push(r);
+    }
+    const duplicateRevisions = [...byRevision]
+        .filter(([, rs]) => new Set(rs.map((r) => r.prId)).size > 1)
+        .map(([revision, rs]) => ({ revision, prIds: [...new Set(rs.map((r) => r.prId))].sort() }));
+    // A revision is a head when nothing in the merged set declares it as a parent.
+    // Only revisions the set DECLARES are candidates: a parent that nothing here
+    // declares lives in the base history and has, by construction, at least one
+    // child — the migration that named it.
+    const claimedAsParent = new Set();
+    for (const r of known) {
+        for (const p of r.parents)
+            claimedAsParent.add(p);
+    }
+    const heads = known
+        .filter((r) => !claimedAsParent.has(r.revision))
+        .map((r) => ({ revision: r.revision, prId: r.prId, file: r.file }))
+        .sort((a, b) => a.revision.localeCompare(b.revision));
+    // The weakest record decides the class — the same pair rule overlap scoring
+    // uses, for the same reason: a claim resting on several observations cannot
+    // be asserted at the strength of its best one.
+    const weakest = known.reduce((min, r) => (r.resolution < min ? r.resolution : min), 4);
+    const evidenceClass = reliabilityCap(weakest, true);
+    // A revision identifier is a name, so the R2 carve-out applies — but a partial
+    // DAG makes the conclusion conditional on something unread, which no amount of
+    // resolution on the read records repairs.
+    const reliability = complete ? evidenceClass : "C";
+    let disclosure = reliabilityNote(weakest, true);
+    if (!complete) {
+        disclosure +=
+            ` ${unknown.length} migration(s) in this set had parents that could not be read, so the ` +
+                "revision graph is partial. One of them may be the merge that resolves this, which is " +
+                "why this is reported as a possibility rather than as the structural fact it would " +
+                "otherwise be.";
+    }
+    const conflict = heads.length > 1
+        ? {
+            prIds: [...new Set(heads.map((h) => h.prId))].sort(),
+            heads,
+            reliability,
+            disclosure,
+        }
+        : null;
+    // A migration whose parent only exists inside another open change. Not a
+    // conflict — the merged set still has one head — but merging in the wrong
+    // order leaves a revision pointing at a parent that is not there yet.
+    const revisionOwner = new Map();
+    for (const r of records)
+        if (!revisionOwner.has(r.revision))
+            revisionOwner.set(r.revision, r.prId);
+    const dependencies = [];
+    for (const r of known) {
+        for (const parent of r.parents) {
+            const owner = revisionOwner.get(parent);
+            if (owner === undefined || owner === r.prId)
+                continue;
+            dependencies.push({
+                prId: r.prId,
+                revision: r.revision,
+                dependsOnRevision: parent,
+                dependsOnPrId: owner,
+                reliability,
+                disclosure,
+            });
+        }
+    }
+    if (conflict !== null) {
+        notes.push(`Merging these ${conflict.prIds.length} change(s) leaves ${heads.length} migration heads. ` +
+            "A migration runner refuses to advance with more than one, so this fails at deploy " +
+            "time rather than at merge time — which is the point of computing it now.");
+        notes.push(disclosure);
+    }
+    if (!complete) {
+        notes.push(`${unknown.length} of ${records.length} migration(s) had unreadable parent revisions and ` +
+            `were excluded from the graph: ${unknown
+                .slice(0, 5)
+                .map((r) => r.file)
+                .join(", ")}${unknown.length > 5 ? ", …" : ""}. They were not treated as having no ` +
+            "parents — an initial migration and an unread one are different, and conflating them " +
+            "would silently change the head count.");
+    }
+    if (duplicateRevisions.length > 0) {
+        notes.push(`${duplicateRevisions.length} revision identifier(s) are declared by more than one change. ` +
+            "Whatever the head count says, two migrations cannot share an identifier.");
+    }
+    if (options.baseHead === undefined) {
+        notes.push("The base branch's current head was not supplied, so migrations branching from stale " +
+            "history were not checked. Only conflicts between the supplied changes were computed.");
+    }
+    else {
+        const stale = known.filter((r) => r.parents.length > 0 &&
+            !r.parents.includes(options.baseHead) &&
+            !r.parents.some((p) => revisionOwner.has(p)));
+        if (stale.length > 0) {
+            notes.push(`${stale.length} migration(s) descend from a revision that is neither the base head nor ` +
+                "added by any change in this set, so they were written against older history: " +
+                `${stale.map((r) => r.file).join(", ")}.`);
+        }
+    }
+    return {
+        conflict,
+        dependencies,
+        duplicateRevisions,
+        analysed: true,
+        complete,
+        checked: {
+            changes,
+            migrations: records.length,
+            withUnknownParents: unknown.length,
+            heads: heads.length,
+        },
+        notes,
+    };
+}
+//# sourceMappingURL=migration-heads.js.map

package/dist/multipr/migration-heads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-heads.js","sourceRoot":"","sources":["../../src/multipr/migration-heads.ts"],"names":[],"mappings":"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"}

package/dist/multipr/overlap.d.ts

@@ -0,0 +1,186 @@
+/**
+ * §14.3 — where two in-flight changes touch the same thing, and whether that
+ * matters.
+ *
+ * ## A shared node alone is not a conflict
+ *
+ * §14.3 says this outright and it is the whole design. At real team scale many
+ * pull requests incidentally touch the same low-importance code — a shared
+ * logging helper, a barrel file, a constants module. A tool that reports every
+ * shared node reports mostly noise, and a developer who has dismissed six
+ * incidental overlaps will dismiss the seventh without reading it.
+ *
+ * So severity is a product of *what* is shared, not *that* something is:
+ *
+ *     score(node) = impact × NODE_TYPE_WEIGHT[type]
+ *
+ * A shared `API_ENDPOINT` is two changes to one contract. A shared `FUNCTION`
+ * in a utility module is two people editing a file. The weights are the only
+ * thing separating them and they are tuning values, labelled as such.
+ *
+ * ## Resolution is carried per node, and that is §14.2's one addition
+ *
+ * §14.2 adds `Resolution` to the persisted row with a reason: *so overlap
+ * severity is not computed across incomparable evidence*. If one change's node
+ * was resolved by a type checker and the other's by syntax alone, an overlap
+ * asserted at the stronger level claims more than half of its own evidence
+ * supports.
+ *
+ * The rule follows DEC-058 exactly — a claim carries the resolution of ITS OWN
+ * evidence, not of the run that produced it. Here the claim rests on two
+ * observations, so it carries **the weaker of the two**, and the finding's
+ * reliability class follows from that rather than from either side alone.
+ *
+ * ## What this deliberately does not do
+ *
+ * §14.4's mechanical-versus-semantic classification needs the actual diff lines
+ * at the shared node, which this module never sees. It reports the overlap and
+ * stops; classifying it — and the auto-apply path that is the single documented
+ * exception to approval-before-code-change — belongs where the diff is.
+ * Guessing "mechanical" without reading the lines would be the one place in
+ * this system where a wrong guess edits somebody's branch.
+ */
+import type { NodeType, ResolutionLevel } from "@descryy/ir";
+import type { ReliabilityClass } from "@descryy/ir";
+/** How a change touched a node. §14.2's `DiffType`. */
+export type DiffType = "added" | "modified" | "deleted";
+/**
+ * One row of a change's scoped subgraph — §14.2's shape, without persistence.
+ *
+ * Defined here rather than in a store module so overlap can be computed and
+ * tested with no database, the same reason `AdjacencyProvider` exists.
+ */
+export interface PrScopeEntry {
+    readonly nodeId: string;
+    readonly nodeType: NodeType;
+    /** Present when known; used only for reporting, never for identity. */
+    readonly file?: string | undefined;
+    /** §12.4's impact score, for this change. */
+    readonly impactScore: number;
+    /** §12.7's tier, for this change. */
+    readonly tier: number;
+    readonly diffType: DiffType;
+    /** The level the graph reached for this node **in this change's run**. */
+    readonly resolution: ResolutionLevel;
+}
+export interface PrScope {
+    /** Whatever identifies the change — a PR number, a branch, a ref. */
+    readonly prId: string;
+    /** Part of scope identity: node ids are repo-scoped, so scopes are too. */
+    readonly repo: string;
+    readonly entries: readonly PrScopeEntry[];
+    /** When this scope was computed, for §14.2's staleness handling. */
+    readonly computedAt: number;
+    /** The head commit of the change itself. Identifies it; never compares it. */
+    readonly headSha: string;
+    /**
+     * The commit **the graph** was at when this scope was computed.
+     *
+     * Not the same as `headSha`, and the distinction is load-bearing: two scopes
+     * are comparable only when this agrees. A single `baseSha` field stood here
+     * first, described as "the base commit it was computed against", which is
+     * ambiguous between the two and would have let a comparison key on the wrong
+     * one. §14.2's column comment is what caught it.
+     */
+    readonly graphCommitSha: string;
+}
+/** One node two changes both touch. */
+export interface SharedNode {
+    readonly nodeId: string;
+    readonly nodeType: NodeType;
+    readonly file?: string | undefined;
+    /** `max` of the two impact scores — see `impactOfPair`. */
+    readonly impact: number;
+    readonly weight: number;
+    readonly score: number;
+    /** How each side touched it. Two deletions and two additions differ. */
+    readonly diffTypes: readonly [DiffType, DiffType];
+    /** The **weaker** of the two resolutions. */
+    readonly resolution: ResolutionLevel;
+    readonly reliability: ReliabilityClass;
+    /** True when the two sides disagree about how well this node was resolved. */
+    readonly resolutionMismatch: boolean;
+}
+export interface OverlapFinding {
+    readonly a: string;
+    readonly b: string;
+    /** Every shared node, including those below the threshold. */
+    readonly overlapSize: number;
+    /** Shared nodes at or above the threshold, strongest first. */
+    readonly surfaced: readonly SharedNode[];
+    /** Sum of surfaced scores — see the note on §14.3's formula. */
+    readonly conflictScore: number;
+    /** The sentence a report must carry with this finding. */
+    readonly disclosure: string;
+}
+/** A pair that was never compared, and why. Never silently absent. */
+export interface IncomparablePair {
+    readonly a: string;
+    readonly b: string;
+    readonly reason: "different-graph" | "different-repo";
+}
+export interface OverlapReport {
+    readonly findings: readonly OverlapFinding[];
+    /** The count before `limit` capped it — P27's disclosed remainder: a structured field, not only a prose note. */
+    readonly findingsTotal: number;
+    readonly checked: {
+        readonly scopes: number;
+        readonly pairs: number;
+        /** Pairs sharing at least one node, before the threshold. */
+        readonly pairsOverlapping: number;
+        /** Shared nodes dropped for scoring below the threshold. */
+        readonly belowThreshold: number;
+        /** Pairs refused before comparison — see `incomparable`. */
+        readonly incomparable: number;
+    };
+    /**
+     * Pairs that could not be compared at all.
+     *
+     * **An incomparable pair and a non-conflicting pair produce the same empty
+     * overlap**, so they are separated here rather than left to be inferred from
+     * a count that does not distinguish them.
+     */
+    readonly incomparable: readonly IncomparablePair[];
+    readonly notes: readonly string[];
+}
+/**
+ * §14.3's `NodeTypeWeight`. **Tuning values, and labelled as such.**
+ *
+ * The architecture gives the shape and one worked contrast — a shared utility
+ * function scores low, a shared API contract scores high — and fixes no
+ * numbers. These are a defensible starting point and are expected to move once
+ * there is data. The ordering is the part that is argued:
+ *
+ * - **Contract surfaces highest.** `API_ENDPOINT` and `API_ROUTE` are the join
+ *   between two services; two changes to one is the case where a merge compiles
+ *   and the system breaks.
+ * - **Schema next.** A `DATABASE_TABLE` or `DATABASE_COLUMN` touched twice is
+ *   two migrations against one object, which §14.6 checks separately and which
+ *   fails at merge rather than at review.
+ * - **Types above callables.** Two changes to a `DTO` or `MODEL` shape reach
+ *   every consumer; two changes to one `FUNCTION` reach its callers.
+ * - **`FILE` lowest of the real types.** File-level overlap is what every naive
+ *   tool already reports and it is the noise this weighting exists to suppress.
+ *
+ * Exhaustive over the frozen vocabulary on purpose: `Record<NodeType, number>`
+ * means adding a node type is a compile error here rather than a silent zero,
+ * and a silent zero would make the new type invisible to conflict detection
+ * without any test failing.
+ */
+export declare const NODE_TYPE_WEIGHTS: Readonly<Record<NodeType, number>>;
+/** Default score below which a shared node is incidental rather than a conflict. */
+export declare const DEFAULT_CONFLICT_THRESHOLD = 0.3;
+export interface OverlapOptions {
+    readonly threshold?: number;
+    readonly weights?: Readonly<Record<NodeType, number>>;
+    /** Cap on findings, per rule 5. Truncation is reported. */
+    readonly limit?: number;
+}
+/**
+ * Overlaps between every pair of in-flight changes.
+ *
+ * Pure over scopes, so it needs no store and no graph. §14.2's persistence is a
+ * layer above this, not a prerequisite for it.
+ */
+export declare function findOverlaps(scopes: readonly PrScope[], options?: OverlapOptions): OverlapReport;
+//# sourceMappingURL=overlap.d.ts.map

package/dist/multipr/overlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap.d.ts","sourceRoot":"","sources":["../../src/multipr/overlap.ts"],"names":[],"mappings":"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"}

package/dist/multipr/overlap.js

@@ -0,0 +1,254 @@
+/**
+ * §14.3 — where two in-flight changes touch the same thing, and whether that
+ * matters.
+ *
+ * ## A shared node alone is not a conflict
+ *
+ * §14.3 says this outright and it is the whole design. At real team scale many
+ * pull requests incidentally touch the same low-importance code — a shared
+ * logging helper, a barrel file, a constants module. A tool that reports every
+ * shared node reports mostly noise, and a developer who has dismissed six
+ * incidental overlaps will dismiss the seventh without reading it.
+ *
+ * So severity is a product of *what* is shared, not *that* something is:
+ *
+ *     score(node) = impact × NODE_TYPE_WEIGHT[type]
+ *
+ * A shared `API_ENDPOINT` is two changes to one contract. A shared `FUNCTION`
+ * in a utility module is two people editing a file. The weights are the only
+ * thing separating them and they are tuning values, labelled as such.
+ *
+ * ## Resolution is carried per node, and that is §14.2's one addition
+ *
+ * §14.2 adds `Resolution` to the persisted row with a reason: *so overlap
+ * severity is not computed across incomparable evidence*. If one change's node
+ * was resolved by a type checker and the other's by syntax alone, an overlap
+ * asserted at the stronger level claims more than half of its own evidence
+ * supports.
+ *
+ * The rule follows DEC-058 exactly — a claim carries the resolution of ITS OWN
+ * evidence, not of the run that produced it. Here the claim rests on two
+ * observations, so it carries **the weaker of the two**, and the finding's
+ * reliability class follows from that rather than from either side alone.
+ *
+ * ## What this deliberately does not do
+ *
+ * §14.4's mechanical-versus-semantic classification needs the actual diff lines
+ * at the shared node, which this module never sees. It reports the overlap and
+ * stops; classifying it — and the auto-apply path that is the single documented
+ * exception to approval-before-code-change — belongs where the diff is.
+ * Guessing "mechanical" without reading the lines would be the one place in
+ * this system where a wrong guess edits somebody's branch.
+ */
+import { reliabilityCap, reliabilityNote } from "@descryy/ir";
+/**
+ * §14.3's `NodeTypeWeight`. **Tuning values, and labelled as such.**
+ *
+ * The architecture gives the shape and one worked contrast — a shared utility
+ * function scores low, a shared API contract scores high — and fixes no
+ * numbers. These are a defensible starting point and are expected to move once
+ * there is data. The ordering is the part that is argued:
+ *
+ * - **Contract surfaces highest.** `API_ENDPOINT` and `API_ROUTE` are the join
+ *   between two services; two changes to one is the case where a merge compiles
+ *   and the system breaks.
+ * - **Schema next.** A `DATABASE_TABLE` or `DATABASE_COLUMN` touched twice is
+ *   two migrations against one object, which §14.6 checks separately and which
+ *   fails at merge rather than at review.
+ * - **Types above callables.** Two changes to a `DTO` or `MODEL` shape reach
+ *   every consumer; two changes to one `FUNCTION` reach its callers.
+ * - **`FILE` lowest of the real types.** File-level overlap is what every naive
+ *   tool already reports and it is the noise this weighting exists to suppress.
+ *
+ * Exhaustive over the frozen vocabulary on purpose: `Record<NodeType, number>`
+ * means adding a node type is a compile error here rather than a silent zero,
+ * and a silent zero would make the new type invisible to conflict detection
+ * without any test failing.
+ */
+export const NODE_TYPE_WEIGHTS = {
+    API_ENDPOINT: 1.0,
+    API_ROUTE: 1.0,
+    DATABASE_COLUMN: 0.9,
+    DATABASE_TABLE: 0.9,
+    DTO: 0.8,
+    MODEL: 0.8,
+    CLASS: 0.6,
+    COMPONENT: 0.6,
+    PAGE: 0.5,
+    MODULE: 0.5,
+    FUNCTION: 0.4,
+    TEST_CASE: 0.3,
+    FILE: 0.2,
+    // History artefacts. Two changes cannot both "touch" an incident; if these
+    // ever appear in a diff scope something upstream is wrong, and a weight of
+    // zero would hide that rather than surface it.
+    INCIDENT: 0.1,
+    FIX_PATTERN: 0.1,
+};
+/** Default score below which a shared node is incidental rather than a conflict. */
+export const DEFAULT_CONFLICT_THRESHOLD = 0.3;
+/**
+ * The impact a shared node carries is the **higher** of the two.
+ *
+ * A node peripheral to one change and central to the other is a real conflict:
+ * somebody is about to have their central concern edited from underneath them.
+ * Taking the minimum would let a large blast radius be discounted by a
+ * one-line drive-by touching the same node, which is the case most worth
+ * catching.
+ */
+function impactOfPair(a, b) {
+    return Math.max(a.impactScore, b.impactScore);
+}
+/**
+ * Overlaps between every pair of in-flight changes.
+ *
+ * Pure over scopes, so it needs no store and no graph. §14.2's persistence is a
+ * layer above this, not a prerequisite for it.
+ */
+export function findOverlaps(scopes, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_CONFLICT_THRESHOLD;
+    const weights = options.weights ?? NODE_TYPE_WEIGHTS;
+    const limit = options.limit ?? 10;
+    const notes = [];
+    const incomparable = [];
+    let belowThreshold = 0;
+    let pairsOverlapping = 0;
+    let pairs = 0;
+    const byId = scopes.map((s) => ({ scope: s, index: new Map(s.entries.map((e) => [e.nodeId, e])) }));
+    const findings = [];
+    for (let i = 0; i < byId.length; i += 1) {
+        for (let j = i + 1; j < byId.length; j += 1) {
+            pairs += 1;
+            const left = byId[i];
+            const right = byId[j];
+            // Refused BEFORE any node is compared. §14.2's schema puts the graph
+            // commit in the primary key so two graph states of one PR cannot
+            // overwrite each other, and warns that a reader ignoring it "will happily
+            // overlap a scope from last week with one from today and report a
+            // number". That warning is honoured here rather than in the store,
+            // because a caller constructing scopes by hand never touches a store —
+            // and because an incomparable pair returns the same empty overlap a
+            // genuinely non-conflicting one does.
+            const reason = left.scope.repo !== right.scope.repo
+                ? "different-repo"
+                : left.scope.graphCommitSha !== right.scope.graphCommitSha
+                    ? "different-graph"
+                    : null;
+            if (reason !== null) {
+                incomparable.push({ a: left.scope.prId, b: right.scope.prId, reason });
+                continue;
+            }
+            const shared = [];
+            let overlapSize = 0;
+            let mismatches = 0;
+            for (const [nodeId, a] of left.index) {
+                const b = right.index.get(nodeId);
+                if (b === undefined)
+                    continue;
+                overlapSize += 1;
+                // DEC-058 at the pair level: the claim rests on two observations, so it
+                // carries the weaker. Asserting at the stronger would claim more than
+                // half its own evidence supports.
+                const resolution = Math.min(a.resolution, b.resolution);
+                const resolutionMismatch = a.resolution !== b.resolution;
+                if (resolutionMismatch)
+                    mismatches += 1;
+                const impact = impactOfPair(a, b);
+                const weight = weights[a.nodeType];
+                const score = impact * weight;
+                if (score < threshold) {
+                    belowThreshold += 1;
+                    continue;
+                }
+                shared.push({
+                    nodeId,
+                    nodeType: a.nodeType,
+                    file: a.file ?? b.file,
+                    impact,
+                    weight,
+                    score,
+                    diffTypes: [a.diffType, b.diffType],
+                    resolution,
+                    // An overlap is a claim about which symbols two changes both name —
+                    // a name-level fact, not a claim about shapes. R2 therefore permits
+                    // class A here where a shape claim on the same evidence would not.
+                    reliability: reliabilityCap(resolution, true),
+                    resolutionMismatch,
+                });
+            }
+            if (overlapSize > 0)
+                pairsOverlapping += 1;
+            if (shared.length === 0)
+                continue;
+            shared.sort((x, y) => y.score - x.score || x.nodeId.localeCompare(y.nodeId));
+            const weakest = shared.reduce((min, s) => (s.resolution < min ? s.resolution : min), 4);
+            let disclosure = reliabilityNote(weakest, true);
+            if (mismatches > 0) {
+                disclosure +=
+                    ` ${mismatches} of the ${overlapSize} shared node(s) were resolved to different ` +
+                        "levels by the two changes; each is reported at the weaker of the two, because an " +
+                        "overlap asserted at the stronger level would claim more than half its evidence " +
+                        "supports.";
+            }
+            findings.push({
+                a: left.scope.prId,
+                b: right.scope.prId,
+                overlapSize,
+                surfaced: shared,
+                // §14.3 writes `OverlapSize × ImpactScore × NodeTypeWeight`. Read
+                // literally that multiplies a pair-level count by two node-level
+                // quantities, which lets one shared trivial node scale with the size of
+                // an unrelated overlap. Summing the per-node scores keeps the same
+                // intent — more shared, and more important, scores higher — and stays
+                // monotonic in both. The divergence is deliberate and recorded rather
+                // than silently "interpreted".
+                conflictScore: shared.reduce((sum, s) => sum + s.score, 0),
+                disclosure,
+            });
+        }
+    }
+    findings.sort((x, y) => y.conflictScore - x.conflictScore || x.a.localeCompare(y.a));
+    const kept = findings.slice(0, limit);
+    if (findings.length > limit) {
+        notes.push(`${findings.length} overlapping pairs scored above the threshold and the ${kept.length} ` +
+            "highest are reported.");
+    }
+    if (belowThreshold > 0) {
+        notes.push(`${belowThreshold} shared node(s) scored below the conflict threshold and were not ` +
+            "surfaced. A shared node is not a conflict on its own — at team scale many changes " +
+            "incidentally touch the same low-importance code, and reporting all of it is how a " +
+            "reader learns to dismiss the report.");
+    }
+    if (scopes.length < 2) {
+        notes.push("Fewer than two scopes were supplied, so no pair could be compared. That is not a " +
+            "finding that nothing conflicts.");
+    }
+    const differentGraph = incomparable.filter((p) => p.reason === "different-graph").length;
+    if (differentGraph > 0) {
+        notes.push(`${differentGraph} pair(s) were computed against different graph states and were not ` +
+            "compared. A scope is only meaningful against the graph it was computed on; comparing " +
+            "across two answers a different question and returns a plausible answer to it. These " +
+            "pairs are neither conflicting nor clear — they are unexamined, and rescoping both " +
+            "against one graph is what would settle them.");
+    }
+    const differentRepo = incomparable.filter((p) => p.reason === "different-repo").length;
+    if (differentRepo > 0) {
+        notes.push(`${differentRepo} pair(s) belong to different repositories and were not compared. Node ` +
+            "identity is repo-scoped, so such a pair shares no node by construction and would " +
+            "report as conflict-free rather than as unexamined.");
+    }
+    return {
+        findings: kept,
+        findingsTotal: findings.length,
+        checked: {
+            scopes: scopes.length,
+            pairs,
+            pairsOverlapping,
+            belowThreshold,
+            incomparable: incomparable.length,
+        },
+        incomparable,
+        notes,
+    };
+}
+//# sourceMappingURL=overlap.js.map