al-sem 0.0.1

package/src/cli/fingerprint-witness.ts

@@ -0,0 +1,493 @@
+import type { CapabilityFact, CapabilityVia } from "../model/capability.ts";
+import type { CoverageRecord } from "../model/coverage.ts";
+import type { GraphEdge } from "../model/graph-edge.ts";
+import type { CallsiteId, OperationId } from "../model/ids.ts";
+import type { StableObjectId, StableRoutineId } from "../model/stable-identity.ts";
+import type { CallsiteEvidence, OperationEvidence } from "../snapshot/types.ts";
+
+export interface WitnessRequest {
+	rootId: StableRoutineId;
+	fact: CapabilityFact;
+	/**
+	 * Maximum witness paths to return.
+	 *  - `false` — suppress all witness reconstruction; returns
+	 *    `{ paths: [], truncated: false, incomplete: false }`. Caller
+	 *    knows it disabled witnesses; the outcome does NOT signal
+	 *    "no evidence" — it signals "evidence not collected".
+	 *  - `number` — clamped to `[0, HARD_PATH_CAP=256]`.
+	 *  - `"all"` — equivalent to `HARD_PATH_CAP`.
+	 */
+	limit: false | number | "all";
+	indexes: WitnessIndexes;
+	maxDepth?: number;
+	maxExpandedStates?: number;
+}
+
+export interface WitnessIndexes {
+	outgoingEdges: Map<StableRoutineId, readonly GraphEdge[]>;
+	directFactsByRoutine: Map<StableRoutineId, readonly CapabilityFact[]>;
+	callsiteById: Map<CallsiteId, CallsiteEvidence>;
+	operationById: Map<OperationId, OperationEvidence>;
+	routineDisplayById: Map<StableRoutineId, string>;
+	stableIdToDisplay: Map<string, string>;
+	eventDisplayById?: Map<string, string>;
+	coverageByRoutine?: Map<StableRoutineId, CoverageRecord>;
+}
+
+export interface WitnessOutcome {
+	paths: readonly WitnessPath[];
+	truncated: boolean;
+	incomplete: boolean;
+	diagnostics: readonly WitnessDiagnostic[];
+}
+
+export interface WitnessPath {
+	hops: readonly WitnessHop[];
+}
+
+export type WitnessDiagnostic =
+	| { kind: "path-limit-reached"; cap: number }
+	| { kind: "depth-exceeded"; maxDepth: number }
+	| { kind: "state-limit-exceeded"; maxExpandedStates: number }
+	| { kind: "first-hop-not-found"; callsiteId?: CallsiteId; via: CapabilityVia }
+	| { kind: "terminal-not-found" }
+	| { kind: "missing-callsite-evidence"; callsiteId: CallsiteId }
+	| { kind: "missing-operation-evidence"; operationId: OperationId }
+	| { kind: "missing-witness-anchor"; subject: StableRoutineId }
+	| { kind: "unresolved-dispatch"; callsiteId?: CallsiteId }
+	| { kind: "opaque-or-unresolved-boundary"; routineId?: StableRoutineId; target?: string };
+
+export type WitnessHop =
+	| {
+			kind: "call";
+			routineId: StableRoutineId;
+			routineDisplay: string;
+			calleeDisplay: string;
+			callsiteId: CallsiteId;
+			sourceFile?: string;
+			line?: number;
+			column?: number;
+	  }
+	| {
+			kind: "object-run";
+			routineId: StableRoutineId;
+			routineDisplay: string;
+			targetObjectId?: StableObjectId;
+			targetDisplay?: string;
+			resolved: boolean;
+			callsiteId?: CallsiteId;
+			sourceFile?: string;
+			line?: number;
+			column?: number;
+	  }
+	| {
+			kind: "event-dispatch";
+			routineId: StableRoutineId;
+			routineDisplay: string;
+			eventId: string;
+			eventDisplay: string;
+	  }
+	| {
+			kind: "implicit-trigger";
+			routineId: StableRoutineId;
+			routineDisplay: string;
+			triggerKind: string;
+			operationId?: OperationId;
+			sourceFile?: string;
+			line?: number;
+			column?: number;
+	  }
+	| {
+			kind: "dependency-export";
+			routineId: StableRoutineId;
+			routineDisplay: string;
+			targetAppGuid: string;
+			callsiteId: CallsiteId;
+			calleeDisplay?: string;
+			sourceFile?: string;
+			line?: number;
+			column?: number;
+	  }
+	| {
+			kind: "terminal";
+			evidenceKind: "operation" | "callsite" | "synthetic";
+			operationId?: OperationId;
+			callsiteId?: CallsiteId;
+			displayText: string;
+			sourceFile?: string;
+			line?: number;
+			column?: number;
+	  };
+
+const HARD_PATH_CAP = 256;
+
+function effectiveLimit(limit: WitnessRequest["limit"]): number {
+	if (limit === false) return 0;
+	if (limit === "all") return HARD_PATH_CAP;
+	return Math.max(0, Math.min(limit, HARD_PATH_CAP));
+}
+
+function buildDirectTerminal(
+	evidenceKind: "operation" | "callsite",
+	witnessId: OperationId | CallsiteId,
+	evidence:
+		| {
+				displayText?: string;
+				calleeDisplay?: string;
+				sourceFile?: string;
+				startLine?: number;
+				startColumn?: number;
+		  }
+		| undefined,
+): WitnessHop & { kind: "terminal" } {
+	const displayText =
+		evidenceKind === "operation"
+			? (evidence?.displayText ?? String(witnessId))
+			: (evidence?.calleeDisplay ?? String(witnessId));
+	return {
+		kind: "terminal",
+		evidenceKind,
+		operationId: evidenceKind === "operation" ? (witnessId as OperationId) : undefined,
+		callsiteId: evidenceKind === "callsite" ? (witnessId as CallsiteId) : undefined,
+		displayText,
+		sourceFile: evidence?.sourceFile,
+		line: evidence?.startLine,
+		column: evidence?.startColumn,
+	};
+}
+
+export function reconstructWitnessPaths(req: WitnessRequest): WitnessOutcome {
+	const cap = effectiveLimit(req.limit);
+	if (cap === 0) return { paths: [], truncated: false, incomplete: false, diagnostics: [] };
+
+	const diagnostics: WitnessDiagnostic[] = [];
+	const { fact, indexes } = req;
+
+	if (fact.provenance === "direct") {
+		// Case A: witnessOperationId present → terminal "operation" evidence.
+		if (fact.witnessOperationId !== undefined) {
+			const ev = indexes.operationById.get(fact.witnessOperationId);
+			const hop = buildDirectTerminal("operation", fact.witnessOperationId, ev);
+			if (ev === undefined) {
+				diagnostics.push({
+					kind: "missing-operation-evidence",
+					operationId: fact.witnessOperationId,
+				});
+			}
+			const path: WitnessPath = { hops: [hop] };
+			return { paths: [path], truncated: false, incomplete: ev === undefined, diagnostics };
+		}
+		// Case B: only witnessCallsiteId → terminal "callsite" evidence.
+		if (fact.witnessCallsiteId !== undefined) {
+			const ev = indexes.callsiteById.get(fact.witnessCallsiteId);
+			const hop = buildDirectTerminal("callsite", fact.witnessCallsiteId, ev);
+			if (ev === undefined) {
+				diagnostics.push({ kind: "missing-callsite-evidence", callsiteId: fact.witnessCallsiteId });
+			}
+			const path: WitnessPath = { hops: [hop] };
+			return { paths: [path], truncated: false, incomplete: ev === undefined, diagnostics };
+		}
+		// Direct with no witness anchor → synthetic.
+		diagnostics.push({ kind: "missing-witness-anchor", subject: fact.subject as StableRoutineId });
+		return {
+			paths: [
+				{
+					hops: [
+						{
+							kind: "terminal",
+							evidenceKind: "synthetic",
+							displayText: `${fact.op} ${fact.resourceKind}`,
+						},
+					],
+				},
+			],
+			truncated: false,
+			incomplete: true,
+			diagnostics,
+		};
+	}
+
+	// --- Case C: inherited fact ---
+	const maxDepth = req.maxDepth ?? 64;
+	const maxStates = req.maxExpandedStates ?? 25_000;
+	let stateCount = 0;
+	let truncated = false;
+	let incomplete = false;
+	let depthExceeded = false;
+
+	const paths: WitnessPath[] = [];
+
+	// First-hop constraint
+	if (fact.witnessCallsiteId === undefined) {
+		diagnostics.push({ kind: "first-hop-not-found", via: fact.via });
+		return { paths: [], truncated: false, incomplete: true, diagnostics };
+	}
+	const outFromRoot = indexes.outgoingEdges.get(req.rootId) ?? [];
+	const firstEdges = outFromRoot.filter(
+		(e) =>
+			"callsiteId" in e && (e as { callsiteId?: CallsiteId }).callsiteId === fact.witnessCallsiteId,
+	);
+	if (firstEdges.length === 0) {
+		diagnostics.push({
+			kind: "first-hop-not-found",
+			callsiteId: fact.witnessCallsiteId,
+			via: fact.via,
+		});
+		return { paths: [], truncated: false, incomplete: true, diagnostics };
+	}
+
+	type State = { routine: StableRoutineId; hops: WitnessHop[]; visited: Set<StableRoutineId> };
+	const queue: State[] = [];
+	for (const edge of firstEdges) {
+		const hop = edgeToHop(edge, indexes);
+		if (hop === undefined) continue;
+		const to = (edge as { to?: StableRoutineId }).to;
+		if (to === undefined) continue;
+		const visited = new Set<StableRoutineId>([req.rootId, to]);
+		queue.push({ routine: to, hops: [hop], visited });
+	}
+
+	queue.sort((a, b) => (a.routine < b.routine ? -1 : 1));
+
+	while (queue.length > 0 && paths.length < cap) {
+		const state = queue.shift();
+		if (state === undefined) break;
+		stateCount++;
+		if (stateCount > maxStates) {
+			diagnostics.push({ kind: "state-limit-exceeded", maxExpandedStates: maxStates });
+			incomplete = true;
+			break;
+		}
+		if (state.hops.length > maxDepth) {
+			depthExceeded = true;
+			continue;
+		}
+		// Terminal check
+		const directs = indexes.directFactsByRoutine.get(state.routine) ?? [];
+		const equivalent = directs.find((d) => factEquivalent(d, fact));
+		if (equivalent !== undefined) {
+			const terminalHop = terminalHopFromFact(equivalent, indexes);
+			paths.push({ hops: [...state.hops, terminalHop] });
+			continue;
+		}
+		// Opaque-or-unresolved-boundary detection at the current routine: no
+		// outgoing edges, no direct facts, and coverage marks it unknown. The
+		// path terminates here — the last hop (already in state.hops) is the
+		// boundary; no terminal hop is appended.
+		const routineOut = indexes.outgoingEdges.get(state.routine);
+		const routineCov = indexes.coverageByRoutine?.get(state.routine);
+		if (
+			(routineOut?.length ?? 0) === 0 &&
+			directs.length === 0 &&
+			routineCov?.directStatus === "unknown"
+		) {
+			diagnostics.push({ kind: "opaque-or-unresolved-boundary", routineId: state.routine });
+			// Emit the path up to (and including) the last hop already accumulated;
+			// no terminal is appended because we have no evidence at this boundary.
+			if (state.hops.length > 0) {
+				paths.push({ hops: [...state.hops] });
+			}
+			continue;
+		}
+		// Expand
+		const out = indexes.outgoingEdges.get(state.routine) ?? [];
+		const sorted = [...out].sort(edgeCompare);
+		for (const edge of sorted) {
+			const to = (edge as { to?: StableRoutineId }).to;
+			if (to === undefined) continue;
+			if (state.visited.has(to)) continue;
+			const hop = edgeToHop(edge, indexes);
+			if (hop === undefined) continue;
+			// Per-path visited (cloned per expansion). Allows the same routine to
+			// participate in different alternative paths; bounded by maxDepth=64 and
+			// maxStates=25_000.
+			const newVisited = new Set(state.visited);
+			newVisited.add(to);
+			queue.push({ routine: to, hops: [...state.hops, hop], visited: newVisited });
+		}
+	}
+
+	if (paths.length >= cap && queue.length > 0) {
+		truncated = true;
+		diagnostics.push({ kind: "path-limit-reached", cap });
+	}
+	if (depthExceeded) {
+		diagnostics.push({ kind: "depth-exceeded", maxDepth });
+		incomplete = true;
+	}
+	if (paths.length === 0 && !incomplete) {
+		diagnostics.push({ kind: "terminal-not-found" });
+		incomplete = true;
+	}
+
+	// Stability over perf: JSON.stringify gives byte-stable tiebreak across
+	// path enumeration order. Cost is O(cap^2 * serialize); pre-compute per
+	// path if cap grows beyond a few hundred.
+	paths.sort((a, b) => {
+		if (a.hops.length !== b.hops.length) return a.hops.length - b.hops.length;
+		return JSON.stringify(a.hops) < JSON.stringify(b.hops) ? -1 : 1;
+	});
+
+	return { paths, truncated, incomplete, diagnostics };
+}
+
+/**
+ * Best-effort equivalence check for "is this direct fact the terminal evidence
+ * for an inherited fact?". The deriver pipeline preserves (op, resourceKind,
+ * resourceId, resourceArgSource, extra) when propagating direct facts upward
+ * into inherited facts, so a matching direct fact at a BFS terminal should
+ * agree on these dimensions.
+ *
+ * The resourceId guard is asymmetric on purpose: if one side has a resourceId
+ * and the other doesn't, the comparison is skipped (treated as equivalent).
+ * This handles the case where the inherited fact carries a specialized
+ * resourceId (e.g., resolved from a literal SetRange argument) while the
+ * direct fact at the terminal stays generic (resourceId undefined for a
+ * dynamic dispatch site whose record-variable target couldn't be resolved).
+ *
+ * If this leniency produces false-positive terminal matches in practice,
+ * tighten to require bilateral agreement.
+ */
+function factEquivalent(a: CapabilityFact, b: CapabilityFact): boolean {
+	if (a.op !== b.op) return false;
+	if (a.resourceKind !== b.resourceKind) return false;
+	if (a.resourceId !== undefined && b.resourceId !== undefined) {
+		if (String(a.resourceId) !== String(b.resourceId)) return false;
+	}
+	if (a.resourceArgSource !== undefined && b.resourceArgSource !== undefined) {
+		if (JSON.stringify(a.resourceArgSource) !== JSON.stringify(b.resourceArgSource)) return false;
+	}
+	const extraA = a.extra as { kind?: string; objectType?: string } | undefined;
+	const extraB = b.extra as { kind?: string; objectType?: string } | undefined;
+	if (extraA?.kind === "dispatch" || extraB?.kind === "dispatch") {
+		if (extraA?.objectType !== extraB?.objectType) return false;
+	}
+	return true;
+}
+
+function terminalHopFromFact(fact: CapabilityFact, indexes: WitnessIndexes): WitnessHop {
+	if (fact.witnessOperationId !== undefined) {
+		const ev = indexes.operationById.get(fact.witnessOperationId);
+		return {
+			kind: "terminal",
+			evidenceKind: "operation",
+			operationId: fact.witnessOperationId,
+			displayText: ev?.displayText ?? String(fact.witnessOperationId),
+			sourceFile: ev?.sourceFile,
+			line: ev?.startLine,
+			column: ev?.startColumn,
+		};
+	}
+	if (fact.witnessCallsiteId !== undefined) {
+		const ev = indexes.callsiteById.get(fact.witnessCallsiteId);
+		return {
+			kind: "terminal",
+			evidenceKind: "callsite",
+			callsiteId: fact.witnessCallsiteId,
+			displayText: ev?.calleeDisplay ?? String(fact.witnessCallsiteId),
+			sourceFile: ev?.sourceFile,
+			line: ev?.startLine,
+			column: ev?.startColumn,
+		};
+	}
+	return {
+		kind: "terminal",
+		evidenceKind: "synthetic",
+		displayText: `${fact.op} ${fact.resourceKind}`,
+	};
+}
+
+function edgeToHop(edge: GraphEdge, indexes: WitnessIndexes): WitnessHop | undefined {
+	switch (edge.kind) {
+		case "direct-call": {
+			const to = edge.to as unknown as StableRoutineId;
+			const display = indexes.routineDisplayById.get(to) ?? String(to);
+			const cs = indexes.callsiteById.get(edge.callsiteId);
+			return {
+				kind: "call",
+				routineId: to,
+				routineDisplay: display,
+				calleeDisplay: cs?.calleeDisplay ?? "",
+				callsiteId: edge.callsiteId,
+				sourceFile: cs?.sourceFile,
+				line: cs?.startLine,
+				column: cs?.startColumn,
+			};
+		}
+		case "object-run-resolved": {
+			const to = edge.to as unknown as StableRoutineId;
+			const display = indexes.routineDisplayById.get(to) ?? String(to);
+			const cs = indexes.callsiteById.get(edge.callsiteId);
+			const targetObject = String(edge.targetObject) as StableObjectId;
+			return {
+				kind: "object-run",
+				routineId: to,
+				routineDisplay: display,
+				targetObjectId: targetObject,
+				targetDisplay: indexes.stableIdToDisplay.get(String(edge.targetObject)),
+				resolved: true,
+				callsiteId: edge.callsiteId,
+				sourceFile: cs?.sourceFile,
+				line: cs?.startLine,
+				column: cs?.startColumn,
+			};
+		}
+		case "object-run-unresolved":
+			// No `to` on unresolved dispatch — BFS cannot walk through.
+			// Boundary detection emits an `unresolved-dispatch` diagnostic (see BFS expand loop).
+			return undefined;
+		case "event-dispatch": {
+			const to = edge.to as unknown as StableRoutineId;
+			const display = indexes.routineDisplayById.get(to) ?? String(to);
+			const eid = String(edge.eventId);
+			return {
+				kind: "event-dispatch",
+				routineId: to,
+				routineDisplay: display,
+				eventId: eid,
+				eventDisplay: indexes.eventDisplayById?.get(eid) ?? eid,
+			};
+		}
+		case "implicit-trigger": {
+			const to = edge.to as unknown as StableRoutineId;
+			const display = indexes.routineDisplayById.get(to) ?? String(to);
+			return {
+				kind: "implicit-trigger",
+				routineId: to,
+				routineDisplay: display,
+				triggerKind: edge.triggerKind,
+				operationId: edge.operationId,
+			};
+		}
+		case "dependency-export": {
+			const to = edge.to as unknown as StableRoutineId;
+			const display = indexes.routineDisplayById.get(to) ?? String(to);
+			const cs = indexes.callsiteById.get(edge.callsiteId);
+			return {
+				kind: "dependency-export",
+				routineId: to,
+				routineDisplay: display,
+				targetAppGuid: edge.targetAppGuid,
+				callsiteId: edge.callsiteId,
+				calleeDisplay: cs?.calleeDisplay,
+				sourceFile: cs?.sourceFile,
+				line: cs?.startLine,
+				column: cs?.startColumn,
+			};
+		}
+		default:
+			return undefined;
+	}
+}
+
+function edgeCompare(a: GraphEdge, b: GraphEdge): number {
+	if (a.kind !== b.kind) return a.kind < b.kind ? -1 : 1;
+	const csOf = (e: GraphEdge) => String((e as { callsiteId?: unknown }).callsiteId ?? "");
+	const csA = csOf(a);
+	const csB = csOf(b);
+	if (csA !== csB) return csA < csB ? -1 : 1;
+	const toOf = (e: GraphEdge) => String((e as { to?: unknown }).to ?? "");
+	const toA = toOf(a);
+	const toB = toOf(b);
+	return toA < toB ? -1 : 1;
+}