al-sem 0.0.1

package/src/detectors/registry.ts

@@ -0,0 +1,176 @@
+import type { CombinedGraph } from "../engine/combined-graph.ts";
+import { compareNatural, compareStrings } from "../engine/uncertainty-util.ts";
+import { roleOf } from "../model/entities.ts";
+import type { DetectorStats, Diagnostic, Finding } from "../model/finding.ts";
+import type { SemanticModel } from "../model/model.ts";
+import { profilingActive, recordPhase } from "../perf/profiler.ts";
+import { detectD1 } from "./d1-db-op-in-loop.ts";
+import { detectD2 } from "./d2-event-fanout-in-loop.ts";
+import { detectD3 } from "./d3-missing-setloadfields.ts";
+import { detectD4 } from "./d4-repeated-lookup-in-loop.ts";
+import { detectD5 } from "./d5-set-based-opportunity.ts";
+import { detectD7 } from "./d7-recursive-event-expansion.ts";
+import { detectD8 } from "./d8-commit-in-transaction.ts";
+import { detectD9 } from "./d9-transaction-span-summary.ts";
+import { detectD10 } from "./d10-self-modifying-loop.ts";
+import { detectD11 } from "./d11-modify-without-get.ts";
+import { detectD12 } from "./d12-dead-integration-event.ts";
+import { detectD13 } from "./d13-cross-app-internal-call.ts";
+import { detectD14 } from "./d14-dead-routine.ts";
+import { detectD16 } from "./d16-obsolete-routine-call.ts";
+import { detectD17 } from "./d17-min-version-drift.ts";
+import { detectD18 } from "./d18-constant-filter-in-loop.ts";
+import { detectD19 } from "./d19-unused-parameter.ts";
+import { detectD20 } from "./d20-unreachable-after-exit.ts";
+import { detectD21 } from "./d21-read-without-load.ts";
+import { detectD22 } from "./d22-flowfield-without-calcfields.ts";
+import { detectD29 } from "./d29-subscriber-modify-on-event-record.ts";
+import { detectD32 } from "./d32-constant-boolean-parameter.ts";
+import { detectD33 } from "./d33-unfiltered-bulk-write.ts";
+import { detectD34 } from "./d34-commit-in-loop.ts";
+import { detectD35 } from "./d35-commit-in-event-subscriber.ts";
+import { detectD36 } from "./d36-late-setloadfields.ts";
+import { detectD37 } from "./d37-validate-without-persist.ts";
+import { detectD38 } from "./d38-subscriber-to-obsolete-event.ts";
+import { detectD39 } from "./d39-record-left-dirty-across-chain.ts";
+// D40 is intentionally NOT in DEFAULT_DETECTORS — opt-in only via
+// `--detector d40-transitive-load-missing`. See the d40 module's JSDoc for the rationale
+// (Phase 4 straight-line walker produces a high false-positive rate dominated by the
+// loop-loaded record class; Phase 6's full walker closes it).
+import { detectD40 } from "./d40-transitive-load-missing.ts";
+import { detectD41 } from "./d41-transitive-filter-loss.ts";
+import { detectD42 } from "./d42-cross-call-wrong-setloadfields.ts";
+import { detectD43 } from "./d43-event-ishandled-skip.ts";
+import { detectD44 } from "./d44-event-multi-subscriber-overlap.ts";
+import { detectD45 } from "./d45-event-transitive-table-exposure.ts";
+import type { DetectorContext } from "./detector-context.ts";
+import { buildDetectorContext } from "./detector-context.ts";
+
+/** A detector: a pure query over the summarised model + combined graph. */
+export interface Detector {
+	name: string;
+	run(
+		model: SemanticModel,
+		graph: CombinedGraph,
+		ctx: DetectorContext,
+	): { findings: Finding[]; stats: DetectorStats };
+}
+
+/** The default detector registry. */
+export const DEFAULT_DETECTORS: Detector[] = [
+	{ name: "d1-db-op-in-loop", run: detectD1 },
+	{ name: "d2-event-fanout-in-loop", run: detectD2 },
+	{ name: "d3-missing-setloadfields", run: detectD3 },
+	{ name: "d4-repeated-lookup-in-loop", run: detectD4 },
+	{ name: "d5-set-based-opportunity", run: detectD5 },
+	{ name: "d7-recursive-event-expansion", run: detectD7 },
+	{ name: "d8-commit-in-transaction", run: detectD8 },
+	{ name: "d9-transaction-span-summary", run: detectD9 },
+	{ name: "d10-self-modifying-loop", run: detectD10 },
+	{ name: "d11-modify-without-get", run: detectD11 },
+	{ name: "d12-dead-integration-event", run: detectD12 },
+	{ name: "d13-cross-app-internal-call", run: detectD13 },
+	{ name: "d14-dead-routine", run: detectD14 },
+	{ name: "d16-obsolete-routine-call", run: detectD16 },
+	{ name: "d17-min-version-drift", run: detectD17 },
+	{ name: "d18-constant-filter-in-loop", run: detectD18 },
+	{ name: "d19-unused-parameter", run: detectD19 },
+	{ name: "d20-unreachable-after-exit", run: detectD20 },
+	{ name: "d21-read-without-load", run: detectD21 },
+	{ name: "d22-flowfield-without-calcfields", run: detectD22 },
+	{ name: "d29-subscriber-modify-on-event-record", run: detectD29 },
+	{ name: "d32-constant-boolean-parameter", run: detectD32 },
+	{ name: "d33-unfiltered-bulk-write", run: detectD33 },
+	{ name: "d34-commit-in-loop", run: detectD34 },
+	{ name: "d35-commit-in-event-subscriber", run: detectD35 },
+	{ name: "d36-late-setloadfields", run: detectD36 },
+	{ name: "d37-validate-without-persist", run: detectD37 },
+	{ name: "d38-subscriber-to-obsolete-event", run: detectD38 },
+	{ name: "d39-record-left-dirty-across-chain", run: detectD39 },
+	{ name: "d41-transitive-filter-loss", run: detectD41 },
+	{ name: "d42-cross-call-wrong-setloadfields", run: detectD42 },
+	{ name: "d43-event-ishandled-skip", run: detectD43 },
+	{ name: "d44-event-multi-subscriber-overlap", run: detectD44 },
+	{ name: "d45-event-transitive-table-exposure", run: detectD45 },
+];
+
+/**
+ * Opt-in detectors — not in the default registry. Surfaced by `--detector <name>`
+ * (CLI) and `analyzeWorkspace({ detectors: [...DEFAULT_DETECTORS, ...OPT_IN_DETECTORS] })`
+ * (library) for callers that explicitly want them.
+ *
+ * Currently: D40 (transitive-load-missing) — Phase 6 graduates it back to the default
+ * registry once the full statement-tree walker eliminates the loop-loaded FP class.
+ */
+export const OPT_IN_DETECTORS: Detector[] = [
+	{ name: "d40-transitive-load-missing", run: detectD40 },
+];
+
+/** All known detectors — default + opt-in. Useful for CLI surface enumeration. */
+export const ALL_DETECTORS: Detector[] = [...DEFAULT_DETECTORS, ...OPT_IN_DETECTORS];
+
+function primaryLocationKey(f: Finding): string {
+	const a = f.primaryLocation;
+	return `${a.sourceUnitId}:${a.range.startLine}:${a.range.startColumn}`;
+}
+
+/**
+ * Run every detector in isolation. A detector that throws does not kill the run — it becomes
+ * a `Diagnostic(stage: "detect")` and the rest still run. The combined Finding[] is sorted
+ * by (detector, primaryLocationKey, rootCauseKey) for deterministic output.
+ */
+export function runDetectors(
+	model: SemanticModel,
+	graph: CombinedGraph,
+	detectors: Detector[] = DEFAULT_DETECTORS,
+): { findings: Finding[]; diagnostics: Diagnostic[]; detectorStats: DetectorStats[] } {
+	const findings: Finding[] = [];
+	const diagnostics: Diagnostic[] = [];
+	const detectorStats: DetectorStats[] = [];
+	const _tCtx = profilingActive() ? performance.now() : 0;
+	const ctx = buildDetectorContext(model, graph);
+	if (profilingActive()) recordPhase("detect:buildDetectorContext", performance.now() - _tCtx);
+	for (const detector of detectors) {
+		const _td = profilingActive() ? performance.now() : 0;
+		try {
+			const result = detector.run(model, graph, ctx);
+			findings.push(...result.findings);
+			detectorStats.push(result.stats);
+			if (profilingActive()) recordPhase(`detect:${detector.name}`, performance.now() - _td);
+		} catch (err) {
+			diagnostics.push({
+				severity: "warning",
+				stage: "detect",
+				message: `Detector "${detector.name}" threw: ${err instanceof Error ? err.message : String(err)}`,
+			});
+		}
+	}
+	diagnostics.push(...ctx.diagnostics);
+	const roleByRoutineId = new Map(model.routines.map((r) => [r.id, roleOf(r)]));
+	const scoped = findings.filter((f) => {
+		const primaryRole = roleByRoutineId.get(f.primaryLocation.enclosingRoutineId) ?? "primary";
+		if (primaryRole === "primary") return true;
+		// Detector flagged a primary-app actionable anchor (e.g. D1 whose terminal DB op
+		// is deep in a dependency, but the user's loop is in primary code).
+		if (f.actionableAnchor !== undefined) {
+			const anchorRole = roleByRoutineId.get(f.actionableAnchor.enclosingRoutineId) ?? "primary";
+			if (anchorRole === "primary") return true;
+		}
+		return false;
+	});
+	scoped.sort((a, b) => {
+		if (a.detector !== b.detector) return compareNatural(a.detector, b.detector);
+		const la = primaryLocationKey(a);
+		const lb = primaryLocationKey(b);
+		if (la !== lb) return compareStrings(la, lb);
+		return compareStrings(a.rootCauseKey, b.rootCauseKey);
+	});
+	if (process.env.AL_SEM_DETECTOR_STATS === "1") {
+		for (const s of detectorStats) {
+			process.stderr.write(
+				`[detector-stats] ${s.detector}: candidates=${s.candidatesConsidered} emitted=${s.findingsEmitted} skipped=${JSON.stringify(s.skipped)}\n`,
+			);
+		}
+	}
+	return { findings: scoped, diagnostics, detectorStats };
+}

