al-sem 0.0.1

package/src/detectors/d8-commit-in-transaction.ts

@@ -0,0 +1,132 @@
+import type { CombinedGraph } from "../engine/combined-graph.ts";
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import { roleOf } from "../model/entities.ts";
+import type { Routine } from "../model/entities.ts";
+import type { DetectorStats, EvidenceStep, Finding } from "../model/finding.ts";
+import type { RoutineId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+import { fingerprintOf } from "../projection/finding-fingerprint.ts";
+import { writesTablesOf } from "./capability-query.ts";
+import { toConfidence } from "./confidence.ts";
+import type { DetectorContext } from "./detector-context.ts";
+
+const POSTING_NAME_RE = /^(Post|Apply|Release)[A-Z]/;
+const TRANSACTION_THRESHOLD_TABLES = 3;
+
+function isTransactionManaging(
+	routineId: RoutineId,
+	routineById: Map<RoutineId, Routine>,
+): boolean {
+	const r = routineById.get(routineId);
+	if (!r) return false;
+	if (POSTING_NAME_RE.test(r.name)) return true;
+	if (!r.summary) return false;
+	return writesTablesOf(r.summary).length >= TRANSACTION_THRESHOLD_TABLES;
+}
+
+/**
+ * D8 — marquee transaction-correctness detector. For each transaction span (Commit
+ * reachable from some root), if the span includes a transaction-managing routine
+ * (Post.../Apply.../Release... name OR writes >= 3 tables) AND the Commit is in a different
+ * routine — emit high-severity finding.
+ *
+ * Catches:
+ *   - Event subscribers that Commit inside a posting handler.
+ *   - Post-* helpers that Commit mid-transaction.
+ *
+ * Cannot be expressed by per-file analyzers: requires reverse call graph + transaction
+ * span aggregation.
+ */
+export function detectD8(
+	model: SemanticModel,
+	graph: CombinedGraph,
+	ctx: DetectorContext,
+): { findings: Finding[]; stats: DetectorStats } {
+	const { transactionSpans: spans, routineById } = ctx;
+	const findings: Finding[] = [];
+	let candidatesConsidered = 0;
+	let skippedOther = 0;
+
+	for (const span of spans) {
+		const commitRoutine = routineById.get(span.commitRoutineId);
+		if (!commitRoutine) continue;
+		if (roleOf(commitRoutine) !== "primary") continue;
+		candidatesConsidered++;
+
+		const managers = span.routinesInSpan
+			.filter((id) => id !== span.commitRoutineId)
+			.filter((id) => isTransactionManaging(id, routineById));
+		if (managers.length === 0) {
+			skippedOther++;
+			continue;
+		}
+
+		const managerId = managers[0];
+		if (managerId === undefined) continue;
+		const manager = routineById.get(managerId);
+		if (!manager) continue;
+
+		const path: EvidenceStep[] = [
+			{
+				routineId: managerId,
+				sourceAnchor: manager.sourceAnchor,
+				note: `transaction-managing routine: ${manager.name}`,
+			},
+		];
+		const commitOpSite = commitRoutine.features.operationSites.find(
+			(os) => os.id === span.commitOperationId,
+		);
+		const commitAnchor = commitOpSite?.sourceAnchor ?? commitRoutine.sourceAnchor;
+		path.push({
+			routineId: commitRoutine.id,
+			operationId: span.commitOperationId,
+			sourceAnchor: commitAnchor,
+			note: `Commit inside ${manager.name}'s transaction span`,
+		});
+
+		const writeCount = manager.summary ? writesTablesOf(manager.summary).length : 0;
+
+		const finding: Finding = {
+			id: `d8/${span.commitOperationId}`,
+			rootCauseKey: `d8/${span.commitOperationId}`,
+			detector: "d8-commit-in-transaction",
+			title: "Commit inside a posting transaction span",
+			rootCause: `${commitRoutine.name} calls Commit while reachable from ${manager.name}, which writes ${writeCount} tables. A mid-transaction Commit breaks rollback semantics — if the surrounding operation later fails, the data is left half-written.`,
+			severity: "high",
+			confidence: toConfidence([], "likely"),
+			primaryLocation: commitAnchor,
+			evidencePath: path,
+			affectedObjects: [commitRoutine.objectId, manager.objectId].sort(),
+			affectedTables: span.writesTables,
+			fixOptions: [
+				{
+					description:
+						"Remove the Commit, or restructure so the surrounding transaction completes (returns control to its caller) before this code runs.",
+					safety: "low",
+				},
+			],
+			provenance: [{ source: "tree-sitter" }],
+		};
+		finding.fingerprint = fingerprintOf(finding, model);
+		findings.push(finding);
+	}
+
+	// Dedupe by id (same Commit operation flagged from multiple manager routines → one finding)
+	const seen = new Set<string>();
+	const deduped: Finding[] = [];
+	for (const f of findings) {
+		if (seen.has(f.id)) continue;
+		seen.add(f.id);
+		deduped.push(f);
+	}
+
+	return {
+		findings: deduped.sort((a, b) => compareStrings(a.id, b.id)),
+		stats: {
+			detector: "d8-commit-in-transaction",
+			candidatesConsidered,
+			findingsEmitted: deduped.length,
+			skipped: { other: skippedOther > 0 ? skippedOther : undefined },
+		},
+	};
+}

package/src/detectors/d9-transaction-span-summary.ts

@@ -0,0 +1,107 @@
+import type { CombinedGraph } from "../engine/combined-graph.ts";
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import { roleOf } from "../model/entities.ts";
+import type { DetectorStats, EvidenceStep, Finding } from "../model/finding.ts";
+import type { SemanticModel } from "../model/model.ts";
+import { fingerprintOf } from "../projection/finding-fingerprint.ts";
+import { toConfidence } from "./confidence.ts";
+import type { DetectorContext } from "./detector-context.ts";
+
+const MIN_INTERESTING_ROUTINES = 2;
+const MIN_INTERESTING_TABLES = 2;
+
+/**
+ * D9 — for each non-trivial transaction span (>=2 routines AND >=2 tables), emit an
+ * info-level finding describing what the span covers. Aimed at code review / agent
+ * context, not a bug to fix.
+ */
+export function detectD9(
+	model: SemanticModel,
+	graph: CombinedGraph,
+	ctx: DetectorContext,
+): { findings: Finding[]; stats: DetectorStats } {
+	const { transactionSpans: spans, routineById } = ctx;
+	const findings: Finding[] = [];
+	let candidatesConsidered = 0;
+	let skippedOther = 0;
+
+	for (const span of spans) {
+		const commitRoutine = routineById.get(span.commitRoutineId);
+		if (!commitRoutine) continue;
+		if (roleOf(commitRoutine) !== "primary") continue;
+		candidatesConsidered++;
+		if (span.routinesInSpan.length < MIN_INTERESTING_ROUTINES) {
+			skippedOther++;
+			continue;
+		}
+
+		// Count concrete tables + presence of uncertain effects.
+		// !span.coverageComplete fires when ANY routine in the span has
+		// an undefined summary OR less-than-complete inherited coverage
+		// (Wave 3 substrate signal). Note: this is broader than the legacy
+		// writesTables-specific probe — any incomplete capability family
+		// (events, http, etc.) sets the flag, not just incomplete writes.
+		// Acceptable at info severity; the signal narrows back to writes-
+		// only when per-family coverage roll-up lands (see
+		// TransactionSpan.coverageComplete JSDoc).
+		const tableCount = span.writesTables.length;
+		const effectsAreInteresting = tableCount >= MIN_INTERESTING_TABLES || !span.coverageComplete;
+		if (!effectsAreInteresting) {
+			skippedOther++;
+			continue;
+		}
+
+		const path: EvidenceStep[] = [
+			{
+				routineId: commitRoutine.id,
+				operationId: span.commitOperationId,
+				sourceAnchor: commitRoutine.sourceAnchor,
+				note: "Commit at end of span",
+			},
+		];
+
+		// Describe table effects—concrete or unknown.
+		// !span.coverageComplete is the substrate's coverage roll-up
+		// (replaces the legacy per-routine writesTables === "unknown" probe).
+		const tableDesc =
+			span.writesTables.length > 0
+				? `writes ${span.writesTables.length} known table(s)`
+				: !span.coverageComplete
+					? "writes tables (effect scope unknown)"
+					: "writes tables";
+
+		const finding: Finding = {
+			id: `d9/${span.commitOperationId}`,
+			rootCauseKey: `d9/${span.commitOperationId}`,
+			detector: "d9-transaction-span-summary",
+			title: "Transaction span summary",
+			rootCause: `Transaction ending at ${commitRoutine.name}'s Commit spans ${span.routinesInSpan.length} routines, ${tableDesc}, publishes ${span.publishesEvents.length} event(s). Consider whether all of this needs to be atomic.`,
+			severity: "info",
+			confidence: toConfidence([], "possible"),
+			primaryLocation: commitRoutine.sourceAnchor,
+			evidencePath: path,
+			affectedObjects: [commitRoutine.objectId],
+			affectedTables: span.writesTables,
+			fixOptions: [
+				{
+					description:
+						"If the span includes operations that are logically independent, split them into separate transactions with their own Commit boundaries.",
+					safety: "low",
+				},
+			],
+			provenance: [{ source: "tree-sitter" }],
+		};
+		finding.fingerprint = fingerprintOf(finding, model);
+		findings.push(finding);
+	}
+
+	return {
+		findings: findings.sort((a, b) => compareStrings(a.id, b.id)),
+		stats: {
+			detector: "d9-transaction-span-summary",
+			candidatesConsidered,
+			findingsEmitted: findings.length,
+			skipped: { other: skippedOther > 0 ? skippedOther : undefined },
+		},
+	};
+}

package/src/detectors/detector-context.ts

@@ -0,0 +1,121 @@
+import type { CombinedGraph } from "../engine/combined-graph.ts";
+import { findEntryPoints, findReachableRoots } from "../engine/entry-points.ts";
+import type { EventFlowIndexes } from "../engine/event-flow.ts";
+import { buildEventFlowIndexes } from "../engine/event-flow.ts";
+import { type ReverseCallGraph, buildReverseCallGraph } from "../engine/reverse-call-graph.ts";
+import { type TransactionSpan, computeTransactionSpans } from "../engine/transaction-spans.ts";
+import type { CallSite, ObjectDecl, Routine, Table } from "../model/entities.ts";
+import type { Diagnostic } from "../model/finding.ts";
+import type { CallEdge } from "../model/graph.ts";
+import type { CallsiteId, ObjectId, RoutineId, TableId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+import type { Uncertainty } from "../model/summary.ts";
+
+/**
+ * Shared, eager indexes + derived graphs detectors read from. Built once at the top of
+ * `runDetectors` so 15 detectors don't each rebuild `new Map(model.routines.map(...))`
+ * and D8/D9 don't recompute transaction spans twice.
+ */
+export interface DetectorContext {
+	routineById: Map<RoutineId, Routine>;
+	objectsById: Map<ObjectId, ObjectDecl>;
+	tableById: Map<TableId, Table>;
+	reverseCallGraph: ReverseCallGraph;
+	/** Trigger + event-subscriber roots — D8 transaction-span boundaries. */
+	entryPoints: Set<RoutineId>;
+	/**
+	 * Reachability roots for "is this routine ever invoked?" — entry points plus the
+	 * procedures we cannot prove are app-scoped (public/protected always; `internal`
+	 * only when `internalReachableExternally` is true). Used by D14 only.
+	 */
+	reachableRoots: Set<RoutineId>;
+	/**
+	 * True when the workspace's app.json `internalsVisibleTo` names at least one app —
+	 * `internal` procedures are then treated as a potential external API surface and
+	 * are not flagged as dead. False (the common case) means `internal` is app-scoped
+	 * for reachability purposes and D14 flags it like a `local procedure`.
+	 */
+	internalReachableExternally: boolean;
+	transactionSpans: TransactionSpan[];
+	/**
+	 * Resolved CallEdges keyed by `callsiteId`. Mirrors SummaryContext's index of the same
+	 * name and lets detectors do O(1) callsite → resolved edge lookup instead of the
+	 * O(N) `graph.edgesByFrom.get(routine.id).find(e => e.callsiteId === cs.id)` scan
+	 * that several pre-Phase-4 detectors still use. Built from the same source — only
+	 * edges with `to !== undefined` are indexed; the first edge per callsiteId wins
+	 * (matches SummaryContext's behaviour for the pathological multi-target case).
+	 */
+	resolvedCallEdgeByCallsite: Map<CallsiteId, CallEdge>;
+	/**
+	 * Uncertainty edges grouped by source routine + every call site indexed by id. The
+	 * interprocedural path-walker (`walkEvidence`, used by D1/D2) is invoked once per in-loop
+	 * call site; without these it rebuilds the routine/edge/callsite indexes from scratch on
+	 * every call — O(routines + edges) per call. Built once here and threaded into `walkEvidence`.
+	 */
+	uncertaintyEdgesByFrom: Map<RoutineId, Uncertainty[]>;
+	callSiteById: Map<CallsiteId, CallSite>;
+	/**
+	 * Lazy memoized event-flow indexes. Built on first call; subsequent
+	 * calls return the same object. Used by D43/D44/D45 + the events
+	 * fanout/chains reports.
+	 */
+	getEventFlowIndexes(): EventFlowIndexes;
+	/**
+	 * Detector-side diagnostic bus. Detectors push warnings here for
+	 * substrate-missing or other run-time signals; `runDetectors` merges
+	 * this into its output diagnostics list.
+	 */
+	diagnostics: Diagnostic[];
+}
+
+/**
+ * Build the shared context. Order matters: `transactionSpans` consumes the reverse graph.
+ * Called once per `runDetectors` invocation.
+ */
+export function buildDetectorContext(model: SemanticModel, graph: CombinedGraph): DetectorContext {
+	const routineById = new Map<RoutineId, Routine>(model.routines.map((r) => [r.id, r]));
+	const objectsById = new Map<ObjectId, ObjectDecl>(model.objects.map((o) => [o.id, o]));
+	const tableById = new Map<TableId, Table>(model.tables.map((t) => [t.id, t]));
+	const reverseCallGraph = buildReverseCallGraph(graph);
+	const entryPoints = new Set(findEntryPoints(model));
+	const internalReachableExternally = (model.identity.primaryInternalsVisibleTo?.length ?? 0) > 0;
+	const reachableRoots = new Set(findReachableRoots(model, { internalReachableExternally }));
+	const transactionSpans = computeTransactionSpans(model, graph, reverseCallGraph);
+	const resolvedCallEdgeByCallsite = new Map<CallsiteId, CallEdge>();
+	for (const ce of model.callGraph) {
+		if (ce.to === undefined) continue;
+		if (!resolvedCallEdgeByCallsite.has(ce.callsiteId)) {
+			resolvedCallEdgeByCallsite.set(ce.callsiteId, ce);
+		}
+	}
+	const uncertaintyEdgesByFrom = new Map<RoutineId, Uncertainty[]>();
+	for (const ue of graph.uncertaintyEdges ?? []) {
+		const list = uncertaintyEdgesByFrom.get(ue.from);
+		if (list) list.push(ue.uncertainty);
+		else uncertaintyEdgesByFrom.set(ue.from, [ue.uncertainty]);
+	}
+	const callSiteById = new Map<CallsiteId, CallSite>();
+	for (const r of model.routines) {
+		for (const cs of r.features.callSites) callSiteById.set(cs.id, cs);
+	}
+	let memoIndexes: EventFlowIndexes | undefined;
+	const diagnostics: Diagnostic[] = [];
+	return {
+		routineById,
+		objectsById,
+		tableById,
+		reverseCallGraph,
+		entryPoints,
+		reachableRoots,
+		internalReachableExternally,
+		transactionSpans,
+		resolvedCallEdgeByCallsite,
+		uncertaintyEdgesByFrom,
+		callSiteById,
+		getEventFlowIndexes() {
+			if (memoIndexes === undefined) memoIndexes = buildEventFlowIndexes(model);
+			return memoIndexes;
+		},
+		diagnostics,
+	};
+}

package/src/detectors/finding-grouping.ts

@@ -0,0 +1,61 @@
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import type { Diagnostic, Finding } from "../model/finding.ts";
+
+export interface GroupAndCapResult {
+	/** Findings kept after grouping + capping. Sorted by (groupKey, id). */
+	kept: readonly Finding[];
+	/** Findings dropped because their group exceeded the cap. Sorted by (groupKey, id). */
+	truncated: readonly Finding[];
+}
+
+/**
+ * Group findings by `keyOf(finding)` then cap each group to `maxPerKey`.
+ * Within each group, findings are sorted by id (deterministic). Group
+ * iteration order is sorted by group key (deterministic).
+ *
+ * Use this to prevent output explosion in detectors that may emit many
+ * findings per resource (D44 read-after-write, D45 N-hop transitive).
+ */
+export function groupAndCap(
+	findings: readonly Finding[],
+	keyOf: (f: Finding) => string,
+	maxPerKey: number,
+): GroupAndCapResult {
+	const groups = new Map<string, Finding[]>();
+	for (const f of findings) {
+		const k = keyOf(f);
+		const bag = groups.get(k) ?? [];
+		bag.push(f);
+		groups.set(k, bag);
+	}
+	const kept: Finding[] = [];
+	const truncated: Finding[] = [];
+	const sortedKeys = [...groups.keys()].sort(compareStrings);
+	for (const k of sortedKeys) {
+		const bag = groups.get(k) ?? [];
+		bag.sort((a, b) => compareStrings(a.id, b.id));
+		if (bag.length <= maxPerKey) {
+			kept.push(...bag);
+		} else {
+			kept.push(...bag.slice(0, maxPerKey));
+			truncated.push(...bag.slice(maxPerKey));
+		}
+	}
+	return { kept, truncated };
+}
+
+/**
+ * Build a single warning diagnostic for a truncation event. Push into
+ * `ctx.diagnostics` when truncation actually happened (truncated.length > 0).
+ */
+export function truncationDiagnostic(
+	detector: string,
+	groupKeyKind: string,
+	truncatedCount: number,
+): Diagnostic {
+	return {
+		severity: "warning",
+		stage: "detect",
+		message: `${detector}: truncated ${truncatedCount} finding(s) per ${groupKeyKind} cap`,
+	};
+}

package/src/detectors/path-merge.ts

@@ -0,0 +1,174 @@
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import type { EvidenceStep, Finding, FindingConfidence } from "../model/finding.ts";
+
+/**
+ * Collapse N per-path findings that share a terminal anchor into ONE finding per
+ * anchor, with the other paths attached as `additionalPaths`.
+ *
+ * The shape problem this fixes: D1 and D2 walk the call graph and emit a finding
+ * per `(loop-containing routine, terminal op)` pair. When the same terminal op is
+ * reachable from M different in-loop ancestors, the user sees M findings on the
+ * same source location — same fix, same bug. The right entity is the terminal
+ * op; the multiple call chains are supporting traces.
+ *
+ * Contract for callers:
+ *  - Pre-merge findings must already share the SAME `id`/`rootCauseKey` when they
+ *    represent the same logical bug. Callers set those keys to omit any
+ *    loop-identity component (so e.g. `d1/{terminalRoutine}/{terminalOp}`, not
+ *    `d1/{loop}/{terminalOp}`).
+ *  - Each input finding has exactly one `evidencePath`; `additionalPaths` is
+ *    expected absent (this helper ignores it if set).
+ *
+ * Canonical-pick rules (deterministic — both `runDetectors` sort and `--baseline`
+ * fingerprints depend on stable order):
+ *   1. Highest severity wins (critical > high > medium > low > info). The
+ *      canonical finding's `evidencePath` is the worst path so the user sees the
+ *      most severe trace first.
+ *   2. Tie on severity → earliest `primaryLocation` (file, then line, then
+ *      column). The pre-merge `primaryLocation` is always the same anchor
+ *      across grouped findings, so this rarely matters, but it's stable.
+ *   3. Tie on location → smaller `id` lexicographically. Final stability anchor.
+ *
+ * Merge math:
+ *  - `severity` = max across the group (canonical already holds this).
+ *  - `confidence.level` = best level (`confirmed` > `likely` > `possible`).
+ *  - `confidence.cappedBy` / `evidence` = union (deduped, sorted).
+ *  - `affectedObjects` / `affectedTables` = union (deduped, sorted).
+ *  - `additionalPaths` = the non-canonical paths sorted by
+ *    (sourceUnitId, line, column, routineId) of the first evidence step — the
+ *    loop step for D1, the call step for D2.
+ *  - `rootCause` text is annotated with the path count when M > 1 (see
+ *    `annotateRootCause` below). Callers control the canonical text.
+ */
+const SEV_RANK = { critical: 5, high: 4, medium: 3, low: 2, info: 1 } as const;
+type Severity = keyof typeof SEV_RANK;
+
+const CONF_RANK = { confirmed: 3, likely: 2, possible: 1 } as const;
+type ConfLevel = keyof typeof CONF_RANK;
+
+/** Sort key for a path's first step — used to order `additionalPaths` deterministically. */
+function pathSortKey(path: EvidenceStep[]): string {
+	const step = path[0];
+	if (step === undefined) return "";
+	const a = step.sourceAnchor;
+	return `${a.sourceUnitId}|${String(a.range.startLine).padStart(8, "0")}|${String(a.range.startColumn).padStart(8, "0")}|${step.routineId}`;
+}
+
+/** Pick the canonical (worst, then earliest, then smallest-id) finding from a group. */
+function pickCanonical(group: Finding[]): Finding {
+	let best = group[0];
+	if (best === undefined) throw new Error("pickCanonical: empty group");
+	for (let i = 1; i < group.length; i++) {
+		const candidate = group[i];
+		if (candidate === undefined) continue;
+		if (SEV_RANK[candidate.severity] > SEV_RANK[best.severity]) {
+			best = candidate;
+			continue;
+		}
+		if (SEV_RANK[candidate.severity] < SEV_RANK[best.severity]) continue;
+		const a = candidate.primaryLocation;
+		const b = best.primaryLocation;
+		if (a.sourceUnitId !== b.sourceUnitId) {
+			if (compareStrings(a.sourceUnitId, b.sourceUnitId) < 0) best = candidate;
+			continue;
+		}
+		if (a.range.startLine !== b.range.startLine) {
+			if (a.range.startLine < b.range.startLine) best = candidate;
+			continue;
+		}
+		if (a.range.startColumn !== b.range.startColumn) {
+			if (a.range.startColumn < b.range.startColumn) best = candidate;
+			continue;
+		}
+		if (compareStrings(candidate.id, best.id) < 0) best = candidate;
+	}
+	return best;
+}
+
+function mergeConfidence(group: Finding[]): FindingConfidence {
+	let bestLevel: ConfLevel = "possible";
+	const cappedBy = new Set<string>();
+	const evidence: FindingConfidence["evidence"] = [];
+	const seenEvidence = new Set<string>();
+	for (const f of group) {
+		if (CONF_RANK[f.confidence.level] > CONF_RANK[bestLevel]) bestLevel = f.confidence.level;
+		for (const c of f.confidence.cappedBy ?? []) cappedBy.add(c);
+		for (const e of f.confidence.evidence ?? []) {
+			const key = JSON.stringify(e);
+			if (!seenEvidence.has(key)) {
+				seenEvidence.add(key);
+				evidence.push(e);
+			}
+		}
+	}
+	const result: FindingConfidence = { level: bestLevel, evidence };
+	const capArr = [...cappedBy].sort();
+	if (capArr.length > 0) {
+		result.cappedBy = capArr as NonNullable<FindingConfidence["cappedBy"]>;
+	}
+	return result;
+}
+
+function unionSorted(...arrs: string[][]): string[] {
+	const set = new Set<string>();
+	for (const arr of arrs) for (const v of arr) set.add(v);
+	return [...set].sort();
+}
+
+/**
+ * Annotate a finding's `rootCause` with the path count when there are multiple
+ * reaching traces. Keeps the canonical text first (so existing tests / consumers
+ * that match the lead clause keep working), appends a separator + path-count
+ * note. When `pathCount === 1`, returns the input unchanged.
+ */
+export function annotateRootCause(rootCause: string, pathCount: number): string {
+	if (pathCount <= 1) return rootCause;
+	const others = pathCount - 1;
+	const noun = others === 1 ? "ancestor" : "ancestors";
+	return `${rootCause} (Also reached from ${others} other in-loop ${noun}.)`;
+}
+
+/**
+ * Group `findings` by `rootCauseKey` and collapse each group to one Finding with
+ * additionalPaths populated. Singleton groups pass through untouched.
+ *
+ * Output is sorted by canonical finding `id` for determinism. Callers run this
+ * AFTER their own per-path dedup (Set-keyed by id) so a single (loop, op) pair
+ * doesn't get its evidence duplicated.
+ */
+export function mergeByTerminal(findings: Finding[]): Finding[] {
+	const groups = new Map<string, Finding[]>();
+	for (const f of findings) {
+		const list = groups.get(f.rootCauseKey);
+		if (list === undefined) groups.set(f.rootCauseKey, [f]);
+		else list.push(f);
+	}
+	const out: Finding[] = [];
+	for (const group of groups.values()) {
+		if (group.length === 1) {
+			const only = group[0];
+			if (only !== undefined) out.push(only);
+			continue;
+		}
+		const canonical = pickCanonical(group);
+		const otherPaths = group
+			.filter((f) => f !== canonical)
+			.map((f) => f.evidencePath)
+			.sort((a, b) => compareStrings(pathSortKey(a), pathSortKey(b)));
+		const merged: Finding = {
+			...canonical,
+			severity: canonical.severity,
+			confidence: mergeConfidence(group),
+			affectedObjects: unionSorted(
+				...group.map((f) => f.affectedObjects.map((id) => id as unknown as string)),
+			) as typeof canonical.affectedObjects,
+			affectedTables: unionSorted(
+				...group.map((f) => f.affectedTables.map((id) => id as unknown as string)),
+			) as typeof canonical.affectedTables,
+			rootCause: annotateRootCause(canonical.rootCause, group.length),
+			additionalPaths: otherPaths,
+		};
+		out.push(merged);
+	}
+	return out.sort((a, b) => compareStrings(a.id, b.id));
+}