al-sem 0.0.1

package/src/snapshot/serialize-json.ts

@@ -0,0 +1,22 @@
+import type { CapabilitySnapshot } from "./types.ts";
+
+/**
+ * Pretty JSON serializer with recursively sorted object keys, 2-space indent,
+ * newline-terminated. Byte-stable for a given input.
+ *
+ * Arrays passed through as-is — derivers sort their own outputs per the
+ * canonical-sort contract. Sorting twice would mask deriver bugs.
+ */
+export function serializeJson(snapshot: CapabilitySnapshot): string {
+	return `${JSON.stringify(snapshot, sortedReplacer(), 2)}\n`;
+}
+
+function sortedReplacer(): (key: string, value: unknown) => unknown {
+	return (_key, value) => {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+		const obj = value as Record<string, unknown>;
+		const sorted: Record<string, unknown> = {};
+		for (const k of Object.keys(obj).sort()) sorted[k] = obj[k];
+		return sorted;
+	};
+}

package/src/snapshot/shard.ts

@@ -0,0 +1,134 @@
+import { serializeCborGz } from "./serialize-cbor-gz.ts";
+import { serializeCbor } from "./serialize-cbor.ts";
+import { serializeJson } from "./serialize-json.ts";
+import type {
+	AppIdentity,
+	CapabilitySnapshot,
+	ShardManifest,
+	SnapshotFormat,
+	SnapshotIdentityTable,
+} from "./types.ts";
+import { SNAPSHOT_SCHEMA_VERSION } from "./types.ts";
+
+export interface ShardingOptions {
+	format: SnapshotFormat;
+	/** Drop dependency shards; keep only the primary app. Default false. */
+	primaryOnly?: boolean;
+}
+
+/**
+ * Split a monolithic snapshot into per-app shards + a manifest.
+ *
+ * Returns a Map<filename, bytes>. Caller writes each entry to disk under
+ * the user's --out directory.
+ *
+ * Slicing rule: a fact belongs to the shard whose appGuid is the prefix of
+ * its stableId (Stable*Ids start with `${appGuid}:`). The primary shard is
+ * the FIRST app in snapshot.apps (apps array is sorted; the primary is
+ * established by analyzeWorkspace and stable across runs).
+ *
+ * Each shard is a fully valid CapabilitySnapshot — schemaVersion,
+ * alsemVersion, workspaceFingerprint, generatedAt are copied; apps,
+ * identities, inputs are narrowed to the shard's app. typedEdges that cross
+ * apps are duplicated into BOTH shards.
+ */
+export function serializeSharded(
+	snapshot: CapabilitySnapshot,
+	opts: ShardingOptions,
+): Map<string, Uint8Array> {
+	const apps = snapshot.apps;
+	const out = new Map<string, Uint8Array>();
+	if (apps.length === 0) {
+		out.set("manifest.json", encodeManifest(snapshot, []));
+		return out;
+	}
+
+	const primaryGuid = apps[0]?.appGuid;
+	if (primaryGuid === undefined) {
+		out.set("manifest.json", encodeManifest(snapshot, []));
+		return out;
+	}
+
+	const shardEntries: ShardManifest["shards"] = [];
+
+	for (const app of apps) {
+		const role = app.appGuid === primaryGuid ? "primary" : "dependency";
+		if (opts.primaryOnly && role !== "primary") continue;
+
+		const shard = sliceForApp(snapshot, app);
+		const fileBase = role === "primary" ? "primary" : `dep-${app.appGuid}`;
+		const ext = opts.format === "json" ? "json" : opts.format === "cbor" ? "cbor" : "cbor.gz";
+		const fileName = `${fileBase}.${ext}`;
+		out.set(fileName, serializeOne(shard, opts.format));
+		shardEntries.push({ appGuid: app.appGuid, role, file: fileName });
+	}
+
+	out.set("manifest.json", encodeManifest(snapshot, shardEntries));
+	return out;
+}
+
+function sliceForApp(s: CapabilitySnapshot, app: AppIdentity): CapabilitySnapshot {
+	const inApp = (stableId: string): boolean => stableId.startsWith(`${app.appGuid}:`);
+	const shard: CapabilitySnapshot = {
+		schemaVersion: s.schemaVersion,
+		alsemVersion: s.alsemVersion,
+		workspaceFingerprint: s.workspaceFingerprint,
+		generatedAt: s.generatedAt,
+		apps: [app],
+		identities: sliceIdentities(s.identities, app.appGuid),
+		contractFacts: s.contractFacts.filter((c) => inApp(c.stableId)),
+		schemaFacts: s.schemaFacts.filter((c) => inApp(c.stableId)),
+		permissionFacts: s.permissionFacts.filter((p) =>
+			inApp(p.kind === "declared" ? String(p.permissionSet) : String(p.subject)),
+		),
+		rootClassifications: s.rootClassifications.filter((r) => inApp(String(r.routineId))),
+		capabilityFacts: s.capabilityFacts.filter((f) => inApp(String(f.subject))),
+		typedEdges: s.typedEdges.filter(
+			(e) =>
+				("from" in e && inApp(String(e.from))) ||
+				("to" in e && inApp(String((e as { to?: unknown }).to ?? ""))),
+		),
+		operationIndex: s.operationIndex.filter((o) => inApp(String(o.routine))),
+		callsiteIndex: s.callsiteIndex.filter((c) => inApp(String(c.routine))),
+		coverage: s.coverage.filter((c) => inApp(String(c.subject))),
+		inputs: s.inputs,
+		eventDeclarations: s.eventDeclarations.filter(
+			(d) => inApp(String(d.routine)) || (d.binding ? inApp(d.binding.publisherObject) : false),
+		),
+	};
+	// Side-band metadata is workspace-scoped, not app-scoped — mirror onto
+	// every shard so each is a self-contained snapshot.
+	if (s.inputsMetadata !== undefined) {
+		shard.inputsMetadata = s.inputsMetadata;
+	}
+	return shard;
+}
+
+function sliceIdentities(table: SnapshotIdentityTable, appGuid: string): SnapshotIdentityTable {
+	const stableIds: string[] = [];
+	const displayNames: string[] = [];
+	for (let i = 0; i < table.stableIds.length; i++) {
+		const id = table.stableIds[i];
+		if (id?.startsWith(`${appGuid}:`)) {
+			stableIds.push(id);
+			displayNames.push(table.displayNames[i] ?? "");
+		}
+	}
+	return { stableIds, displayNames };
+}
+
+function serializeOne(s: CapabilitySnapshot, fmt: SnapshotFormat): Uint8Array {
+	if (fmt === "json") return new TextEncoder().encode(serializeJson(s));
+	if (fmt === "cbor") return serializeCbor(s);
+	return serializeCborGz(s);
+}
+
+function encodeManifest(s: CapabilitySnapshot, shards: ShardManifest["shards"]): Uint8Array {
+	const m: ShardManifest = {
+		schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+		alsemVersion: s.alsemVersion,
+		workspaceFingerprint: s.workspaceFingerprint,
+		shards: [...shards].sort((a, b) => a.appGuid.localeCompare(b.appGuid)),
+	};
+	return new TextEncoder().encode(`${JSON.stringify(m, null, 2)}\n`);
+}

