al-sem 0.0.1

package/src/deps/dependency-artifact.ts

@@ -0,0 +1,144 @@
+import type { ObjectDecl, Routine, Table } from "../model/entities.ts";
+import type { Diagnostic } from "../model/finding.ts";
+import type { EventSymbol } from "../model/graph.ts";
+import type { SemanticIndex } from "../model/model.ts";
+import type { ManifestDependency } from "../symbols/app-manifest.ts";
+
+/** Bump alongside `depCache` in cache-versions.ts when this shape changes. */
+export const DEPENDENCY_ARTIFACT_SCHEMA_VERSION = 1;
+
+/** A discovered dependency .app on disk — NOT a SourceUnit. Produced by dependency-package-discovery. */
+export interface DependencyPackageRef {
+	appPath: string;
+	appGuid: string;
+	publisher: string;
+	name: string;
+	version: string;
+	/** Raw-byte sha256 of the .app file — provenance only. */
+	packageHash: string;
+	/** Declared dependencies from NavxManifest.xml — drives DAG topo-sort + version resolution. */
+	manifestDependencies: ManifestDependency[];
+	/** ResourceExposurePolicy.IncludeSourceInSymbolFile. */
+	includesSource: boolean;
+}
+
+/** One direct dependency, identity + the artifact key it resolved to. Sorted by identity in keys. */
+export interface DirectDependencyRef {
+	appGuid: string;
+	publisher: string;
+	name: string;
+	version: string;
+	artifactKey: string;
+}
+
+export interface DependencyArtifactVersions {
+	analyzer: string;
+	grammar: string;
+	symbolReader: string;
+	summarySchema: string;
+	depCache: string;
+	resourcePolicy: string;
+	devFingerprint: string;
+}
+
+export interface DependencyArtifactHeader {
+	schemaVersion: number;
+	versions: DependencyArtifactVersions;
+	/** Semantic input key — also the cache filename stem. */
+	artifactKey: string;
+	/** sha256 of the canonical artifact JSON minus this field — the real content address. */
+	artifactContentHash: string;
+	appIdentity: { appGuid: string; publisher: string; name: string; version: string };
+	/** Raw-byte sha256 of the .app — provenance only, NOT part of the key. */
+	packageHash: string;
+	/** sha256 of manifest identity+deps + SymbolReference.json hash + sorted embedded-.al hashes. */
+	packageSemanticHash: string;
+	directDependencies: DirectDependencyRef[];
+	summaryMode:
+		| "full"
+		| "structural-only-resource-guard"
+		| "structural-only-parser-unavailable"
+		| "structural-only-no-dep-summaries";
+}
+
+/**
+ * The structural + behavioral payload. `routines` are full model entities with **empty
+ * `features`**, `analysisRole: "dependency"`, and `summary` populated — the open-world
+ * residuals (`uncertainties`, `capabilityFactsDirect`, `capabilityFactsInherited`,
+ * `coverage`) live inside each `summary`. All ids use the artifact's fixed
+ * `dep:<artifactKey>` modelInstanceId, so the merge is verbatim.
+ */
+export interface DependencyArtifactAbi {
+	objects: ObjectDecl[];
+	tables: Table[];
+	routines: Routine[];
+	/** Exported event-publisher symbols — empty `features` on dep routines cannot feed buildEventGraph. */
+	eventPublishers: EventSymbol[];
+}
+
+/** A cached, compact semantic artifact for one dependency .app. */
+export interface DependencyArtifact {
+	header: DependencyArtifactHeader;
+	abi: DependencyArtifactAbi;
+	/** Analyzer-authored, stable, replayable degradation diagnostics. */
+	diagnostics: Diagnostic[];
+}
+
+/** Structural guard used by validate-on-read. Checks shape, not semantic validity. */
+export function isDependencyArtifact(x: unknown): x is DependencyArtifact {
+	if (x === null || typeof x !== "object") return false;
+	const a = x as Record<string, unknown>;
+	const h = a.header as Record<string, unknown> | undefined;
+	if (h === null || h === undefined || typeof h !== "object") return false;
+	if (h.schemaVersion !== DEPENDENCY_ARTIFACT_SCHEMA_VERSION) return false;
+	if (typeof h.artifactKey !== "string" || typeof h.artifactContentHash !== "string") return false;
+	if (typeof h.versions !== "object" || h.versions === null) return false;
+	if (!Array.isArray(h.directDependencies)) return false;
+	if (
+		h.summaryMode !== "full" &&
+		h.summaryMode !== "structural-only-resource-guard" &&
+		h.summaryMode !== "structural-only-parser-unavailable" &&
+		h.summaryMode !== "structural-only-no-dep-summaries"
+	)
+		return false;
+	const abi = a.abi as Record<string, unknown> | undefined;
+	if (
+		abi === null ||
+		abi === undefined ||
+		!Array.isArray(abi.objects) ||
+		!Array.isArray(abi.tables)
+	)
+		return false;
+	if (!Array.isArray(abi.routines) || !Array.isArray(abi.eventPublishers)) return false;
+	if (!Array.isArray(a.diagnostics)) return false;
+	return true;
+}
+
+/**
+ * Pure merge: fold dependency artifacts into a workspace SemanticIndex, returning a NEW
+ * index (the input is never mutated). Artifacts arrive in dependency topo order; entities
+ * within each artifact are already sorted, so the merged collections are deterministic.
+ * Dependency apps are appended with `analysisRole: "dependency"`.
+ */
+export function withDependencyArtifacts(
+	index: SemanticIndex,
+	artifacts: DependencyArtifact[],
+): SemanticIndex {
+	const apps = [...index.apps];
+	const objects = [...index.objects];
+	const tables = [...index.tables];
+	const routines = [...index.routines];
+	for (const artifact of artifacts) {
+		apps.push({
+			appGuid: artifact.header.appIdentity.appGuid,
+			publisher: artifact.header.appIdentity.publisher,
+			name: artifact.header.appIdentity.name,
+			version: artifact.header.appIdentity.version,
+			analysisRole: "dependency",
+		});
+		objects.push(...artifact.abi.objects);
+		tables.push(...artifact.abi.tables);
+		routines.push(...artifact.abi.routines);
+	}
+	return { ...index, apps, objects, tables, routines };
+}

