al-sem 0.0.1

package/src/engine/capability-cone.ts

@@ -0,0 +1,531 @@
+import type { CapabilityFact, CapabilityVia } from "../model/capability.ts";
+import type { CoverageReason, CoverageRecord, CoverageStatus } from "../model/coverage.ts";
+import type { Routine } from "../model/entities.ts";
+import type { Diagnostic } from "../model/finding.ts";
+import type { GraphEdge, GraphEdgeKind } from "../model/graph-edge.ts";
+import type { CallsiteId, EventId, RoutineId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+import type { RoutineSummary } from "../model/summary.ts";
+import type { Scc, SccInputGraph } from "./scc.ts";
+import { tarjanScc } from "./scc.ts";
+import { compareStrings } from "./uncertainty-util.ts";
+
+/** Dedup key for inherited capability facts — (op, resourceKind, resourceId, confidence). */
+export function inheritedFactKey(f: CapabilityFact): string {
+	return `${f.op}|${f.resourceKind}|${f.resourceId ?? ""}|${f.confidence}`;
+}
+
+function capabilityViaForEdgeKind(kind: GraphEdgeKind): CapabilityVia {
+	switch (kind) {
+		case "direct-call":
+			return "call";
+		case "object-run-resolved":
+		case "object-run-unresolved":
+			return "object-run";
+		case "event-dispatch":
+			return "event-dispatch";
+		case "implicit-trigger":
+			return "implicit-trigger";
+		case "dependency-export":
+			return "dependency";
+	}
+}
+
+function callsiteIdForEdge(edge: GraphEdge): CallsiteId | undefined {
+	if (
+		edge.kind === "direct-call" ||
+		edge.kind === "object-run-resolved" ||
+		edge.kind === "object-run-unresolved" ||
+		edge.kind === "dependency-export"
+	) {
+		return edge.callsiteId;
+	}
+	return undefined;
+}
+
+/** A resolved outgoing typed edge (only edges with a `to`). */
+export interface TypedOutEdge {
+	to: RoutineId;
+	kind: GraphEdgeKind;
+	callsite: CallsiteId | undefined;
+	eventId: EventId | undefined;
+}
+
+export interface TypedEdgeGraph {
+	nodes: RoutineId[];
+	/** Per-routine outgoing edges, each list sorted by edgeSortKey. */
+	outgoing: Map<RoutineId, TypedOutEdge[]>;
+	/** `from` of every object-run-unresolved edge (coverage reason source). */
+	unresolvedSources: Set<RoutineId>;
+}
+
+/** Total-order key for an out-edge. eventId disambiguates event-dispatch (no callsite). */
+function edgeSortKey(e: TypedOutEdge): string {
+	return `${e.kind}|${e.callsite ?? ""}|${e.eventId ?? ""}|${e.to}`;
+}
+
+export function buildTypedEdgeGraph(model: SemanticModel): TypedEdgeGraph {
+	const outgoing = new Map<RoutineId, TypedOutEdge[]>();
+	const unresolvedSources = new Set<RoutineId>();
+	for (const edge of model.typedEdges ?? []) {
+		if (edge.kind === "object-run-unresolved") {
+			unresolvedSources.add(edge.from);
+			continue;
+		}
+		if (!("to" in edge)) continue;
+		const out: TypedOutEdge = {
+			to: edge.to,
+			kind: edge.kind,
+			callsite: callsiteIdForEdge(edge),
+			eventId: "eventId" in edge ? edge.eventId : undefined,
+		};
+		const list = outgoing.get(edge.from);
+		if (list) list.push(out);
+		else outgoing.set(edge.from, [out]);
+	}
+	for (const list of outgoing.values()) {
+		list.sort((a, b) => compareStrings(edgeSortKey(a), edgeSortKey(b)));
+	}
+	const nodes = model.routines.map((r) => r.id).sort((a, b) => compareStrings(a, b));
+	return { nodes, outgoing, unresolvedSources };
+}
+
+/** Adapter so tarjanScc runs over the typed-edge graph. */
+export function typedEdgeSccInput(g: TypedEdgeGraph): SccInputGraph {
+	return { nodes: g.nodes, edgesByFrom: g.outgoing };
+}
+
+/** Per-routine direct facts grouped by dedup key (canonical rep per key). */
+export type RoutineDirectFacts = Map<RoutineId, Map<string, CapabilityFact>>;
+
+export interface ConeFactEntry {
+	rep: CapabilityFact; // the original DIRECT fact (re-tagged by consumers)
+	dist: number; // min hop distance from the SCC to a node carrying this key
+}
+export type ConeFacts = Map<string, ConeFactEntry>;
+
+/** Canonical representative key — deterministic, traversal-order-independent. */
+function repKey(f: CapabilityFact): string {
+	return [
+		inheritedFactKey(f),
+		String(f.subject ?? ""),
+		String(f.witnessOperationId ?? ""),
+		String(f.witnessCallsiteId ?? ""),
+		JSON.stringify(f.resourceArgSource ?? null),
+		JSON.stringify(f.extra ?? null),
+	].join("§");
+}
+
+/** Merge `entry` (already distance-shifted) into `dst` at `key`, keeping min dist; tie-break canonical rep. */
+function mergeCone(dst: ConeFacts, key: string, entry: ConeFactEntry): void {
+	const existing = dst.get(key);
+	if (existing === undefined) {
+		dst.set(key, entry);
+		return;
+	}
+	if (entry.dist < existing.dist) {
+		dst.set(key, entry);
+	} else if (
+		entry.dist === existing.dist &&
+		compareStrings(repKey(entry.rep), repKey(existing.rep)) < 0
+	) {
+		dst.set(key, entry);
+	}
+}
+
+/** Re-tag a representative direct fact as an inherited fact on `subject` via a first-hop edge. */
+function retag(rep: CapabilityFact, subject: RoutineId, edge: TypedOutEdge): CapabilityFact {
+	return {
+		...rep,
+		subject,
+		provenance: "inherited",
+		via: capabilityViaForEdgeKind(edge.kind),
+		witnessCallsiteId: edge.callsite,
+	};
+}
+
+/** Sort key for the final capabilityFactsInherited array (deterministic output order). */
+function inheritedOutputSortKey(f: CapabilityFact): string {
+	return [
+		f.op,
+		f.resourceKind,
+		String(f.resourceId ?? ""),
+		f.confidence,
+		f.via,
+		String(f.witnessCallsiteId ?? ""),
+		String(f.witnessOperationId ?? ""),
+	].join("|");
+}
+
+function sortInherited(facts: CapabilityFact[]): CapabilityFact[] {
+	return facts.sort((a, b) => compareStrings(inheritedOutputSortKey(a), inheritedOutputSortKey(b)));
+}
+
+/**
+ * Singleton non-recursive fast path. For each dedup key reachable through some out-edge, pick
+ * the out-edge minimizing (1 + downstream cone distance), tie-break by canonical edge key.
+ * `subject` can never appear in a successor cone (else they'd share an SCC), so its own facts
+ * are excluded automatically. Reads SUCCESSOR cones, which are alive when this is called from
+ * the fused pass (composeInheritedCones emits before freeing) and from the unit tests (which
+ * use the non-freeing buildFactCones below).
+ */
+export function inheritedFactsForSingleton(
+	subject: RoutineId,
+	g: TypedEdgeGraph,
+	sccIdByRoutine: Map<RoutineId, number>,
+	cones: Map<number, ConeFacts>,
+): CapabilityFact[] {
+	const best = new Map<string, { rep: CapabilityFact; dist: number; edge: TypedOutEdge }>();
+	for (const edge of g.outgoing.get(subject) ?? []) {
+		const yj = sccIdByRoutine.get(edge.to);
+		if (yj === undefined) continue;
+		const ycone = cones.get(yj);
+		if (ycone === undefined) continue;
+		for (const [key, entry] of ycone) {
+			const cand = { rep: entry.rep, dist: entry.dist + 1, edge };
+			const cur = best.get(key);
+			if (cur === undefined || cand.dist < cur.dist) {
+				best.set(key, cand);
+			} else if (cand.dist === cur.dist) {
+				if (compareStrings(edgeSortKey(edge), edgeSortKey(cur.edge)) < 0) best.set(key, cand);
+			}
+		}
+	}
+	const out: CapabilityFact[] = [];
+	for (const { rep, edge } of best.values()) out.push(retag(rep, subject, edge));
+	return sortInherited(out);
+}
+
+/**
+ * Set-correct, deterministic path for routines in recursive SCCs (rare). BFS expands ONLY over
+ * intra-SCC edges to discover each sibling member's first hop from `subject`; for every edge
+ * that LEAVES the SCC, it pulls the target's full precomputed cone attributed to the current
+ * first hop (the cone already holds the entire downstream closure, so it must not traverse
+ * further). Self is never enqueued, so self facts are excluded. First-reached-wins in
+ * sorted-edge BFS order makes the winner deterministic.
+ */
+export function inheritedFactsByBfs(
+	subject: RoutineId,
+	g: TypedEdgeGraph,
+	direct: RoutineDirectFacts,
+	sccIdByRoutine: Map<RoutineId, number>,
+	cones: Map<number, ConeFacts>,
+): CapabilityFact[] {
+	const myScc = sccIdByRoutine.get(subject);
+	const seen = new Set<string>();
+	const out: CapabilityFact[] = [];
+	const visited = new Set<RoutineId>([subject]);
+	type QI = { id: RoutineId; firstHop: TypedOutEdge };
+	const queue: QI[] = [];
+	for (const edge of g.outgoing.get(subject) ?? []) {
+		if (!visited.has(edge.to)) {
+			visited.add(edge.to);
+			queue.push({ id: edge.to, firstHop: edge });
+		}
+	}
+	while (queue.length > 0) {
+		const item = queue.shift();
+		if (item === undefined) break;
+		const { id, firstHop } = item;
+		if (sccIdByRoutine.get(id) === myScc) {
+			// sibling member: emit its own direct facts (attributed to firstHop), keep walking intra-SCC
+			for (const [key, rep] of direct.get(id) ?? []) {
+				if (!seen.has(key)) {
+					seen.add(key);
+					out.push(retag(rep, subject, firstHop));
+				}
+			}
+			for (const edge of g.outgoing.get(id) ?? []) {
+				if (!visited.has(edge.to)) {
+					visited.add(edge.to);
+					queue.push({ id: edge.to, firstHop });
+				}
+			}
+		} else {
+			// downstream entry: pull its whole cone (includes its own direct at dist 0), do NOT recurse
+			const yj = sccIdByRoutine.get(id);
+			const ycone = yj !== undefined ? cones.get(yj) : undefined;
+			if (ycone !== undefined) {
+				for (const [key, entry] of ycone) {
+					if (!seen.has(key)) {
+						seen.add(key);
+						out.push(retag(entry.rep, subject, firstHop));
+					}
+				}
+			}
+		}
+	}
+	return sortInherited(out);
+}
+
+/** Minimal per-routine direct coverage the cone roll-up needs. */
+export type RoutineDirectCoverage = Map<
+	RoutineId,
+	{ directStatus: CoverageStatus; reasons: readonly CoverageReason[] }
+>;
+
+export interface CoverageCone {
+	complete: boolean;
+	reasons: CoverageReason[]; // sorted, deduped
+	unknownTargets: string[]; // sorted, deduped
+}
+
+/**
+ * Distinct successor SCCs per SCC (cross-SCC edges only). Shared by every cone build so the
+ * test-only builders and the fused production pass use the SAME successor enumeration.
+ */
+function buildSuccSccs(
+	g: TypedEdgeGraph,
+	sccs: Scc[],
+	sccIdByRoutine: Map<RoutineId, number>,
+): Set<number>[] {
+	const succSccs: Set<number>[] = sccs.map(() => new Set<number>());
+	for (let i = 0; i < sccs.length; i++) {
+		const scc = sccs[i];
+		if (scc === undefined) continue;
+		for (const m of scc.members) {
+			for (const e of g.outgoing.get(m) ?? []) {
+				const yj = sccIdByRoutine.get(e.to);
+				if (yj !== undefined && yj !== i) succSccs[i]?.add(yj);
+			}
+		}
+	}
+	return succSccs;
+}
+
+/**
+ * Build one SCC's fact cone: members' direct facts at dist 0, plus each (already-built)
+ * successor cone shifted to dist + 1. Shared by buildFactCones and composeInheritedCones.
+ */
+function factConeForScc(
+	members: readonly RoutineId[],
+	succIds: Set<number>,
+	factCones: Map<number, ConeFacts>,
+	direct: RoutineDirectFacts,
+): ConeFacts {
+	const cone: ConeFacts = new Map();
+	for (const m of members) {
+		for (const [key, f] of direct.get(m) ?? []) mergeCone(cone, key, { rep: f, dist: 0 });
+	}
+	for (const y of succIds) {
+		const yc = factCones.get(y);
+		if (yc === undefined) continue;
+		for (const [key, entry] of yc) mergeCone(cone, key, { rep: entry.rep, dist: entry.dist + 1 });
+	}
+	return cone;
+}
+
+/**
+ * Build one SCC's coverage cone (includes self; identical for every member). Mirrors
+ * composeCoverage: reasons are unioned ONLY from members whose directStatus is non-complete,
+ * plus "object-run-unresolved" when a member is an unresolved source. A member with no coverage
+ * entry contributes nothing and is not added to unknownTargets. Rolls up each (already-built)
+ * successor cone. Shared by buildCoverageCones and composeInheritedCones.
+ */
+function coverageConeForScc(
+	members: readonly RoutineId[],
+	succIds: Set<number>,
+	covCones: Map<number, CoverageCone>,
+	cov: RoutineDirectCoverage,
+	unresolvedSources: Set<RoutineId>,
+): CoverageCone {
+	let complete = true;
+	const reasonSet = new Set<CoverageReason>();
+	const unknownSet = new Set<string>();
+	for (const m of members) {
+		if (unresolvedSources.has(m)) {
+			complete = false;
+			reasonSet.add("object-run-unresolved");
+		}
+		const c = cov.get(m);
+		if (c === undefined) continue;
+		if (c.directStatus === "partial" || c.directStatus === "unknown") {
+			complete = false;
+			unknownSet.add(m);
+			for (const r of c.reasons) reasonSet.add(r);
+		}
+	}
+	for (const y of succIds) {
+		const yc = covCones.get(y);
+		if (yc === undefined) continue;
+		if (!yc.complete) complete = false;
+		for (const r of yc.reasons) reasonSet.add(r);
+		for (const t of yc.unknownTargets) unknownSet.add(t);
+	}
+	return {
+		complete,
+		reasons: [...reasonSet].sort((a, b) => compareStrings(a, b)),
+		unknownTargets: [...unknownSet].sort((a, b) => compareStrings(a, b)),
+	};
+}
+
+/**
+ * Per-SCC coverage cone (includes self; identical for every member). Mirrors composeCoverage:
+ * reasons are unioned ONLY from members whose directStatus is non-complete, plus
+ * "object-run-unresolved" when a member is an unresolved source. A member with no coverage
+ * entry contributes nothing and is not added to unknownTargets.
+ *
+ * Retains ALL cones (no refcount freeing) — this is the test-only pure recurrence; production
+ * memory-bounding is done by the future fused pass composeInheritedCones. Processes SCCs in
+ * reverse-topological order (downstream first).
+ */
+export function buildCoverageCones(
+	g: TypedEdgeGraph,
+	sccs: Scc[],
+	sccIdByRoutine: Map<RoutineId, number>,
+	cov: RoutineDirectCoverage,
+): Map<number, CoverageCone> {
+	const succSccs = buildSuccSccs(g, sccs, sccIdByRoutine);
+	const cones = new Map<number, CoverageCone>();
+	for (let i = 0; i < sccs.length; i++) {
+		const scc = sccs[i];
+		if (scc === undefined) continue;
+		cones.set(
+			i,
+			coverageConeForScc(scc.members, succSccs[i] ?? new Set(), cones, cov, g.unresolvedSources),
+		);
+	}
+	return cones;
+}
+
+/**
+ * Per-SCC reachable fact cone (including the SCC's own members' direct facts at dist 0).
+ * Processed in reverse-topological order so downstream SCCs are done first.
+ *
+ * This is the test-only pure recurrence: it RETAINS every SCC's cone in the returned Map so
+ * callers (and the singleton/recursive helpers above) can read any SCC's successor cones.
+ * Production memory-bounding (predecessor-refcount freeing of consumed downstream cones) is the
+ * job of the future fused pass `composeInheritedCones`, NOT this function.
+ */
+export function buildFactCones(
+	g: TypedEdgeGraph,
+	sccs: Scc[],
+	sccIdByRoutine: Map<RoutineId, number>,
+	direct: RoutineDirectFacts,
+): Map<number, ConeFacts> {
+	// distinct successor SCCs per SCC (needed to pull downstream cones at dist + 1)
+	const succSccs = buildSuccSccs(g, sccs, sccIdByRoutine);
+	const cones = new Map<number, ConeFacts>();
+	for (let i = 0; i < sccs.length; i++) {
+		const scc = sccs[i];
+		if (scc === undefined) continue;
+		cones.set(i, factConeForScc(scc.members, succSccs[i] ?? new Set(), cones, direct));
+	}
+	return cones;
+}
+
+export interface InheritedConeResult {
+	inherited: CapabilityFact[];
+	coverage: CoverageRecord;
+}
+
+/**
+ * Compute capabilityFactsInherited + coverage for every NON-leaf routine via a single fused
+ * bottom-up SCC-cone pass. Reads each routine's direct facts + directStatus from `final`
+ * (the task-17 pass already attached them; leaf routines carry authoritative summaries).
+ *
+ * One reverse-topological walk: per SCC, build its fact cone + coverage cone (pulling already-
+ * built successor cones), emit per-routine results for its non-leaf members (successor cones are
+ * still alive), then refcount-free downstream cones whose last predecessor has now been
+ * processed. Bounds memory without re-traversing the graph.
+ *
+ * Engine-never-throws: on internal failure, returns an empty map and pushes a diagnostic; the
+ * caller falls back to empty inherited facts + baseline coverage.
+ */
+export function composeInheritedCones(
+	model: SemanticModel,
+	final: Map<RoutineId, RoutineSummary>,
+	isLeaf: (r: Routine) => boolean,
+	diagnostics?: Diagnostic[],
+): Map<RoutineId, InheritedConeResult> {
+	const out = new Map<RoutineId, InheritedConeResult>();
+	try {
+		const g = buildTypedEdgeGraph(model);
+
+		const routineById = new Map<RoutineId, Routine>();
+		for (const r of model.routines) routineById.set(r.id, r);
+
+		// direct facts (canonical rep per dedup key) + direct coverage, for ALL routines in `final`
+		const direct: RoutineDirectFacts = new Map();
+		const cov: RoutineDirectCoverage = new Map();
+		for (const r of model.routines) {
+			const s = final.get(r.id);
+			if (s === undefined) continue;
+			const byKey = new Map<string, CapabilityFact>();
+			for (const f of s.capabilityFactsDirect ?? []) {
+				const k = inheritedFactKey(f);
+				const cur = byKey.get(k);
+				if (cur === undefined || compareStrings(repKey(f), repKey(cur)) < 0) byKey.set(k, f);
+			}
+			if (byKey.size > 0) direct.set(r.id, byKey);
+			const c = s.coverage;
+			// A routine with no coverage record contributes NOTHING to the coverage cone:
+			// it is not forced to "unknown" and is not added to unknownTargets. The roll-up
+			// below skips routines absent from `cov` via its `if (c === undefined) continue;`.
+			if (c !== undefined) cov.set(r.id, { directStatus: c.directStatus, reasons: c.reasons });
+		}
+
+		const { sccs, sccIdByRoutine } = tarjanScc(typedEdgeSccInput(g));
+
+		// distinct successor SCCs per SCC + predecessor refcounts (shared by fact + coverage cones)
+		const succSccs = buildSuccSccs(g, sccs, sccIdByRoutine);
+		const remainingUses = sccs.map(() => 0);
+		for (let i = 0; i < sccs.length; i++) {
+			for (const y of succSccs[i] ?? []) remainingUses[y] = (remainingUses[y] ?? 0) + 1;
+		}
+
+		const factCones = new Map<number, ConeFacts>();
+		const covCones = new Map<number, CoverageCone>();
+
+		for (let i = 0; i < sccs.length; i++) {
+			const scc = sccs[i];
+			if (scc === undefined) continue;
+
+			const succIds = succSccs[i] ?? new Set<number>();
+
+			// --- build this SCC's fact + coverage cones (pulling already-built successor cones) ---
+			const fcone = factConeForScc(scc.members, succIds, factCones, direct);
+			factCones.set(i, fcone);
+			const ccone = coverageConeForScc(scc.members, succIds, covCones, cov, g.unresolvedSources);
+			covCones.set(i, ccone);
+
+			// --- emit per-routine results for this SCC's NON-leaf members (cones still alive) ---
+			const recursive = scc.recursive;
+			for (const m of scc.members) {
+				const routine = routineById.get(m);
+				if (routine === undefined || isLeaf(routine)) continue;
+				const inherited = recursive
+					? inheritedFactsByBfs(m, g, direct, sccIdByRoutine, factCones)
+					: inheritedFactsForSingleton(m, g, sccIdByRoutine, factCones);
+				const dStatus = cov.get(m)?.directStatus ?? "unknown";
+				out.set(m, {
+					inherited,
+					coverage: {
+						subject: m,
+						directStatus: dStatus,
+						inheritedStatus: ccone.complete ? "complete" : "partial",
+						reasons: ccone.reasons,
+						unknownTargets: ccone.unknownTargets,
+					},
+				});
+			}
+
+			// --- refcount-free downstream cones whose last predecessor (this SCC) is now done ---
+			for (const y of succIds) {
+				remainingUses[y] = (remainingUses[y] ?? 0) - 1;
+				if ((remainingUses[y] ?? 0) <= 0) {
+					factCones.delete(y);
+					covCones.delete(y);
+				}
+			}
+		}
+	} catch (err) {
+		diagnostics?.push({
+			severity: "warning",
+			stage: "summarize",
+			message: `capability-cone composition failed: ${err instanceof Error ? err.message : String(err)}`,
+		});
+		return new Map();
+	}
+	return out;
+}