package/src/snapshot/types.ts

@@ -0,0 +1,181 @@
+import type { CapabilityFact } from "../model/capability.ts";
+import type { CoverageRecord } from "../model/coverage.ts";
+import type { GraphEdge } from "../model/graph-edge.ts";
+import type { SourceAnchor } from "../model/identity.ts";
+import type { CallsiteId, OperationId } from "../model/ids.ts";
+import type { PermissionFact } from "../model/permission.ts";
+import type {
+	StableAppId,
+	StableEventId,
+	StableObjectId,
+	StableRoutineId,
+} from "../model/stable-identity.ts";
+
+/** Snapshot schema version. Bump per CLAUDE.md "schema bumps are cheap"
+ *  recipe; deserializer asserts and may run a migration shim. */
+export const SNAPSHOT_SCHEMA_VERSION = 1 as const;
+export type SnapshotSchemaVersion = typeof SNAPSHOT_SCHEMA_VERSION;
+
+export type SnapshotFormat = "json" | "cbor" | "cbor.gz";
+export type SnapshotShardingMode = "monolithic" | "sharded";
+
+/** Stable app metadata. Sorted by `appGuid` in the snapshot. */
+export interface AppIdentity {
+	appGuid: StableAppId;
+	publisher: string;
+	name: string;
+	version: string;
+}
+
+/** Interning table — stable IDs and parallel display names. Facts reference
+ *  ids; the table provides the human-readable name once per id. Arrays are
+ *  parallel: stableIds[i] ↔ displayNames[i]. Sorted by stableIds. */
+export interface SnapshotIdentityTable {
+	stableIds: string[];
+	displayNames: string[];
+}
+
+/** Canonical fingerprint of one parsed attribute — name + SHA-256 of
+ *  normalized argument list. */
+export interface AttributeFingerprint {
+	name: string;
+	argsHash: string;
+}
+
+/** Contract surface — drives Phase 2 ABI / contract diff. */
+export interface ContractFact {
+	kind: "object" | "routine" | "event-publisher" | "interface";
+	stableId: string;
+	visibility: "public" | "internal" | "local" | "protected";
+	obsoleteState?: "Pending" | "Removed";
+	obsoleteReason?: string;
+	/** Routines + events: parameter shape hash + return-type hash. */
+	signatureFingerprint: string;
+	attributes: AttributeFingerprint[];
+}
+
+/** Schema surface — drives Phase 2 schema diff. */
+export interface SchemaFact {
+	kind: "table" | "field" | "enum" | "enum-value" | "key";
+	stableId: string;
+	/** Type/length/option/relation/dataclassification, canonicalised + SHA-256. */
+	shapeFingerprint: string;
+	dataClassification?: string;
+}
+
+/** Anchor metadata for replaying op witnesses without re-reading AL source. */
+export interface OperationEvidence {
+	operationId: OperationId;
+	routine: StableRoutineId;
+	sourceFile: string;
+	startLine: number;
+	startColumn: number;
+	endLine: number;
+	endColumn: number;
+	displayText: string;
+}
+
+/** Anchor metadata for call witnesses. */
+export interface CallsiteEvidence {
+	callsiteId: CallsiteId;
+	routine: StableRoutineId;
+	sourceFile: string;
+	startLine: number;
+	startColumn: number;
+	endLine: number;
+	endColumn: number;
+	calleeDisplay: string;
+}
+
+/** Reproducibility input — every file whose content contributes to the
+ *  snapshot identity. */
+export interface SnapshotInput {
+	kind: "app-json" | "roots-config" | "policy" | "dep-package" | "app-package";
+	path: string;
+	contentHash: string;
+}
+
+/**
+ * Side-band metadata about the inputs list. Tracks operator overrides
+ * that affect what does or doesn't appear in `inputs` (e.g.
+ * roots.config.json skipped via --no-roots-config). Distinct from
+ * `inputs` itself so diff tools can tell "config doesn't exist" (no
+ * inputsMetadata) from "config existed but was ignored"
+ * (`rootsConfigIgnored: true`).
+ */
+export interface SnapshotInputsMetadata {
+	/** True if `roots.config.json` was present on disk but skipped via --no-roots-config. */
+	rootsConfigIgnored?: boolean;
+}
+
+/** Subscriber binding — points to publisher object + event name. */
+export interface SubscriberBinding {
+	publisherObject: StableObjectId;
+	eventName: string;
+}
+
+/** Bipartite publisher / subscriber declaration. */
+export interface EventDeclaration {
+	kind: "publisher" | "subscriber";
+	routine: StableRoutineId;
+	eventId: StableEventId;
+	binding?: SubscriberBinding;
+	sourceAnchor: SourceAnchor;
+}
+
+/** Phase 0c reserves this slot; Phase 1's root-classifier populates it. */
+export interface RootClassificationSlot {
+	routineId: StableRoutineId;
+	kinds: string[];
+	externallyReachable: boolean;
+	source: "ast" | "config" | "ast+config";
+	confidence: "static" | "user-asserted";
+	sourceAnchor?: SourceAnchor;
+	configEntryId?: string;
+	resolutionStatus?: "resolved" | "ambiguous" | "unresolved";
+}
+
+/** Sharded layout manifest. References per-app shard files by stable app id. */
+export interface ShardManifest {
+	schemaVersion: SnapshotSchemaVersion;
+	alsemVersion: string;
+	workspaceFingerprint: string;
+	shards: Array<{
+		appGuid: StableAppId;
+		role: "primary" | "dependency";
+		file: string;
+	}>;
+}
+
+/** The semantic snapshot — single source of truth for Phase 1+ consumers. */
+export interface CapabilitySnapshot {
+	schemaVersion: SnapshotSchemaVersion;
+	alsemVersion: string;
+	workspaceFingerprint: string;
+	generatedAt: string;
+	apps: AppIdentity[];
+	identities: SnapshotIdentityTable;
+	contractFacts: ContractFact[];
+	schemaFacts: SchemaFact[];
+	permissionFacts: PermissionFact[];
+	rootClassifications: RootClassificationSlot[];
+	capabilityFacts: CapabilityFact[];
+	typedEdges: GraphEdge[];
+	operationIndex: OperationEvidence[];
+	callsiteIndex: CallsiteEvidence[];
+	coverage: CoverageRecord[];
+	inputs: SnapshotInput[];
+	/**
+	 * Side-band metadata about the inputs list. Tracks operator overrides
+	 * that affect what does or doesn't appear in `inputs` (e.g.
+	 * roots.config.json skipped via --no-roots-config). Distinct from
+	 * `inputs` itself so diff tools can tell "config doesn't exist" (no
+	 * inputsMetadata) from "config existed but was ignored"
+	 * (`rootsConfigIgnored: true`).
+	 *
+	 * Omitted entirely when no overrides apply — avoids noisy
+	 * `inputsMetadata: {}` in serialized output.
+	 */
+	inputsMetadata?: SnapshotInputsMetadata;
+	eventDeclarations: EventDeclaration[];
+}

