al-sem 0.0.1

package/src/diff/diff-indexes.ts

@@ -0,0 +1,199 @@
+import type { CapabilityFact } from "../model/capability.ts";
+import type { CoverageRecord } from "../model/coverage.ts";
+import type { PermissionFact } from "../model/permission.ts";
+import type {
+	CapabilitySnapshot,
+	ContractFact,
+	EventDeclaration,
+	SchemaFact,
+} from "../snapshot/types.ts";
+import type { RenameDiagnostic, RenameTable } from "./diff-renames.ts";
+import { validateOverlayAgainstSnapshots } from "./diff-renames.ts";
+
+export interface SubjectOrigin {
+	normalizedStableId: string;
+	oldOriginalStableId?: string;
+	newStableId?: string;
+	renameApplied: boolean;
+}
+
+export interface DiffIndexes {
+	// Per-snapshot display lookup keyed by normalized id.
+	oldDisplayByStableId: Map<string, string>;
+	newDisplayByStableId: Map<string, string>;
+	// Origin tracking — produces renderer-side "renamed from X" rendering.
+	originByNormalized: Map<string, SubjectOrigin>;
+	// Fact lookups, all OLD side rename-normalized.
+	oldContractsBySubject: Map<string, ContractFact>;
+	newContractsBySubject: Map<string, ContractFact>;
+	oldSchemaBySubject: Map<string, SchemaFact[]>;
+	newSchemaBySubject: Map<string, SchemaFact[]>;
+	oldPermissionsBySubject: Map<string, PermissionFact[]>;
+	newPermissionsBySubject: Map<string, PermissionFact[]>;
+	oldEventsBySubject: Map<string, EventDeclaration[]>;
+	newEventsBySubject: Map<string, EventDeclaration[]>;
+	oldCapabilityFactsBySubject: Map<string, CapabilityFact[]>;
+	newCapabilityFactsBySubject: Map<string, CapabilityFact[]>;
+	oldCoverageBySubject: Map<string, CoverageRecord>;
+	newCoverageBySubject: Map<string, CoverageRecord>;
+	// Stale-rename diagnostics surfaced here since membership is now known.
+	renameDiagnostics: readonly RenameDiagnostic[];
+}
+
+function normalize(id: string, renameTable: RenameTable): string {
+	const entry = renameTable.get(id);
+	return entry?.newId ?? id;
+}
+
+function pushByKey<V>(map: Map<string, V[]>, key: string, value: V): void {
+	const list = map.get(key) ?? [];
+	list.push(value);
+	map.set(key, list);
+}
+
+/**
+ * Extract the primary subject id from a PermissionFact.
+ *
+ * `DeclaredPermissionFact` groups by `permissionSet` (no routine subject).
+ * `RequiredPermissionFact` groups by `subject` (the routine the requirement
+ * is attached to). The `kind` discriminator selects the right field.
+ */
+function permissionFactSubject(fact: PermissionFact): string {
+	if (fact.kind === "required") {
+		return fact.subject;
+	}
+	// declared: group by permissionSet
+	return fact.permissionSet;
+}
+
+export function buildDiffIndexes(
+	oldSnap: CapabilitySnapshot,
+	newSnap: CapabilitySnapshot,
+	renameTable: RenameTable,
+): DiffIndexes {
+	const oldDisplayByStableId = new Map<string, string>();
+	const newDisplayByStableId = new Map<string, string>();
+	const originByNormalized = new Map<string, SubjectOrigin>();
+
+	// Old identities — normalize.
+	for (let i = 0; i < oldSnap.identities.stableIds.length; i++) {
+		const id = oldSnap.identities.stableIds[i] ?? "";
+		const display = oldSnap.identities.displayNames[i] ?? "";
+		if (id === "") continue;
+		const normalized = normalize(id, renameTable);
+		oldDisplayByStableId.set(normalized, display);
+		const renameApplied = normalized !== id;
+		originByNormalized.set(normalized, {
+			normalizedStableId: normalized,
+			oldOriginalStableId: renameApplied ? id : undefined,
+			renameApplied,
+		});
+	}
+
+	// New identities — never renamed; populate display + fold into origin.
+	for (let i = 0; i < newSnap.identities.stableIds.length; i++) {
+		const id = newSnap.identities.stableIds[i] ?? "";
+		const display = newSnap.identities.displayNames[i] ?? "";
+		if (id === "") continue;
+		newDisplayByStableId.set(id, display);
+		const origin = originByNormalized.get(id);
+		if (origin !== undefined) {
+			origin.newStableId = id;
+		} else {
+			originByNormalized.set(id, {
+				normalizedStableId: id,
+				newStableId: id,
+				renameApplied: false,
+			});
+		}
+	}
+
+	// ContractFacts — keyed by stableId (the primary subject field on ContractFact).
+	const oldContractsBySubject = new Map<string, ContractFact>();
+	for (const fact of oldSnap.contractFacts) {
+		oldContractsBySubject.set(normalize(fact.stableId, renameTable), fact);
+	}
+	const newContractsBySubject = new Map<string, ContractFact>();
+	for (const fact of newSnap.contractFacts) {
+		newContractsBySubject.set(fact.stableId, fact);
+	}
+
+	// SchemaFacts — keyed by stableId (the primary subject field on SchemaFact).
+	const oldSchemaBySubject = new Map<string, SchemaFact[]>();
+	for (const fact of oldSnap.schemaFacts) {
+		pushByKey(oldSchemaBySubject, normalize(fact.stableId, renameTable), fact);
+	}
+	const newSchemaBySubject = new Map<string, SchemaFact[]>();
+	for (const fact of newSnap.schemaFacts) {
+		pushByKey(newSchemaBySubject, fact.stableId, fact);
+	}
+
+	// PermissionFacts — keyed by permissionFactSubject (declared→permissionSet,
+	// required→subject).
+	const oldPermissionsBySubject = new Map<string, PermissionFact[]>();
+	for (const fact of oldSnap.permissionFacts) {
+		pushByKey(oldPermissionsBySubject, normalize(permissionFactSubject(fact), renameTable), fact);
+	}
+	const newPermissionsBySubject = new Map<string, PermissionFact[]>();
+	for (const fact of newSnap.permissionFacts) {
+		pushByKey(newPermissionsBySubject, permissionFactSubject(fact), fact);
+	}
+
+	// EventDeclarations — keyed by routine (StableRoutineId).
+	const oldEventsBySubject = new Map<string, EventDeclaration[]>();
+	for (const decl of oldSnap.eventDeclarations) {
+		pushByKey(oldEventsBySubject, normalize(decl.routine, renameTable), decl);
+	}
+	const newEventsBySubject = new Map<string, EventDeclaration[]>();
+	for (const decl of newSnap.eventDeclarations) {
+		pushByKey(newEventsBySubject, decl.routine, decl);
+	}
+
+	// CapabilityFacts — keyed by subject (RoutineId).
+	const oldCapabilityFactsBySubject = new Map<string, CapabilityFact[]>();
+	for (const fact of oldSnap.capabilityFacts) {
+		pushByKey(oldCapabilityFactsBySubject, normalize(fact.subject, renameTable), fact);
+	}
+	const newCapabilityFactsBySubject = new Map<string, CapabilityFact[]>();
+	for (const fact of newSnap.capabilityFacts) {
+		pushByKey(newCapabilityFactsBySubject, fact.subject, fact);
+	}
+
+	// CoverageRecords — keyed by subject (RoutineId).
+	const oldCoverageBySubject = new Map<string, CoverageRecord>();
+	for (const rec of oldSnap.coverage) {
+		oldCoverageBySubject.set(normalize(rec.subject, renameTable), rec);
+	}
+	const newCoverageBySubject = new Map<string, CoverageRecord>();
+	for (const rec of newSnap.coverage) {
+		newCoverageBySubject.set(rec.subject, rec);
+	}
+
+	// Stale-rename diagnostics now that snapshot membership is known.
+	const oldIds = new Set(oldSnap.identities.stableIds);
+	const newIds = new Set(newSnap.identities.stableIds);
+	const overlayLike: Record<string, string> = {};
+	for (const [oldId, entry] of renameTable) {
+		overlayLike[oldId] = entry.newId;
+	}
+	const renameDiagnostics = validateOverlayAgainstSnapshots(overlayLike, oldIds, newIds);
+
+	return {
+		oldDisplayByStableId,
+		newDisplayByStableId,
+		originByNormalized,
+		oldContractsBySubject,
+		newContractsBySubject,
+		oldSchemaBySubject,
+		newSchemaBySubject,
+		oldPermissionsBySubject,
+		newPermissionsBySubject,
+		oldEventsBySubject,
+		newEventsBySubject,
+		oldCapabilityFactsBySubject,
+		newCapabilityFactsBySubject,
+		oldCoverageBySubject,
+		newCoverageBySubject,
+		renameDiagnostics,
+	};
+}