package/src/detectors/table-display.ts

@@ -0,0 +1,42 @@
+import type { Routine, Table } from "../model/entities.ts";
+import type { TableId } from "../model/ids.ts";
+
+/**
+ * Render a record-operation's target table for human consumption.
+ *
+ * Three tiers, in order of preference:
+ *  1. `op.tableId` resolves in `tableById` → return the table's NAME (e.g.
+ *     `"Customer"`, `"CDC Template Field"`). This is what the user sees in
+ *     their IDE.
+ *  2. `op.tableId` is undefined or unresolved AND the receiving record-variable
+ *     has a declared `tableName` text → return that text, suffixed with
+ *     `(type not loaded)`. This is the common case when the type lives in a
+ *     dependency we couldn't load (e.g. opaque Continia deps, AL-language's
+ *     `.dependencies/` cache that al-sem doesn't crawl). The user still gets
+ *     the type they wrote in source.
+ *  3. Variable name itself, prefixed with `var `, as a last-resort identity
+ *     (e.g. `var DocGroup`).
+ *  4. The string `"unknown table"`.
+ *
+ * Replaces the previous behavior of rendering the internal table id verbatim
+ * (e.g. `"table 6225286"` or
+ * `"f4b69b55-c90d-4937-8f53-2742898fa948/table/6175301"`) — useless to humans
+ * and the dominant UX paper-cut surfaced by the DC/Cloud precision study.
+ */
+export function describeTable(
+	op: { tableId?: TableId; recordVariableName: string },
+	routine: Routine | undefined,
+	tableById: Map<TableId, Table>,
+): string {
+	if (op.tableId !== undefined) {
+		const table = tableById.get(op.tableId);
+		if (table) return table.name;
+	}
+	if (routine !== undefined) {
+		const lc = op.recordVariableName.toLowerCase();
+		const rv = routine.features.recordVariables.find((v) => v.name.toLowerCase() === lc);
+		if (rv?.tableName && rv.tableName !== "") return `${rv.tableName} (type not loaded)`;
+	}
+	if (op.recordVariableName !== "") return `var ${op.recordVariableName}`;
+	return "unknown table";
+}