package/src/symbols/app-manifest.ts

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { filteredUnzip } from "./app-package-zip.ts";
+
+export interface ManifestAppIdentity {
+	appGuid: string;
+	name: string;
+	publisher: string;
+	version: string;
+}
+
+export interface ManifestDependency {
+	appGuid: string;
+	name: string;
+	publisher: string;
+	minVersion: string;
+}
+
+export interface AppManifest {
+	identity: ManifestAppIdentity;
+	dependencies: ManifestDependency[];
+	/** ResourceExposurePolicy.IncludeSourceInSymbolFile — whether embedded .al source is present. */
+	includesSource: boolean;
+	/** Set when the manifest could not be parsed; identity is then empty. */
+	error?: string;
+}
+
+/** Build an empty manifest carrying an error — used for every failure path (no silent clean). */
+function failManifest(error: string): AppManifest {
+	return {
+		identity: { appGuid: "", name: "", publisher: "", version: "" },
+		dependencies: [],
+		includesSource: false,
+		error,
+	};
+}
+
+/** Read an attribute value out of an opening tag, anchored on a word boundary so a
+ * longer attribute name (e.g. `CompatibilityId`) cannot be matched as a shorter one (`Id`). */
+function readTagAttr(tag: string, attr: string): string {
+	return tag.match(new RegExp(`\\b${attr}\\s*=\\s*"([^"]*)"`, "i"))?.[1] ?? "";
+}
+
+/** Read one attribute from the first occurrence of `<tag ...>`, tolerant of attribute order. */
+function readAttr(xml: string, tag: string, attr: string): string {
+	const tagMatch = xml.match(new RegExp(`<${tag}\\b[^>]*>`, "i"));
+	if (!tagMatch) return "";
+	return readTagAttr(tagMatch[0], attr);
+}
+
+/** Parse the text of a NavxManifest.xml. Never throws — failure is reported via `error`. */
+export function parseAppManifestXml(xml: string): AppManifest {
+	if (!/<App\b/i.test(xml)) {
+		return failManifest("no <App> element found in manifest");
+	}
+	const identity: ManifestAppIdentity = {
+		appGuid: readAttr(xml, "App", "Id"),
+		name: readAttr(xml, "App", "Name"),
+		publisher: readAttr(xml, "App", "Publisher"),
+		version: readAttr(xml, "App", "Version"),
+	};
+	if (identity.appGuid === "") {
+		return failManifest("<App> element missing Id attribute");
+	}
+
+	const dependencies: ManifestDependency[] = [];
+	for (const m of xml.matchAll(/<Dependency\b[^>]*>/gi)) {
+		const tag = m[0];
+		dependencies.push({
+			appGuid: readTagAttr(tag, "Id"),
+			name: readTagAttr(tag, "Name"),
+			publisher: readTagAttr(tag, "Publisher"),
+			minVersion: readTagAttr(tag, "MinVersion"),
+		});
+	}
+
+	const includesSource = /IncludeSourceInSymbolFile\s*=\s*"true"/i.test(xml);
+
+	return { identity, dependencies, includesSource };
+}
+
+/** Read and parse NavxManifest.xml from a .app on disk. Never throws. */
+export function readAppManifest(appPath: string): AppManifest {
+	let xml: string;
+	try {
+		const bytes = new Uint8Array(readFileSync(appPath));
+		const entries = filteredUnzip(bytes, (name) => name.toLowerCase().endsWith("navxmanifest.xml"));
+		const key = Object.keys(entries)[0];
+		if (key === undefined) {
+			return failManifest("NavxManifest.xml not found in package");
+		}
+		xml = new TextDecoder("utf-8").decode(entries[key]);
+	} catch (err) {
+		return failManifest(`could not read package: ${(err as Error).message}`);
+	}
+	return parseAppManifestXml(xml);
+}