package/src/diff/diff-permissions.ts

@@ -0,0 +1,260 @@
+import type { RequiredPermissionFact } from "../model/permission.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 PermissionDetails {
+	kind:
+		| DiffKind.PermissionRightsExpanded
+		| DiffKind.PermissionRightsContracted
+		| DiffKind.PermissionTargetAdded
+		| DiffKind.PermissionTargetRemoved;
+	targetKind: string;
+	targetId: string;
+	oldRights?: string[];
+	newRights?: string[];
+}
+
+export interface PermissionFinding {
+	id: string;
+	category: DiffCategory.Permissions;
+	kind: DiffKind;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	subject: {
+		normalizedStableId: string;
+		oldOriginalStableId?: string;
+		newStableId?: string;
+		displayName: string;
+	};
+	comparisonCone: readonly string[];
+	details: PermissionDetails;
+}
+
+const SEVERITY: Partial<Record<DiffKind, PermissionFinding["severity"]>> = {
+	[DiffKind.PermissionRightsExpanded]: "high",
+	[DiffKind.PermissionTargetAdded]: "high",
+	[DiffKind.PermissionRightsContracted]: "low",
+	[DiffKind.PermissionTargetRemoved]: "low",
+};
+
+/**
+ * Returns true when newRights is a strict superset of oldRights.
+ * All elements of oldRights are present in newRights, and newRights has more.
+ */
+function isExpansion(oldRights: readonly string[], newRights: readonly string[]): boolean {
+	const oldSet = new Set(oldRights);
+	const newSet = new Set(newRights);
+	if (newSet.size <= oldSet.size) return false;
+	for (const r of oldSet) {
+		if (!newSet.has(r)) return false;
+	}
+	return true;
+}
+
+/**
+ * Returns true when newRights is a strict subset of oldRights.
+ * All elements of newRights are present in oldRights, and oldRights has more.
+ */
+function isContraction(oldRights: readonly string[], newRights: readonly string[]): boolean {
+	const oldSet = new Set(oldRights);
+	const newSet = new Set(newRights);
+	if (oldSet.size <= newSet.size) return false;
+	for (const r of newSet) {
+		if (!oldSet.has(r)) return false;
+	}
+	return true;
+}
+
+function makeFinding(
+	kind: PermissionDetails["kind"],
+	subjectId: string,
+	indexes: DiffIndexes,
+	details: PermissionDetails,
+	secondaryKey: string,
+): PermissionFinding {
+	const origin = indexes.originByNormalized.get(subjectId);
+	const display =
+		indexes.newDisplayByStableId.get(subjectId) ??
+		indexes.oldDisplayByStableId.get(subjectId) ??
+		subjectId;
+	return {
+		id: computeDiffFingerprint({
+			category: DiffCategory.Permissions,
+			kind,
+			normalizedStableId: subjectId,
+			secondaryKey,
+		}),
+		category: DiffCategory.Permissions,
+		kind,
+		severity: SEVERITY[kind] ?? "medium",
+		subject: {
+			normalizedStableId: subjectId,
+			oldOriginalStableId: origin?.oldOriginalStableId,
+			newStableId: origin?.newStableId,
+			displayName: display,
+		},
+		comparisonCone: [subjectId],
+		details,
+	};
+}
+
+/**
+ * Diff required permission footprints between two snapshots.
+ *
+ * Only `RequiredPermissionFact` (kind === "required") are compared — they
+ * carry a `subject` routine id and a `target`/`targetKind`/`rights` tuple.
+ * `DeclaredPermissionFact` (kind === "declared") has a different shape
+ * (grouped by permissionSet, no routine subject) and is out of scope for
+ * this delta; a future task can add a declared-permission diff pass.
+ *
+ * Rights comparison uses set semantics over `PermissionRight[]`:
+ *  - strict superset  → PermissionRightsExpanded (high)
+ *  - strict subset    → PermissionRightsContracted (low)
+ *  - mixed change     → PermissionRightsExpanded (any new right is dangerous)
+ */
+export function diffPermissions(
+	_oldSnap: unknown,
+	_newSnap: unknown,
+	indexes: DiffIndexes,
+	_opts: DiffEngineOptions,
+): PermissionFinding[] {
+	const out: PermissionFinding[] = [];
+
+	const allSubjects = new Set<string>();
+	for (const s of indexes.oldPermissionsBySubject.keys()) allSubjects.add(s);
+	for (const s of indexes.newPermissionsBySubject.keys()) allSubjects.add(s);
+
+	for (const subject of allSubjects) {
+		// Filter to RequiredPermissionFact only — DeclaredPermissionFact has no
+		// (subject, target) shape comparable here.
+		const oldFacts = (indexes.oldPermissionsBySubject.get(subject) ?? []).filter(
+			(f): f is RequiredPermissionFact => f.kind === "required",
+		);
+		const newFacts = (indexes.newPermissionsBySubject.get(subject) ?? []).filter(
+			(f): f is RequiredPermissionFact => f.kind === "required",
+		);
+
+		const oldByTarget = new Map<string, { targetKind: string; rights: string[] }>();
+		const newByTarget = new Map<string, { targetKind: string; rights: string[] }>();
+
+		for (const f of oldFacts) {
+			const tk = f.targetKind;
+			const tid = String(f.target);
+			oldByTarget.set(`${tk}|${tid}`, { targetKind: tk, rights: f.rights as string[] });
+		}
+		for (const f of newFacts) {
+			const tk = f.targetKind;
+			const tid = String(f.target);
+			newByTarget.set(`${tk}|${tid}`, { targetKind: tk, rights: f.rights as string[] });
+		}
+
+		// Walk old targets — detect removals and rights changes.
+		for (const [key, oldEntry] of oldByTarget) {
+			const newEntry = newByTarget.get(key);
+			const sepIdx = key.indexOf("|");
+			const tk = key.slice(0, sepIdx);
+			const tid = key.slice(sepIdx + 1);
+
+			if (newEntry === undefined) {
+				out.push(
+					makeFinding(
+						DiffKind.PermissionTargetRemoved,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.PermissionTargetRemoved,
+							targetKind: tk,
+							targetId: tid,
+							oldRights: oldEntry.rights,
+						},
+						key,
+					),
+				);
+				continue;
+			}
+
+			// Compare rights as sets — skip when identical.
+			const oldSet = new Set(oldEntry.rights);
+			const newSet = new Set(newEntry.rights);
+			const sameSize = oldSet.size === newSet.size;
+			const identical = sameSize && [...oldSet].every((r) => newSet.has(r));
+			if (identical) continue;
+
+			if (isExpansion(oldEntry.rights, newEntry.rights)) {
+				out.push(
+					makeFinding(
+						DiffKind.PermissionRightsExpanded,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.PermissionRightsExpanded,
+							targetKind: tk,
+							targetId: tid,
+							oldRights: oldEntry.rights,
+							newRights: newEntry.rights,
+						},
+						key,
+					),
+				);
+			} else if (isContraction(oldEntry.rights, newEntry.rights)) {
+				out.push(
+					makeFinding(
+						DiffKind.PermissionRightsContracted,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.PermissionRightsContracted,
+							targetKind: tk,
+							targetId: tid,
+							oldRights: oldEntry.rights,
+							newRights: newEntry.rights,
+						},
+						key,
+					),
+				);
+			} else {
+				// Mixed change (some rights added, some removed): treat as expansion
+				// because any newly granted right is the dangerous direction.
+				out.push(
+					makeFinding(
+						DiffKind.PermissionRightsExpanded,
+						subject,
+						indexes,
+						{
+							kind: DiffKind.PermissionRightsExpanded,
+							targetKind: tk,
+							targetId: tid,
+							oldRights: oldEntry.rights,
+							newRights: newEntry.rights,
+						},
+						key,
+					),
+				);
+			}
+		}
+
+		// Walk new targets — detect additions (not present in old).
+		for (const [key, newEntry] of newByTarget) {
+			if (oldByTarget.has(key)) continue;
+			const sepIdx = key.indexOf("|");
+			const tk = key.slice(0, sepIdx);
+			const tid = key.slice(sepIdx + 1);
+			out.push(
+				makeFinding(
+					DiffKind.PermissionTargetAdded,
+					subject,
+					indexes,
+					{
+						kind: DiffKind.PermissionTargetAdded,
+						targetKind: tk,
+						targetId: tid,
+						newRights: newEntry.rights,
+					},
+					key,
+				),
+			);
+		}
+	}
+
+	return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/src/diff/diff-policy.ts