package/src/diff/diff-abi.ts

@@ -0,0 +1,195 @@
+import type { ContractFact } from "../snapshot/types.ts";
+import { DiffCategory, DiffKind, computeDiffFingerprint } from "./diff-identity.ts";
+import type { DiffIndexes } from "./diff-indexes.ts";
+
+export interface DiffEngineOptions {
+	coveragePolicy: "loose" | "strict";
+}
+
+export interface AbiDetails {
+	kind:
+		| DiffKind.ObjectRemoved
+		| DiffKind.ObjectAccessibilityNarrowed
+		| DiffKind.ProcedureRemoved
+		| DiffKind.ProcedureSignatureChanged
+		| DiffKind.ProcedureVarDirectionChanged
+		| DiffKind.ProcedureObsoletionRegressed
+		| DiffKind.ProcedureObsoletionProgressed
+		| DiffKind.ObjectAdded
+		| DiffKind.ProcedureAdded;
+	oldAccessibility?: string;
+	newAccessibility?: string;
+	oldObsoleteState?: string;
+	newObsoleteState?: string;
+	oldSignatureHash?: string;
+	newSignatureHash?: string;
+}
+
+export interface AbiFinding {
+	id: string;
+	category: DiffCategory.ABI;
+	kind: DiffKind;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	subject: {
+		normalizedStableId: string;
+		oldOriginalStableId?: string;
+		newStableId?: string;
+		displayName: string;
+	};
+	comparisonCone: readonly string[];
+	details: AbiDetails;
+}
+
+const SEVERITY: Partial<Record<DiffKind, AbiFinding["severity"]>> = {
+	[DiffKind.ObjectRemoved]: "critical",
+	[DiffKind.ObjectAccessibilityNarrowed]: "critical",
+	[DiffKind.ProcedureRemoved]: "critical",
+	[DiffKind.ProcedureSignatureChanged]: "critical",
+	[DiffKind.ProcedureVarDirectionChanged]: "critical",
+	[DiffKind.ProcedureObsoletionRegressed]: "high",
+	[DiffKind.ProcedureObsoletionProgressed]: "info",
+	[DiffKind.ObjectAdded]: "info",
+	[DiffKind.ProcedureAdded]: "info",
+};
+
+/**
+ * Visibility lattice order: local < internal < protected < public.
+ * Narrowing = moving to a less visible level (higher index → lower index).
+ */
+const VISIBILITY_ORDER = ["local", "internal", "protected", "public"];
+
+function isNarrowed(oldVisibility: string | undefined, newVisibility: string | undefined): boolean {
+	const o = VISIBILITY_ORDER.indexOf(oldVisibility ?? "");
+	const n = VISIBILITY_ORDER.indexOf(newVisibility ?? "");
+	return o > n && n >= 0;
+}
+
+/**
+ * Returns true when the contract fact's kind represents a procedure-like
+ * surface (routine, event-publisher) rather than a plain object or interface.
+ */
+function isProcedureLike(fact: ContractFact): boolean {
+	return fact.kind === "routine" || fact.kind === "event-publisher";
+}
+
+function makeFinding(
+	kind: AbiDetails["kind"],
+	subjectId: string,
+	indexes: DiffIndexes,
+	details: AbiDetails,
+): AbiFinding {
+	const origin = indexes.originByNormalized.get(subjectId);
+	const display =
+		indexes.newDisplayByStableId.get(subjectId) ??
+		indexes.oldDisplayByStableId.get(subjectId) ??
+		subjectId;
+	return {
+		id: computeDiffFingerprint({
+			category: DiffCategory.ABI,
+			kind,
+			normalizedStableId: subjectId,
+		}),
+		category: DiffCategory.ABI,
+		kind,
+		severity: SEVERITY[kind] ?? "medium",
+		subject: {
+			normalizedStableId: subjectId,
+			oldOriginalStableId: origin?.oldOriginalStableId,
+			newStableId: origin?.newStableId,
+			displayName: display,
+		},
+		comparisonCone: [subjectId],
+		details,
+	};
+}
+
+export function diffAbi(
+	_oldSnap: unknown,
+	_newSnap: unknown,
+	indexes: DiffIndexes,
+	_opts: DiffEngineOptions,
+): AbiFinding[] {
+	const out: AbiFinding[] = [];
+
+	// Walk OLD facts — detect removals and in-place changes.
+	for (const [subject, oldFact] of indexes.oldContractsBySubject) {
+		const newFact = indexes.newContractsBySubject.get(subject);
+		if (newFact === undefined) {
+			// Removal — distinguish object vs procedure-like.
+			const removalKind = isProcedureLike(oldFact)
+				? DiffKind.ProcedureRemoved
+				: DiffKind.ObjectRemoved;
+			out.push(
+				makeFinding(removalKind as AbiDetails["kind"], subject, indexes, {
+					kind: removalKind as AbiDetails["kind"],
+				}),
+			);
+			continue;
+		}
+
+		// Compare in place — visibility, obsoletion, signature.
+		const oldVisibility = oldFact.visibility;
+		const newVisibility = newFact.visibility;
+		if (isNarrowed(oldVisibility, newVisibility)) {
+			out.push(
+				makeFinding(DiffKind.ObjectAccessibilityNarrowed, subject, indexes, {
+					kind: DiffKind.ObjectAccessibilityNarrowed,
+					oldAccessibility: oldVisibility,
+					newAccessibility: newVisibility,
+				}),
+			);
+		}
+
+		// Obsoletion transition: flat `obsoleteState` field ("Pending" | "Removed").
+		const oldObs = oldFact.obsoleteState;
+		const newObs = newFact.obsoleteState;
+		if (oldObs !== newObs) {
+			const order: Record<string, number> = { Pending: 1, Removed: 2 };
+			const oldRank = oldObs !== undefined ? (order[oldObs] ?? 0) : 0;
+			const newRank = newObs !== undefined ? (order[newObs] ?? 0) : 0;
+			if (newRank > oldRank) {
+				out.push(
+					makeFinding(DiffKind.ProcedureObsoletionProgressed, subject, indexes, {
+						kind: DiffKind.ProcedureObsoletionProgressed,
+						oldObsoleteState: oldObs,
+						newObsoleteState: newObs,
+					}),
+				);
+			} else if (newRank < oldRank) {
+				out.push(
+					makeFinding(DiffKind.ProcedureObsoletionRegressed, subject, indexes, {
+						kind: DiffKind.ProcedureObsoletionRegressed,
+						oldObsoleteState: oldObs,
+						newObsoleteState: newObs,
+					}),
+				);
+			}
+		}
+
+		// Signature fingerprint change (routines and event-publishers carry this).
+		const oldSig = oldFact.signatureFingerprint;
+		const newSig = newFact.signatureFingerprint;
+		if (oldSig !== "" && newSig !== "" && oldSig !== newSig) {
+			out.push(
+				makeFinding(DiffKind.ProcedureSignatureChanged, subject, indexes, {
+					kind: DiffKind.ProcedureSignatureChanged,
+					oldSignatureHash: oldSig,
+					newSignatureHash: newSig,
+				}),
+			);
+		}
+	}
+
+	// Walk NEW facts to find additions.
+	for (const [subject, newFact] of indexes.newContractsBySubject) {
+		if (indexes.oldContractsBySubject.has(subject)) continue;
+		const addKind = isProcedureLike(newFact) ? DiffKind.ProcedureAdded : DiffKind.ObjectAdded;
+		out.push(
+			makeFinding(addKind as AbiDetails["kind"], subject, indexes, {
+				kind: addKind as AbiDetails["kind"],
+			}),
+		);
+	}
+
+	return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/src/diff/diff-capabilities.ts

@@ -0,0 +1,179 @@
+import type { CapabilityFact, CapabilityResourceKind } from "../model/capability.ts";
+import type { DiffEngineOptions } from "./diff-abi.ts";
+import { DiffCategory, DiffKind, computeDiffFingerprint } from "./diff-identity.ts";
+import type { DiffIndexes } from "./diff-indexes.ts";
+
+export interface CapabilityDetails {
+	kind:
+		| DiffKind.CapabilityGainedWrite
+		| DiffKind.CapabilityGainedRead
+		| DiffKind.CapabilityGainedCommit
+		| DiffKind.CapabilityGainedHttp
+		| DiffKind.CapabilityGainedTelemetry
+		| DiffKind.CapabilityGainedIsolatedStorage
+		| DiffKind.CapabilityGainedFile
+		| DiffKind.CapabilityGainedDynamicDispatch
+		| DiffKind.CapabilityGainedEventPublish
+		| DiffKind.CapabilityLost
+		| DiffKind.CapabilityLostUnderCoverage;
+	resourceKind: string;
+	resourceId?: string;
+	op: string;
+}
+
+export interface CapabilityFinding {
+	id: string;
+	category: DiffCategory.Capabilities;
+	kind: DiffKind;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	subject: {
+		normalizedStableId: string;
+		oldOriginalStableId?: string;
+		newStableId?: string;
+		displayName: string;
+	};
+	comparisonCone: readonly string[];
+	details: CapabilityDetails;
+}
+
+const SEVERITY: Partial<Record<DiffKind, CapabilityFinding["severity"]>> = {
+	[DiffKind.CapabilityGainedCommit]: "high",
+	[DiffKind.CapabilityGainedDynamicDispatch]: "high",
+	[DiffKind.CapabilityGainedWrite]: "medium",
+	[DiffKind.CapabilityGainedRead]: "medium",
+	[DiffKind.CapabilityGainedHttp]: "medium",
+	[DiffKind.CapabilityGainedTelemetry]: "medium",
+	[DiffKind.CapabilityGainedIsolatedStorage]: "medium",
+	[DiffKind.CapabilityGainedFile]: "medium",
+	[DiffKind.CapabilityGainedEventPublish]: "medium",
+	[DiffKind.CapabilityLost]: "medium",
+	[DiffKind.CapabilityLostUnderCoverage]: "low",
+};
+
+function gainedKindFor(fact: CapabilityFact): DiffKind | undefined {
+	const kind = fact.resourceKind as CapabilityResourceKind;
+	const op = fact.op;
+	if (kind === "table") {
+		if (op === "read") return DiffKind.CapabilityGainedRead;
+		if (op === "insert" || op === "modify" || op === "delete")
+			return DiffKind.CapabilityGainedWrite;
+	}
+	if (kind === "transaction" && op === "commit") return DiffKind.CapabilityGainedCommit;
+	if (kind === "http") return DiffKind.CapabilityGainedHttp;
+	if (kind === "telemetry") return DiffKind.CapabilityGainedTelemetry;
+	if (kind === "isolated-storage") return DiffKind.CapabilityGainedIsolatedStorage;
+	if (kind === "file") return DiffKind.CapabilityGainedFile;
+	if (kind === "event" && op === "publish") return DiffKind.CapabilityGainedEventPublish;
+	if ((kind === "codeunit" || kind === "page" || kind === "report") && op === "execute") {
+		const extra = (fact as { extra?: { kind?: string } }).extra;
+		const dispatchUnresolved = extra?.kind === "dispatch" && fact.resourceId === undefined;
+		if (dispatchUnresolved) return DiffKind.CapabilityGainedDynamicDispatch;
+	}
+	return undefined;
+}
+
+/** Key for matching facts across snapshots. */
+function factKey(fact: CapabilityFact): string {
+	return `${fact.op}|${fact.resourceKind}|${String(fact.resourceId ?? "")}`;
+}
+
+function makeFinding(
+	kind: CapabilityDetails["kind"],
+	subjectId: string,
+	indexes: DiffIndexes,
+	details: CapabilityDetails,
+	secondaryKey: string,
+	comparisonCone: readonly string[],
+): CapabilityFinding {
+	const origin = indexes.originByNormalized.get(subjectId);
+	const display =
+		indexes.newDisplayByStableId.get(subjectId) ??
+		indexes.oldDisplayByStableId.get(subjectId) ??
+		subjectId;
+	return {
+		id: computeDiffFingerprint({
+			category: DiffCategory.Capabilities,
+			kind,
+			normalizedStableId: subjectId,
+			secondaryKey,
+		}),
+		category: DiffCategory.Capabilities,
+		kind,
+		severity: SEVERITY[kind] ?? "medium",
+		subject: {
+			normalizedStableId: subjectId,
+			oldOriginalStableId: origin?.oldOriginalStableId,
+			newStableId: origin?.newStableId,
+			displayName: display,
+		},
+		comparisonCone,
+		details,
+	};
+}
+
+export function diffCapabilities(
+	_oldSnap: unknown,
+	_newSnap: unknown,
+	indexes: DiffIndexes,
+	_opts: DiffEngineOptions,
+): CapabilityFinding[] {
+	const out: CapabilityFinding[] = [];
+
+	const allSubjects = new Set<string>();
+	for (const s of indexes.oldCapabilityFactsBySubject.keys()) allSubjects.add(s);
+	for (const s of indexes.newCapabilityFactsBySubject.keys()) allSubjects.add(s);
+
+	for (const subject of allSubjects) {
+		const oldFacts = indexes.oldCapabilityFactsBySubject.get(subject) ?? [];
+		const newFacts = indexes.newCapabilityFactsBySubject.get(subject) ?? [];
+		const oldByKey = new Map<string, CapabilityFact>();
+		const newByKey = new Map<string, CapabilityFact>();
+		for (const f of oldFacts) oldByKey.set(factKey(f), f);
+		for (const f of newFacts) newByKey.set(factKey(f), f);
+
+		// Gains: in new, not in old.
+		for (const [key, fact] of newByKey) {
+			if (oldByKey.has(key)) continue;
+			const gainKind = gainedKindFor(fact);
+			if (gainKind === undefined) continue;
+			out.push(
+				makeFinding(
+					gainKind as CapabilityDetails["kind"],
+					subject,
+					indexes,
+					{
+						kind: gainKind as CapabilityDetails["kind"],
+						resourceKind: fact.resourceKind,
+						resourceId: fact.resourceId !== undefined ? String(fact.resourceId) : undefined,
+						op: fact.op,
+					},
+					key,
+					[subject],
+				),
+			);
+		}
+
+		// Losses: in old, not in new. Emit provisional CapabilityLost; policy
+		// post-pass downgrades to CapabilityLostUnderCoverage when applicable.
+		for (const [key, fact] of oldByKey) {
+			if (newByKey.has(key)) continue;
+			out.push(
+				makeFinding(
+					DiffKind.CapabilityLost,
+					subject,
+					indexes,
+					{
+						kind: DiffKind.CapabilityLost,
+						resourceKind: fact.resourceKind,
+						resourceId: fact.resourceId !== undefined ? String(fact.resourceId) : undefined,
+						op: fact.op,
+					},
+					key,
+					[subject],
+				),
+			);
+		}
+	}
+
+	return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}