package/src/symbols/app-package-zip.ts

@@ -0,0 +1,50 @@
+import { type Unzipped, unzipSync } from "fflate";
+
+/** BC .app files may carry a binary header before the ZIP. The ZIP starts at PK\x03\x04. */
+export function stripAppHeader(bytes: Uint8Array): Uint8Array {
+	const limit = Math.min(bytes.length - 4, 4096);
+	for (let i = 0; i < limit; i++) {
+		if (
+			bytes[i] === 0x50 &&
+			bytes[i + 1] === 0x4b &&
+			bytes[i + 2] === 0x03 &&
+			bytes[i + 3] === 0x04
+		) {
+			return i === 0 ? bytes : bytes.subarray(i);
+		}
+	}
+	return bytes; // assume it is already a plain ZIP
+}
+
+/** Normalise a ZIP entry key: backslashes -> forward slashes. */
+export function normalizeZipEntryName(key: string): string {
+	return key.replace(/\\/g, "/");
+}
+
+/**
+ * Unzip only the entries `accept` returns true for. The `.app` header is stripped first.
+ * Keys in the returned map are normalised to forward slashes.
+ */
+export function filteredUnzip(appBytes: Uint8Array, accept: (name: string) => boolean): Unzipped {
+	const zip = stripAppHeader(appBytes);
+	const raw = unzipSync(zip, { filter: (f) => accept(normalizeZipEntryName(f.name)) });
+	const out: Unzipped = {};
+	for (const [k, v] of Object.entries(raw)) out[normalizeZipEntryName(k)] = v;
+	return out;
+}
+
+/**
+ * Enumerate every ZIP entry name without decompressing anything — the `filter` callback
+ * sees every entry's metadata and we always return false.
+ */
+export function listZipEntryNames(appBytes: Uint8Array): string[] {
+	const zip = stripAppHeader(appBytes);
+	const names: string[] = [];
+	unzipSync(zip, {
+		filter: (f) => {
+			names.push(normalizeZipEntryName(f.name));
+			return false;
+		},
+	});
+	return names;
+}