@@ -0,0 +1,101 @@
+import type { CoverageStatus } from "../model/coverage.ts";
+import { DiffKind } from "./diff-identity.ts";
+import type { DiffIndexes } from "./diff-indexes.ts";
+
+export interface PolicyDiagnostic {
+	kind: "coverage-incomplete";
+	subject: string;
+	cone: "old" | "new" | "both";
+}
+
+export interface PolicyOptions {
+	coveragePolicy: "loose" | "strict";
+}
+
+/** A finding's shape post-categorisation; minimum the post-pass needs. */
+export interface PolicyFinding {
+	id: string;
+	kind: DiffKind;
+	comparisonCone: readonly string[];
+	coverageState?: { old: CoverageStatus; new: CoverageStatus };
+	[k: string]: unknown;
+}
+
+function coneStatus(
+	cone: readonly string[],
+	source: Map<string, { inheritedStatus: CoverageStatus }>,
+): CoverageStatus {
+	let worst: CoverageStatus = "complete";
+	for (const id of cone) {
+		const rec = source.get(id);
+		const s: CoverageStatus = rec?.inheritedStatus ?? "unknown";
+		if (s === "unknown") return "unknown";
+		if (s === "partial") worst = "partial";
+	}
+	return worst;
+}
+
+const COVERAGE_SENSITIVE_KINDS: ReadonlySet<DiffKind> = new Set([
+	DiffKind.CapabilityLost,
+	DiffKind.CapabilityGainedWrite,
+	DiffKind.CapabilityGainedRead,
+	DiffKind.CapabilityGainedCommit,
+	DiffKind.CapabilityGainedHttp,
+	DiffKind.CapabilityGainedTelemetry,
+	DiffKind.CapabilityGainedIsolatedStorage,
+	DiffKind.CapabilityGainedFile,
+	DiffKind.CapabilityGainedDynamicDispatch,
+	DiffKind.CapabilityGainedEventPublish,
+]);
+
+export function applyCoveragePolicy<T extends PolicyFinding>(
+	findings: readonly T[],
+	indexes: DiffIndexes,
+	opts: PolicyOptions,
+): { findings: T[]; diagnostics: PolicyDiagnostic[] } {
+	const outFindings: T[] = [];
+	const diagnostics: PolicyDiagnostic[] = [];
+
+	for (const finding of findings) {
+		if (!COVERAGE_SENSITIVE_KINDS.has(finding.kind)) {
+			outFindings.push(finding);
+			continue;
+		}
+		const oldStatus = coneStatus(
+			finding.comparisonCone,
+			indexes.oldCoverageBySubject as unknown as Map<string, { inheritedStatus: CoverageStatus }>,
+		);
+		const newStatus = coneStatus(
+			finding.comparisonCone,
+			indexes.newCoverageBySubject as unknown as Map<string, { inheritedStatus: CoverageStatus }>,
+		);
+		const annotated: T = { ...finding, coverageState: { old: oldStatus, new: newStatus } };
+
+		const oldPartial = oldStatus !== "complete";
+		const newPartial = newStatus !== "complete";
+
+		if (opts.coveragePolicy === "strict") {
+			if (oldPartial || newPartial) {
+				const cone: "old" | "new" | "both" =
+					oldPartial && newPartial ? "both" : oldPartial ? "old" : "new";
+				diagnostics.push({
+					kind: "coverage-incomplete",
+					subject: finding.comparisonCone[0] ?? "",
+					cone,
+				});
+				continue; // drop finding under strict
+			}
+			outFindings.push(annotated);
+			continue;
+		}
+
+		// Loose: downgrade CapabilityLost → CapabilityLostUnderCoverage when new is partial.
+		if (finding.kind === DiffKind.CapabilityLost && newPartial) {
+			outFindings.push({ ...annotated, kind: DiffKind.CapabilityLostUnderCoverage } as T);
+			continue;
+		}
+		outFindings.push(annotated);
+	}
+
+	return { findings: outFindings, diagnostics };
+}