package/src/deps/dependency-cache.ts

@@ -0,0 +1,262 @@
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CACHE_VERSIONS, devFingerprint } from "./cache-versions.ts";
+import { canonicalStringify } from "./canonical-json.ts";
+import type { DependencyArtifact, DirectDependencyRef } from "./dependency-artifact.ts";
+import { isDependencyArtifact } from "./dependency-artifact.ts";
+
+const sha256 = (s: string): string => createHash("sha256").update(s, "utf8").digest("hex");
+
+/** Artifact variants the cache keeps namespaced. `full` carries behavioral summaries derived
+ * from embedded-source parsing; `structural-only` is the `--no-dep-summaries` mode (ABI only,
+ * no summaries on routines). The two artifacts for the same package live as separate cache
+ * entries so a flag-flipped run never reads the wrong shape. */
+export type ArtifactMode = "full" | "structural-only";
+
+/**
+ * The semantic input key for a dependency artifact — also the cache filename stem. Hashes
+ * domain-separated canonical key material: packageSemanticHash + sorted direct-dependency
+ * identity+key pairs + all cache-affecting version stamps + devFingerprint + artifact mode.
+ */
+export function computeArtifactKey(
+	packageSemanticHash: string,
+	directDependencies: DirectDependencyRef[],
+	mode: ArtifactMode = "full",
+): string {
+	const keyMaterial = {
+		kind: "al-sem.depArtifactKey",
+		v: 2,
+		packageSemanticHash,
+		directDependencies: [...directDependencies].sort((a, b) =>
+			`${a.publisher}|${a.name}|${a.appGuid}` < `${b.publisher}|${b.name}|${b.appGuid}` ? -1 : 1,
+		),
+		versions: { ...CACHE_VERSIONS, devFingerprint: devFingerprint() },
+		mode,
+	};
+	return sha256(canonicalStringify(keyMaterial));
+}
+
+/** Resolve the cache directory: an explicit override, else `~/.al-sem/cache/`. */
+export function resolveCacheDir(override?: string): string {
+	return override ?? join(homedir(), ".al-sem", "cache");
+}
+
+/** Canonical artifact JSON with `artifactContentHash` cleared — the input to the content hash. */
+function canonicalWithoutContentHash(artifact: DependencyArtifact): string {
+	return canonicalStringify({
+		...artifact,
+		header: { ...artifact.header, artifactContentHash: "" },
+	});
+}
+
+/**
+ * Recompute the content hash from the on-disk text WITHOUT re-serializing the parsed artifact.
+ * `writeCachedArtifact` emits canonical bytes with the hash injected by string substitution, so
+ * the file is byte-identical to `canonicalStringify(finalArtifact)`; substituting the stored hash
+ * back to "" reproduces exactly `canonicalWithoutContentHash`. This avoids a full
+ * `canonicalStringify` walk of a multi-hundred-MB object tree on every cache hit. A file written
+ * by anything other than `writeCachedArtifact` (non-canonical, or tampered) yields a mismatch and
+ * is treated as a miss — strictly safe.
+ */
+function contentHashFromRawText(rawText: string, storedHash: string): string {
+	const emptyHashText = rawText.replace(
+		`"artifactContentHash":"${storedHash}"`,
+		'"artifactContentHash":""',
+	);
+	return sha256(emptyHashText);
+}
+
+/**
+ * Write an artifact to the cache atomically (temp file + rename). Computes artifactContentHash
+ * and returns the canonical in-memory form — `JSON.parse` of the exact bytes a future cache hit
+ * reads — so the cold-write path produces byte-identical downstream output to a warm cache hit
+ * WITHOUT a disk round-trip (the caller does not re-read + re-validate what it just wrote).
+ *
+ * Serializes the artifact ONCE (with an empty content hash) and injects the computed hash by
+ * string substitution. `canonicalStringify` is compact + recursively key-sorted, so the
+ * with-hash and without-hash serializations are identical except for the hash value; injecting
+ * avoids a second full serialization of a multi-hundred-MB artifact. The token
+ * `"artifactContentHash":""` is unique to the header (no data field carries that key, and `abi`
+ * sorts before `header`), so the first/only occurrence is the header field.
+ */
+export function writeCachedArtifact(
+	artifact: DependencyArtifact,
+	cacheDir: string,
+): DependencyArtifact {
+	const jsonEmptyHash = canonicalWithoutContentHash(artifact);
+	const contentHash = sha256(jsonEmptyHash);
+	const json = jsonEmptyHash.replace(
+		'"artifactContentHash":""',
+		`"artifactContentHash":"${contentHash}"`,
+	);
+	if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+	const finalPath = join(cacheDir, `${artifact.header.artifactKey}.json`);
+	const tmpPath = `${finalPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+	writeFileSync(tmpPath, json, "utf8");
+	try {
+		renameSync(tmpPath, finalPath);
+	} catch {
+		// rename-over-existing can fail on Windows/network FS; if a valid final exists, accept it.
+		if (!existsSync(finalPath)) throw new Error(`could not place cache file ${finalPath}`);
+		try {
+			unlinkSync(tmpPath);
+		} catch {
+			/* best-effort temp cleanup */
+		}
+	}
+	return JSON.parse(json) as DependencyArtifact;
+}
+
+/**
+ * Read and validate a cached artifact. Returns null on any miss/failure (caller treats it as
+ * a cache miss). Validation: filename pattern, JSON parse, structural shape, key match,
+ * version-stamp match, and content-hash recompute.
+ */
+export function readCachedArtifact(
+	artifactKey: string,
+	cacheDir: string,
+): DependencyArtifact | null {
+	if (!/^[a-f0-9]{64}$/.test(artifactKey)) return null;
+	const path = join(cacheDir, `${artifactKey}.json`);
+	if (!existsSync(path)) return null;
+	let rawText: string;
+	try {
+		rawText = readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawText);
+	} catch {
+		return null;
+	}
+	if (!isDependencyArtifact(parsed)) return null;
+	const artifact = parsed;
+	if (artifact.header.artifactKey !== artifactKey) return null;
+	const v = artifact.header.versions;
+	const expected = { ...CACHE_VERSIONS, devFingerprint: devFingerprint() };
+	for (const [k, val] of Object.entries(expected)) {
+		if ((v as unknown as Record<string, string>)[k] !== val) return null;
+	}
+	const recomputed = contentHashFromRawText(rawText, artifact.header.artifactContentHash);
+	if (recomputed !== artifact.header.artifactContentHash) return null;
+	return artifact;
+}
+
+/** One entry classified by `pruneCache` — the file, its size, and why it was kept or dropped. */
+export interface PruneCacheEntry {
+	file: string;
+	bytes: number;
+	status:
+		| "kept"
+		| "removed-bad-name"
+		| "removed-unreadable"
+		| "removed-version-mismatch"
+		| "removed-content-hash-mismatch";
+}
+
+export interface PruneCacheResult {
+	cacheDir: string;
+	entries: PruneCacheEntry[];
+	bytesFreed: number;
+	filesRemoved: number;
+}
+
+/** Reasons recognised by `pruneCache` as evidence the cached artifact is no longer usable
+ * by this build of al-sem. Read-but-validates-fine artifacts are kept. */
+function classifyArtifactForPrune(path: string): PruneCacheEntry["status"] {
+	const fileName = path.split(/[\\/]/).pop() ?? path;
+	const match = fileName.match(/^([a-f0-9]{64})\.json$/);
+	if (match === null) return "removed-bad-name";
+	const key = match[1] as string;
+	let rawText: string;
+	try {
+		rawText = readFileSync(path, "utf8");
+	} catch {
+		return "removed-unreadable";
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawText);
+	} catch {
+		return "removed-unreadable";
+	}
+	if (!isDependencyArtifact(parsed)) return "removed-unreadable";
+	const artifact = parsed;
+	if (artifact.header.artifactKey !== key) return "removed-unreadable";
+	const v = artifact.header.versions;
+	const expected = { ...CACHE_VERSIONS, devFingerprint: devFingerprint() };
+	for (const [k, val] of Object.entries(expected)) {
+		if ((v as unknown as Record<string, string>)[k] !== val) return "removed-version-mismatch";
+	}
+	const recomputed = contentHashFromRawText(rawText, artifact.header.artifactContentHash);
+	if (recomputed !== artifact.header.artifactContentHash) return "removed-content-hash-mismatch";
+	return "kept";
+}
+
+/**
+ * Remove cached artifacts that this build of al-sem can no longer use — version-stamp
+ * mismatch (new analyzer / grammar / symbolReader / depCache / resourcePolicy /
+ * summarySchema / devFingerprint), corrupt files, mis-named files, or content-hash
+ * tampering. Artifacts that match the current versions stay; pruning is a no-op for them.
+ *
+ * Use `dryRun: true` to classify without deleting anything — the result still lists the
+ * entries that WOULD be removed, with `bytesFreed` totaling them.
+ */
+export function pruneCache(
+	cacheDirOverride: string | undefined,
+	options: { dryRun?: boolean } = {},
+): PruneCacheResult {
+	const cacheDir = resolveCacheDir(cacheDirOverride);
+	const entries: PruneCacheEntry[] = [];
+	let bytesFreed = 0;
+	let filesRemoved = 0;
+	if (!existsSync(cacheDir)) {
+		return { cacheDir, entries, bytesFreed, filesRemoved };
+	}
+	let files: string[];
+	try {
+		files = readdirSync(cacheDir);
+	} catch {
+		return { cacheDir, entries, bytesFreed, filesRemoved };
+	}
+	for (const file of files.sort()) {
+		// Skip temp files left behind by interrupted writes — readCachedArtifact also ignores
+		// these. They are reaped by the next successful rename of the same target.
+		if (file.includes(".tmp.")) continue;
+		const path = join(cacheDir, file);
+		let bytes = 0;
+		try {
+			const st = statSync(path);
+			if (!st.isFile()) continue;
+			bytes = st.size;
+		} catch {
+			continue;
+		}
+		const status = classifyArtifactForPrune(path);
+		entries.push({ file, bytes, status });
+		if (status === "kept") continue;
+		if (options.dryRun !== true) {
+			try {
+				unlinkSync(path);
+			} catch {
+				continue; // leave it — better than half-deleting
+			}
+		}
+		bytesFreed += bytes;
+		filesRemoved++;
+	}
+	return { cacheDir, entries, bytesFreed, filesRemoved };
+}

package/src/deps/dependency-dag.ts

@@ -0,0 +1,128 @@
+import { basename } from "node:path";
+import type { Diagnostic } from "../model/finding.ts";
+import type { ManifestDependency } from "../symbols/app-manifest.ts";
+import type { DependencyPackageRef } from "./dependency-artifact.ts";
+
+/** Compare two BC `x.y.z.w` version strings numerically. Missing components count as 0. */
+export function compareVersions(a: string, b: string): number {
+	const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+	const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+	for (let i = 0; i < 4; i++) {
+		const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (d !== 0) return d < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
+export interface ResolveDependencyDagResult {
+	/** Selected packages in dependency order (a dependency precedes its dependents). */
+	ordered: DependencyPackageRef[];
+	diagnostics: Diagnostic[];
+}
+
+/**
+ * Validate the dependency DAG, resolve one package per appGuid against accumulated
+ * minVersion constraints, and topo-sort the reachable set. Never throws; failure modes
+ * surface as DEP0xx diagnostics. Deterministic: package grouping, constraint accumulation,
+ * version selection, and topo order are all sorted.
+ */
+export function resolveDependencyDag(
+	packages: DependencyPackageRef[],
+	workspaceDependencies: ManifestDependency[],
+): ResolveDependencyDagResult {
+	const diagnostics: Diagnostic[] = [];
+
+	// --- group by appGuid; flag exact-identity duplicates (DEP010) ---
+	const byGuid = new Map<string, DependencyPackageRef[]>();
+	for (const p of [...packages].sort((a, b) => (a.appPath < b.appPath ? -1 : 1))) {
+		const list = byGuid.get(p.appGuid) ?? [];
+		const dup = list.find((q) => q.version === p.version);
+		if (dup !== undefined) {
+			diagnostics.push({
+				severity: "warning",
+				stage: "discover",
+				message: `[DEP010] duplicate package identity ${p.name} ${p.version} (kept ${basename(dup.appPath)}, ignored ${basename(p.appPath)})`,
+				sourceRef: p.appPath,
+			});
+			continue;
+		}
+		list.push(p);
+		byGuid.set(p.appGuid, list);
+	}
+
+	// --- BFS the transitive closure, accumulating minVersion constraints per appGuid ---
+	const constraints = new Map<string, string>(); // appGuid -> highest required minVersion
+	const queue: ManifestDependency[] = [...workspaceDependencies];
+	const seenConstraintFrom = new Set<string>(); // appGuids whose own deps were already queued
+	const requireConstraint = (d: ManifestDependency): void => {
+		const prev = constraints.get(d.appGuid);
+		if (prev === undefined || compareVersions(d.minVersion, prev) > 0) {
+			constraints.set(d.appGuid, d.minVersion);
+		}
+	};
+	const selected = new Map<string, DependencyPackageRef>();
+	while (queue.length > 0) {
+		const d = queue.shift();
+		if (d === undefined) continue;
+		requireConstraint(d);
+		if (seenConstraintFrom.has(d.appGuid)) continue;
+		seenConstraintFrom.add(d.appGuid);
+
+		const available = byGuid.get(d.appGuid);
+		if (available === undefined || available.length === 0) {
+			diagnostics.push({
+				severity: "warning",
+				stage: "discover",
+				message: `[DEP012] declared dependency ${d.name} (${d.appGuid}) has no matching package in .alpackages`,
+			});
+			continue;
+		}
+		// select highest version satisfying the (current) accumulated constraint
+		const min = constraints.get(d.appGuid) ?? "0.0.0.0";
+		const satisfying = available
+			.filter((p) => compareVersions(p.version, min) >= 0)
+			.sort((a, b) => compareVersions(a.version, b.version));
+		const chosen = satisfying[satisfying.length - 1];
+		if (chosen === undefined) {
+			const highest = [...available].sort((a, b) => compareVersions(a.version, b.version)).pop();
+			diagnostics.push({
+				severity: "warning",
+				stage: "discover",
+				message: `[DEP011] no version of ${d.name} satisfies minVersion ${min} (highest available ${highest?.version ?? "?"}) — dependency left opaque`,
+			});
+			continue;
+		}
+		selected.set(d.appGuid, chosen);
+		for (const td of chosen.manifestDependencies) queue.push(td);
+	}
+
+	// --- topo-sort the selected set; break cycles deterministically (DEP013) ---
+	const nodes = [...selected.values()].sort((a, b) =>
+		`${a.publisher}|${a.name}|${a.appGuid}` < `${b.publisher}|${b.name}|${b.appGuid}` ? -1 : 1,
+	);
+	const ordered: DependencyPackageRef[] = [];
+	const state = new Map<string, "visiting" | "done">();
+	const visit = (p: DependencyPackageRef): void => {
+		const s = state.get(p.appGuid);
+		if (s === "done") return;
+		if (s === "visiting") {
+			diagnostics.push({
+				severity: "error",
+				stage: "discover",
+				message: `[DEP013] dependency cycle involving ${p.name} — back-edge dropped`,
+			});
+			return;
+		}
+		state.set(p.appGuid, "visiting");
+		const deps = [...p.manifestDependencies].sort((a, b) => (a.appGuid < b.appGuid ? -1 : 1));
+		for (const d of deps) {
+			const child = selected.get(d.appGuid);
+			if (child !== undefined) visit(child);
+		}
+		state.set(p.appGuid, "done");
+		ordered.push(p);
+	};
+	for (const p of nodes) visit(p);
+
+	return { ordered, diagnostics };
+}

package/src/deps/dependency-package-discovery.ts

@@ -0,0 +1,85 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Diagnostic } from "../model/finding.ts";
+import { readAppManifest } from "../symbols/app-manifest.ts";
+import { packageHash } from "../symbols/package-hash.ts";
+import type { DependencyPackageRef } from "./dependency-artifact.ts";
+
+export interface DiscoverDependencyPackagesResult {
+	packages: DependencyPackageRef[];
+	diagnostics: Diagnostic[];
+}
+
+/**
+ * Enumerate the .app packages in an .alpackages directory into DependencyPackageRefs. Reads
+ * only each package's NavxManifest.xml and raw bytes — never SymbolReference.json or source.
+ * Never throws: an unreadable directory or a corrupt .app becomes a `discover` diagnostic.
+ * Packages are returned sorted by file path for determinism.
+ */
+export function discoverDependencyPackages(
+	alpackagesDir: string,
+): DiscoverDependencyPackagesResult {
+	const diagnostics: Diagnostic[] = [];
+	if (!existsSync(alpackagesDir)) {
+		diagnostics.push({
+			severity: "warning",
+			stage: "discover",
+			message: "[DEP001] .alpackages directory not found",
+			sourceRef: alpackagesDir,
+		});
+		return { packages: [], diagnostics };
+	}
+
+	let entries: string[];
+	try {
+		entries = readdirSync(alpackagesDir);
+	} catch (err) {
+		diagnostics.push({
+			severity: "warning",
+			stage: "discover",
+			message: `[DEP001] could not read .alpackages directory: ${(err as Error).message}`,
+			sourceRef: alpackagesDir,
+		});
+		return { packages: [], diagnostics };
+	}
+
+	const appFiles = entries.filter((e) => e.toLowerCase().endsWith(".app")).sort();
+	const packages: DependencyPackageRef[] = [];
+	for (const fileName of appFiles) {
+		const appPath = join(alpackagesDir, fileName);
+		const manifest = readAppManifest(appPath);
+		if (manifest.error !== undefined || manifest.identity.appGuid === "") {
+			diagnostics.push({
+				severity: "warning",
+				stage: "discover",
+				message: `[DEP002] skipped unreadable or corrupt package ${fileName}: ${manifest.error ?? "no app identity"}`,
+				sourceRef: appPath,
+			});
+			continue;
+		}
+		let hash: string;
+		try {
+			hash = packageHash(appPath);
+		} catch (err) {
+			diagnostics.push({
+				severity: "warning",
+				stage: "discover",
+				message: `[DEP002] could not hash package ${fileName}: ${(err as Error).message}`,
+				sourceRef: appPath,
+			});
+			continue;
+		}
+		packages.push({
+			appPath,
+			appGuid: manifest.identity.appGuid,
+			publisher: manifest.identity.publisher,
+			name: manifest.identity.name,
+			version: manifest.identity.version,
+			packageHash: hash,
+			manifestDependencies: manifest.dependencies,
+			includesSource: manifest.includesSource,
+		});
+	}
+
+	return { packages, diagnostics };
+}