package/src/symbols/embedded-source-reader.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { filteredUnzip } from "./app-package-zip.ts";
+
+export interface EmbeddedSourceFile {
+	/** Forward-slash relative path inside the package, e.g. "src/Foo.Codeunit.al". URL-escaped form kept as-is. */
+	relativePath: string;
+	content: string;
+}
+
+/**
+ * Async-iterate the embedded .al files of a .app, sorted by relative path.
+ *
+ * Decompresses every .al entry in ONE pass over the ZIP central directory, then yields
+ * them one at a time. The previous implementation called `filteredUnzip` per file, which
+ * re-parsed the ZIP central directory once per entry — on Microsoft Base Application
+ * (7,634 .al files in a ~41 MB compressed package) that was the dominant cost of the
+ * cold-build loop (~40 s of pure ZIP overhead, not accounted for in any per-phase timer).
+ *
+ * Peak retained memory still tracks "one file in transit at a time": each entry is
+ * removed from the entries map as it is yielded, so the GC can reclaim its bytes as
+ * the consumer advances.
+ */
+export async function* iterateEmbeddedSourceBytes(
+	appBytes: Uint8Array,
+): AsyncIterable<EmbeddedSourceFile> {
+	const entries = filteredUnzip(appBytes, (n) => n.toLowerCase().endsWith(".al"));
+	const names = Object.keys(entries).sort();
+	const decoder = new TextDecoder("utf-8");
+	for (const name of names) {
+		const bytes = entries[name];
+		if (bytes === undefined) continue; // entry vanished — defensive, should not happen
+		delete entries[name]; // free the buffer once we've handed it to the consumer
+		yield { relativePath: name, content: decoder.decode(bytes) };
+	}
+}
+
+/** Disk-path convenience: read the .app once, then async-iterate its embedded .al files. */
+export async function* iterateEmbeddedSource(appPath: string): AsyncIterable<EmbeddedSourceFile> {
+	const bytes = new Uint8Array(readFileSync(appPath));
+	yield* iterateEmbeddedSourceBytes(bytes);
+}