package/src/diff/diff-preflight.ts

@@ -0,0 +1,66 @@
+import type { CapabilitySnapshot } from "../snapshot/types.ts";
+
+export type PreflightDiagnostic =
+	| { kind: "schema-version-mismatch"; old: number; new: number }
+	| { kind: "alsem-version-mismatch"; old: string; new: string; severity: "warning" | "error" }
+	| { kind: "app-identity-mismatch"; oldAppId: string; newAppId: string };
+
+export interface PreflightOptions {
+	coveragePolicy: "loose" | "strict";
+}
+
+export interface PreflightResult {
+	diagnostics: readonly PreflightDiagnostic[];
+	/** True when the engine should short-circuit and emit diagnostics only. */
+	fatal: boolean;
+}
+
+function primaryAppId(snap: CapabilitySnapshot): string | undefined {
+	const app = snap.apps[0];
+	return app ? (app as { appGuid?: string }).appGuid : undefined;
+}
+
+export function runPreflight(
+	oldSnap: CapabilitySnapshot,
+	newSnap: CapabilitySnapshot,
+	opts: PreflightOptions,
+): PreflightResult {
+	const diagnostics: PreflightDiagnostic[] = [];
+	let fatal = false;
+
+	// Schema version mismatch — always fatal.
+	if (oldSnap.schemaVersion !== newSnap.schemaVersion) {
+		diagnostics.push({
+			kind: "schema-version-mismatch",
+			old: oldSnap.schemaVersion as unknown as number,
+			new: newSnap.schemaVersion as unknown as number,
+		});
+		fatal = true;
+	}
+
+	// alsemVersion difference — warning loose, error strict.
+	if (oldSnap.alsemVersion !== newSnap.alsemVersion) {
+		const severity: "warning" | "error" = opts.coveragePolicy === "strict" ? "error" : "warning";
+		diagnostics.push({
+			kind: "alsem-version-mismatch",
+			old: oldSnap.alsemVersion,
+			new: newSnap.alsemVersion,
+			severity,
+		});
+		if (severity === "error") fatal = true;
+	}
+
+	// App identity mismatch — always fatal.
+	const oldAppId = primaryAppId(oldSnap);
+	const newAppId = primaryAppId(newSnap);
+	if (oldAppId !== undefined && newAppId !== undefined && oldAppId !== newAppId) {
+		diagnostics.push({
+			kind: "app-identity-mismatch",
+			oldAppId,
+			newAppId,
+		});
+		fatal = true;
+	}
+
+	return { diagnostics, fatal };
+}