package/src/symbols/package-hash.ts

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { sha256OfStrings } from "../hash.ts";
+import { parseAppManifestXml } from "./app-manifest.ts";
+import { filteredUnzip } from "./app-package-zip.ts";
+
+/** Raw-byte sha256 of a .app's bytes — provenance only. */
+export function packageHashOfBytes(bytes: Uint8Array): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Disk-path convenience. */
+export function packageHash(appPath: string): string {
+	return packageHashOfBytes(new Uint8Array(readFileSync(appPath)));
+}
+
+const sha256 = (b: Uint8Array): string => createHash("sha256").update(b).digest("hex");
+
+/**
+ * Semantic content hash of a .app — the cache-key input. Hashes only what affects analysis:
+ * normalized manifest identity + declared dependency constraints, the SymbolReference.json
+ * content, and every embedded .al's content hash (sorted by relative path). Deliberately
+ * ignores ZIP metadata, entry order, timestamps, signing, and the .app binary header — so a
+ * re-download of the same release reuses the cache.
+ *
+ * Single-pass ZIP extraction: every relevant entry (manifest + symbol reference + every
+ * .al) is decompressed in ONE `filteredUnzip` call. The previous implementation made
+ * one `filteredUnzip` call PER .al entry plus separate calls for manifest and symbol
+ * reference — on Base Application (7,634 .al files) that re-parsed the ZIP central
+ * directory 7,636 times per cache-key computation.
+ */
+export function packageSemanticHashOfBytes(bytes: Uint8Array): string {
+	const entries = filteredUnzip(bytes, (name) => {
+		const lower = name.toLowerCase();
+		return (
+			lower.endsWith(".al") ||
+			lower.endsWith("navxmanifest.xml") ||
+			lower.endsWith("symbolreference.json")
+		);
+	});
+
+	// 1. manifest identity + declared dependency constraints
+	const manifestKey = Object.keys(entries).find((k) =>
+		k.toLowerCase().endsWith("navxmanifest.xml"),
+	);
+	const manifestXml =
+		manifestKey === undefined ? "" : new TextDecoder("utf-8").decode(entries[manifestKey]);
+	const manifest = parseAppManifestXml(manifestXml);
+	const manifestPart = sha256OfStrings([
+		manifest.identity.appGuid,
+		manifest.identity.name,
+		manifest.identity.publisher,
+		manifest.identity.version,
+		...manifest.dependencies
+			.map((d) => `${d.appGuid}|${d.publisher}|${d.name}|${d.minVersion}`)
+			.sort(),
+	]);
+
+	// 2. SymbolReference.json content
+	const symKey = Object.keys(entries).find((k) => k.toLowerCase().endsWith("symbolreference.json"));
+	const symPart = symKey === undefined ? "" : sha256(entries[symKey] ?? new Uint8Array());
+
+	// 3. embedded .al content hashes, sorted by relative path
+	const alNames = Object.keys(entries)
+		.filter((n) => n.toLowerCase().endsWith(".al"))
+		.sort();
+	const alParts: string[] = [];
+	for (const name of alNames) {
+		const b = entries[name];
+		if (b !== undefined) {
+			alParts.push(`${name}:${sha256(b)}`);
+		}
+	}
+
+	return sha256OfStrings(["pkgSemantic/v1", manifestPart, symPart, ...alParts]);
+}
+
+/** Disk-path convenience. */
+export function packageSemanticHash(appPath: string): string {
+	return packageSemanticHashOfBytes(new Uint8Array(readFileSync(appPath)));
+}