al-sem 0.0.1

package/src/model/root-classification.ts

@@ -0,0 +1,116 @@
+import type { SourceAnchor } from "./identity.ts";
+import type { RoutineId } from "./ids.ts";
+
+/**
+ * The classification kinds a routine may receive from §4.3 root-classifier.
+ * Each value names a static AST-derivable entry-point pattern.
+ *
+ * Deferred kinds (not produced by the Phase 1 §4.3 classifier; reserved for
+ * future substrate):
+ *   - page-action: needs Page action AST indexing.
+ *   - web-service-exposed: needs cross-object WebService scan.
+ *   - job-queue-entrypoint: no static signal; runtime-registered.
+ *
+ * "externallyReachable" routines are those whose RootKind set includes any
+ * kind that is fired from outside the AL code itself (BC runtime, HTTP,
+ * test runner, etc.). All Phase §4.3 kinds today qualify.
+ */
+export type RootKind =
+	| "trigger-table"
+	| "trigger-page"
+	| "page-action" // deferred: needs Page action AST indexing
+	| "report-trigger"
+	| "event-subscriber"
+	| "install-codeunit"
+	| "upgrade-codeunit"
+	| "api-page"
+	| "web-service-exposed" // deferred: needs cross-object WebService scan
+	| "job-queue-entrypoint" // deferred: no static signal (runtime-registered)
+	| "public-procedure"
+	| "test-procedure";
+
+/**
+ * Per-routine classification with full provenance (spec §4.3). One entry per
+ * classified routine; routines with no qualifying kind are not in the array.
+ *
+ * `kinds` is deduplicated and sorted in `RootKind` declaration order — Task 3's
+ * AST classifier and Task 6's overlay both produce arrays satisfying this invariant.
+ *
+ * `source` records how the classification was produced:
+ *   - "ast"        — derived purely from AST + attributes (no config file).
+ *   - "config"     — roots.config.json asserted this routine as a root.
+ *   - "ast+config" — both paths agreed (or both contributed kinds — the
+ *                    union is recorded; disagreement emits a diagnostic).
+ *
+ * `confidence` is "user-asserted" iff `source === "config"` (config-only
+ * with no AST corroboration); otherwise "static".
+ *
+ * `resolutionStatus` is only populated when `source` includes "config":
+ *   - "resolved"   — config entry mapped to exactly one routine.
+ *   - "ambiguous"  — config entry matched multiple routines (a diagnostic
+ *                    was emitted; this classification reflects the FIRST
+ *                    match by canonical id sort).
+ *   - "unresolved" — config entry did not match any routine.
+ */
+export interface RootClassification {
+	routineId: RoutineId;
+	kinds: RootKind[];
+	externallyReachable: boolean;
+	source: "ast" | "config" | "ast+config";
+	confidence: "static" | "user-asserted";
+	sourceAnchor?: SourceAnchor;
+	configEntryId?: string;
+	resolutionStatus?: "resolved" | "ambiguous" | "unresolved";
+}
+
+/**
+ * Returns true if the kind is externally reachable today. Spec §4.3 marks
+ * all current kinds externally reachable; this helper centralises the
+ * mapping so future internal-trigger-style kinds can opt out cleanly.
+ *
+ * Exhaustiveness-guarded: adding a RootKind variant must extend this switch.
+ */
+export function isExternallyReachableKind(kind: RootKind): boolean {
+	switch (kind) {
+		case "trigger-table":
+		case "trigger-page":
+		case "page-action":
+		case "report-trigger":
+		case "event-subscriber":
+		case "install-codeunit":
+		case "upgrade-codeunit":
+		case "api-page":
+		case "web-service-exposed":
+		case "job-queue-entrypoint":
+		case "public-procedure":
+		case "test-procedure":
+			return true;
+		default: {
+			const _exhaustive: never = kind;
+			return _exhaustive;
+		}
+	}
+}
+
+/**
+ * Canonical RootKind values in declaration order. The single source of truth
+ * for valid kinds, consumed by the classifier (sort/dedup invariant), the
+ * roots-config loader (validation), and the §4.4 CLI (--roots flag validation).
+ *
+ * Promoted from `src/engine/root-classifier.ts`'s `ROOT_KIND_ORDER` so the
+ * model layer owns it. `ROOT_KIND_ORDER` becomes a re-export.
+ */
+export const ROOT_KIND_VALUES = [
+	"trigger-table",
+	"trigger-page",
+	"page-action",
+	"report-trigger",
+	"event-subscriber",
+	"install-codeunit",
+	"upgrade-codeunit",
+	"api-page",
+	"web-service-exposed",
+	"job-queue-entrypoint",
+	"public-procedure",
+	"test-procedure",
+] as const satisfies readonly RootKind[];

package/src/model/stable-identity.ts

@@ -0,0 +1,102 @@
+import type { FieldId, ObjectId, TableId } from "./ids.ts";
+
+/**
+ * Stable identities — snapshot-comparable across analysis runs and across
+ * al-sem versions. Used at the snapshot serialization boundary; in-memory
+ * model code continues to use the internal `ObjectId` / `TableId` / etc.
+ * for index speed.
+ *
+ * Format choice (`:` and `#` separators) deliberately differs from the
+ * internal id format (`/` separator) so the two cannot be accidentally
+ * substituted at type-check time when both are `string` aliases.
+ */
+export type StableAppId = string; // appGuid
+export type StableObjectId = string; // `${appGuid}:${objectType}:${objectNumber}`
+export type StableTableId = string; // `${appGuid}:Table:${tableNumber}`
+export type StableFieldId = string; // `${stableTableId}#${fieldNumber}`
+export type StableEventId = string; // `${stablePublisherObjectId}::${eventName}::${parameterShapeHash}`
+export type StableRoutineId = string; // `${stableObjectId}#${canonicalSignatureHash}`
+export type StablePermissionSetId = string; // permissionSetGuid OR `${appGuid}:PermissionSet:${name}`
+
+/**
+ * Bidirectional converter between in-memory ids and stable serialization ids.
+ *
+ * Phase 0a ships the format-only directions (Object/Table/Field/Event) plus
+ * the forward direction for routines. The reverse direction for routines
+ * requires a lookup table over `CanonicalRoutineKey` that is built in
+ * Phase 0b alongside the variable indexer.
+ */
+export interface IdentityIndex {
+	toStableObjectId(internal: ObjectId): StableObjectId;
+	toInternalObjectId(stable: StableObjectId): ObjectId;
+
+	toStableTableId(internal: TableId): StableTableId;
+	toInternalTableId(stable: StableTableId): TableId;
+
+	toStableFieldId(internal: FieldId): StableFieldId;
+	toInternalFieldId(stable: StableFieldId): FieldId;
+
+	toStableEventId(
+		publisher: StableObjectId,
+		eventName: string,
+		parameterShapeHash: string,
+	): StableEventId;
+
+	toStableRoutineIdFromParts(
+		stableObject: StableObjectId,
+		canonicalSignatureHash: string,
+	): StableRoutineId;
+}
+
+/** Factory — Phase 0a returns a stateless converter. Phase 0b will accept a
+ *  lookup-context argument so the routine reverse direction can be resolved. */
+export function createIdentityIndex(): IdentityIndex {
+	function toStableTableId(internal: TableId): StableTableId {
+		const parts = internal.split("/");
+		if (parts.length !== 3 || parts[1] !== "table") {
+			throw new Error(`toStableTableId: malformed TableId: ${internal}`);
+		}
+		return `${parts[0]}:Table:${parts[2]}`;
+	}
+	function toInternalTableId(stable: StableTableId): TableId {
+		const parts = stable.split(":");
+		if (parts.length !== 3 || parts[1] !== "Table") {
+			throw new Error(`toInternalTableId: malformed StableTableId: ${stable}`);
+		}
+		return `${parts[0]}/table/${parts[2]}`;
+	}
+	return {
+		toStableObjectId(internal) {
+			return internal.replaceAll("/", ":");
+		},
+		toInternalObjectId(stable) {
+			return stable.replaceAll(":", "/");
+		},
+		toStableTableId,
+		toInternalTableId,
+		toStableFieldId(internal) {
+			const lastSlash = internal.lastIndexOf("/");
+			if (lastSlash <= 0) {
+				throw new Error(`toStableFieldId: malformed FieldId: ${internal}`);
+			}
+			const tableInternal = internal.slice(0, lastSlash);
+			const fieldNum = internal.slice(lastSlash + 1);
+			return `${toStableTableId(tableInternal)}#${fieldNum}`;
+		},
+		toInternalFieldId(stable) {
+			const hash = stable.indexOf("#");
+			if (hash <= 0) {
+				throw new Error(`toInternalFieldId: malformed StableFieldId: ${stable}`);
+			}
+			const tableStable = stable.slice(0, hash);
+			const fieldNum = stable.slice(hash + 1);
+			return `${toInternalTableId(tableStable)}/${fieldNum}`;
+		},
+		toStableEventId(publisher, eventName, parameterShapeHash) {
+			return `${publisher}::${eventName}::${parameterShapeHash}`;
+		},
+		toStableRoutineIdFromParts(stableObject, canonicalSignatureHash) {
+			return `${stableObject}#${canonicalSignatureHash}`;
+		},
+	};
+}

package/src/model/summary.ts

@@ -0,0 +1,96 @@
+import type { CapabilityFact } from "./capability.ts";
+import type { CoverageRecord } from "./coverage.ts";
+import type { RecordOpType, TempState } from "./entities.ts";
+import type { CallsiteId, FieldId, OperationId, RoutineId, TableId } from "./ids.ts";
+
+/** Tri-state effect presence — distinct from "unresolved call". */
+export type EffectPresence = "yes" | "no" | "unknown";
+
+export type Uncertainty =
+	| { kind: "unresolved-call"; callsiteId: CallsiteId }
+	| { kind: "opaque-callee"; callsiteId: CallsiteId }
+	| { kind: "dynamic-dispatch"; operationId: OperationId }
+	| { kind: "recordref-or-variant"; operationId: OperationId }
+	| { kind: "interface-dispatch"; callsiteId: CallsiteId }
+	| { kind: "parse-incomplete"; routineId: RoutineId };
+
+/** Compact, de-duped effect fact. Carries NO evidence path — the path-walker rebuilds paths. */
+export interface DbEffect {
+	effectKey: string; // op + table + operationSite + paramDependency + uncertaintyKind
+	operationId: OperationId;
+	op: RecordOpType;
+	tableId: TableId | "unknown";
+	recordVariableId?: string;
+	tempState: TempState;
+	via: "direct" | "inherited" | "implicit-trigger" | "event-subscriber" | "dynamic";
+}
+
+/** Field effects relative to one parameter — required by detector D3. */
+export interface RecordRoleSummary {
+	parameterIndex: number;
+	tableId: TableId | "unknown";
+	readsFields: FieldId[] | "unknown";
+	writesFields: FieldId[] | "unknown";
+	mayResetFilters: boolean;
+	mayChangeLoadFields: boolean;
+	mayAssignRecord: boolean;
+	mayUseRecordRef: boolean;
+
+	// ====================================================================
+	// Entry requirements — populated in Phase 4 (path-aware walker)
+	// ====================================================================
+	requiresLoadedAtEntry: EffectPresence;
+	requiredLoadedFieldsAtEntry: FieldId[] | "unknown";
+	mutatesBeforeLoad: EffectPresence;
+
+	// ====================================================================
+	// Exit effects — populated in this phase (may-facts) and Phase 6 (path)
+	// ====================================================================
+	persistsCurrentRecord: EffectPresence;
+	setBasedDbWrites: EffectPresence;
+	validatesParam: EffectPresence;
+	copiesIntoParam: EffectPresence;
+	resetsFiltersOnParam: EffectPresence;
+	dirtyAtExit: EffectPresence;
+	currentLoadedFieldsAtExit: FieldId[] | "full" | "unknown";
+
+	// ====================================================================
+	// Convenience derivations
+	// ====================================================================
+	mutatesParam: EffectPresence;
+	loadsFromDbParam: EffectPresence;
+	initialisesParam: EffectPresence;
+}
+
+export interface FieldEffectSet {
+	readsByRecordVariable: Record<string, FieldId[]>;
+}
+
+export interface RoutineSummary {
+	routineId: RoutineId;
+	dbEffects: DbEffect[];
+	inRecursiveCycle: boolean;
+	hasUnresolvedCalls: boolean;
+	uncertainties: Uncertainty[];
+	parameterRoles: RecordRoleSummary[];
+	fieldEffects?: FieldEffectSet; // lazy — only when a detector needs it
+	/**
+	 * Phase 0a addition (capability-stack roadmap §3.4). Direct capability
+	 * facts emitted by this routine's body. `undefined` in Phase 0a
+	 * (extractor is still a no-op shell); populated in Phase 0b.
+	 */
+	capabilityFactsDirect?: CapabilityFact[];
+	/**
+	 * Phase 0a addition. Capability facts inherited from the routine's
+	 * transitive reachable closure (via call / event-dispatch /
+	 * object-run / implicit-trigger / dependency-export edges). `undefined`
+	 * in Phase 0a; populated in Phase 0b.
+	 */
+	capabilityFactsInherited?: CapabilityFact[];
+	/**
+	 * Phase 0a addition. Coverage status for this routine's direct
+	 * extraction + inherited capability cone. `undefined` in Phase 0a;
+	 * populated in Phase 0b.
+	 */
+	coverage?: CoverageRecord;
+}

package/src/parser/ast.ts

@@ -0,0 +1,82 @@
+import type { SourceRange } from "../model/identity.ts";
+import type { Node as SyntaxNode } from "./native/wrapper.ts";
+
+/** Strip surrounding double quotes from a quoted_identifier node's text. */
+export function stripQuotes(text: string): string {
+	if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+		return text.slice(1, -1);
+	}
+	return text;
+}
+
+/** Map a tree-sitter node's position to a model SourceRange (0-based). */
+export function nodeToSourceRange(node: SyntaxNode): SourceRange {
+	return {
+		startLine: node.startPosition.row,
+		startColumn: node.startPosition.column,
+		endLine: node.endPosition.row,
+		endColumn: node.endPosition.column,
+	};
+}
+
+/**
+ * Depth-first collect every named descendant (and the node itself) matching a predicate.
+ * Traverses `namedChildren`, so anonymous tokens are skipped. Traversal order is not
+ * guaranteed to match document order — the stack-based DFS visits siblings in reverse.
+ *
+ * When `pruneAtMatch` is true, the traversal does not descend into a node that matched
+ * the predicate. Use for "find top-level X" patterns where descendants of an X can never
+ * themselves be the X we're looking for — e.g. AL has no nested procedures, so the
+ * routine-finder should not walk into a procedure's body looking for more procedures.
+ * On a big object that pruning collapses an O(routines × body-size) traversal into one
+ * proportional to the object skeleton only.
+ */
+export function collectDescendants(
+	root: SyntaxNode,
+	predicate: (node: SyntaxNode) => boolean,
+	pruneAtMatch = false,
+): SyntaxNode[] {
+	const out: SyntaxNode[] = [];
+	const stack: SyntaxNode[] = [root];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (!node) continue;
+		if (predicate(node)) {
+			out.push(node);
+			if (pruneAtMatch) continue; // don't descend into matched node
+		}
+		for (const child of node.namedChildren) {
+			if (child) stack.push(child);
+		}
+	}
+	return out;
+}
+
+/** True if `node` is a descendant of `ancestor`. */
+export function isDescendantOf(node: SyntaxNode, ancestor: SyntaxNode): boolean {
+	let current = node.parent;
+	while (current) {
+		if (current.id === ancestor.id) return true;
+		current = current.parent;
+	}
+	return false;
+}
+
+/** Find the first named child matching a predicate, or null. */
+export function findChild(
+	node: SyntaxNode,
+	predicate: (child: SyntaxNode) => boolean,
+): SyntaxNode | null {
+	for (const child of node.namedChildren) {
+		if (child && predicate(child)) return child;
+	}
+	return null;
+}
+
+/** True if a node is a generic V2 `property` node with the given name (case-insensitive). */
+export function isPropertyNamed(node: SyntaxNode, name: string): boolean {
+	return (
+		node.type === "property" &&
+		node.childForFieldName("name")?.text?.toLowerCase() === name.toLowerCase()
+	);
+}

package/src/parser/native/ffi.ts

@@ -0,0 +1,145 @@
+// src/parser/native/ffi.ts
+// bun:ffi declarations for the al_shim ABI. Two-phase load for clean
+// ABI-mismatch diagnostics. Module-level singleton (one process = one parser).
+
+import { FFIType, type Library, dlopen } from "bun:ffi";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { arch as nodeArch, platform as nodePlatform } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const EXPECTED_MAJOR = 1;
+const REQUIRED_MINOR = 0;
+
+export class NativeParserUnavailableError extends Error {
+	readonly kind: "missing" | "abi-mismatch" | "symbol-missing";
+	constructor(kind: NativeParserUnavailableError["kind"], message: string) {
+		super(message);
+		this.name = "NativeParserUnavailableError";
+		this.kind = kind;
+	}
+}
+
+interface MetaShape {
+	tag: string;
+	platform: string;
+	arch: string;
+	asset: string;
+	sha256: string;
+}
+
+function resolveLibPath(): string {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const metaPath = join(here, "lib.meta.json");
+	if (!existsSync(metaPath)) {
+		throw new NativeParserUnavailableError(
+			"missing",
+			`al-sem: native parser meta missing at ${metaPath}. Did 'bun install' complete? If running offline, set AL_SEM_NATIVE_PARSER_PATH to a preseeded artifact.`,
+		);
+	}
+	const meta = JSON.parse(readFileSync(metaPath, "utf8")) as MetaShape;
+	if (meta.platform !== nodePlatform || meta.arch !== nodeArch) {
+		throw new NativeParserUnavailableError(
+			"abi-mismatch",
+			`al-sem: native parser meta is for ${meta.platform}-${meta.arch}, ` +
+				`but current process is ${nodePlatform}-${nodeArch}. Re-run 'bun install'.`,
+		);
+	}
+	const ext = meta.asset.split(".").pop() ?? "so";
+	const libPath = join(here, `lib-${meta.tag}-${meta.platform}-${meta.arch}.${ext}`);
+	if (!existsSync(libPath)) {
+		throw new NativeParserUnavailableError(
+			"missing",
+			`al-sem: native parser library missing at ${libPath}. Re-run 'bun install'.`,
+		);
+	}
+	return libPath;
+}
+
+const FULL_SYMBOLS = {
+	al_shim_abi_version: { args: [], returns: FFIType.u32 },
+	al_shim_parser_new: { args: [], returns: FFIType.ptr },
+	al_shim_parser_delete: { args: [FFIType.ptr], returns: FFIType.void },
+	al_shim_language: { args: [], returns: FFIType.ptr },
+	al_shim_parser_set_language: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.u32 },
+	al_shim_parse_utf8: { args: [FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.ptr },
+	al_shim_tree_delete: { args: [FFIType.ptr], returns: FFIType.void },
+	al_shim_node_size: { args: [], returns: FFIType.u32 },
+	al_shim_tree_root_node: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+	al_shim_node_type: { args: [FFIType.ptr], returns: FFIType.cstring },
+	al_shim_node_start_byte: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_end_byte: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_start_row: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_start_column: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_end_row: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_end_column: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_child_count: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_named_child_count: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_child: { args: [FFIType.ptr, FFIType.u32, FFIType.ptr], returns: FFIType.void },
+	al_shim_node_named_child: {
+		args: [FFIType.ptr, FFIType.u32, FFIType.ptr],
+		returns: FFIType.void,
+	},
+	al_shim_node_child_by_field_name: {
+		args: [FFIType.ptr, FFIType.ptr, FFIType.u32, FFIType.ptr],
+		returns: FFIType.void,
+	},
+	al_shim_node_parent: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+	al_shim_node_previous_sibling: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+	al_shim_node_next_sibling: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+	al_shim_node_is_null: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_is_named: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_eq: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.u32 },
+	al_shim_node_has_error: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_cursor_new: { args: [FFIType.ptr], returns: FFIType.ptr },
+	al_shim_cursor_delete: { args: [FFIType.ptr], returns: FFIType.void },
+	al_shim_cursor_goto_first_child: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_cursor_goto_next_sibling: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_cursor_goto_parent: { args: [FFIType.ptr], returns: FFIType.u32 },
+	al_shim_cursor_current_node: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+	al_shim_cursor_current_field_name: { args: [FFIType.ptr], returns: FFIType.cstring },
+	al_shim_tree_sitter_language_version: { args: [], returns: FFIType.u32 },
+	al_shim_tree_sitter_min_compatible_language_version: { args: [], returns: FFIType.u32 },
+} as const;
+
+let cached: Library<typeof FULL_SYMBOLS> | null = null;
+
+export function loadShim(): Library<typeof FULL_SYMBOLS> {
+	if (cached) return cached;
+	const libPath = resolveLibPath();
+
+	// Phase 1: load only the version function. If this fails, the lib is broken
+	// or missing — we know it's not an ABI mismatch.
+	let v: Library<{ al_shim_abi_version: { args: []; returns: typeof FFIType.u32 } }>;
+	try {
+		v = dlopen(libPath, { al_shim_abi_version: { args: [], returns: FFIType.u32 } });
+	} catch (err) {
+		throw new NativeParserUnavailableError(
+			"missing",
+			`al-sem: could not dlopen ${libPath}: ${(err as Error).message}. Re-run 'bun install'.`,
+		);
+	}
+	const version = v.symbols.al_shim_abi_version();
+	const major = (version >>> 16) & 0xffff;
+	const minor = version & 0xffff;
+	if (major !== EXPECTED_MAJOR || minor < REQUIRED_MINOR) {
+		throw new NativeParserUnavailableError(
+			"abi-mismatch",
+			`al-sem: native parser ABI ${major}.${minor} is incompatible with this build ` +
+				`(needs ${EXPECTED_MAJOR}.${REQUIRED_MINOR}+). Re-install al-sem.`,
+		);
+	}
+
+	// Phase 2: load the full symbol surface. A missing symbol now raises a
+	// meaningful error (we know the ABI version is right, so the lib is corrupt
+	// or wrong-build).
+	try {
+		cached = dlopen(libPath, FULL_SYMBOLS);
+	} catch (err) {
+		throw new NativeParserUnavailableError(
+			"symbol-missing",
+			`al-sem: native parser is missing expected symbols: ${(err as Error).message}. Re-install al-sem.`,
+		);
+	}
+	return cached;
+}

package/src/parser/native/parse-index-pool.ts

@@ -0,0 +1,148 @@
+// src/parser/native/parse-index-pool.ts
+// Tiny fixed-size pool around the parse-index Worker. Round-robin dispatch with
+// per-worker busy state; each `submit()` returns a Promise resolved when that
+// specific worker completes the job.
+//
+// Determinism contract: the pool does NOT preserve submission order in results.
+// Callers must collect all results, then merge in a canonical order (e.g. sorted
+// by relativePath) before pushing into the SemanticIndex. The dependency
+// pipeline does this explicitly.
+
+import type { WorkerResult } from "./parse-index-worker.ts";
+
+export interface ParseIndexJob {
+	relativePath: string;
+	content: string;
+	appGuid: string;
+	sourceUnitId: string;
+	modelInstanceId: string;
+}
+
+interface PendingJob {
+	jobId: number;
+	resolve: (value: WorkerResult) => void;
+	reject: (reason: Error) => void;
+}
+
+export class ParseIndexPool {
+	private workers: Worker[];
+	private pending: Map<number, PendingJob> = new Map();
+	private nextJobId = 0;
+	/** Round-robin pointer; the next worker to receive a job. */
+	private rr = 0;
+	private disposed = false;
+
+	constructor(size: number) {
+		if (size < 1) throw new Error("ParseIndexPool size must be >= 1");
+		this.workers = new Array(size);
+		for (let i = 0; i < size; i++) {
+			const w = new Worker(new URL("./parse-index-worker.ts", import.meta.url), {
+				type: "module",
+			});
+			w.onmessage = (event: MessageEvent<WorkerResult>) => {
+				const job = this.pending.get(event.data.jobId);
+				if (!job) return; // late message after termination
+				this.pending.delete(event.data.jobId);
+				job.resolve(event.data);
+			};
+			w.onerror = (event) => {
+				// Worker-level error — fail every in-flight job; the worker is unusable now.
+				const message = `parse-index worker crashed: ${event.message ?? "unknown"}`;
+				for (const job of this.pending.values()) job.reject(new Error(message));
+				this.pending.clear();
+			};
+			this.workers[i] = w;
+		}
+	}
+
+	get size(): number {
+		return this.workers.length;
+	}
+
+	submit(job: ParseIndexJob): Promise<WorkerResult> {
+		if (this.disposed) return Promise.reject(new Error("ParseIndexPool is disposed"));
+		const jobId = this.nextJobId++;
+		const worker = this.workers[this.rr];
+		this.rr = (this.rr + 1) % this.workers.length;
+		const promise = new Promise<WorkerResult>((resolve, reject) => {
+			this.pending.set(jobId, { jobId, resolve, reject });
+		});
+		worker?.postMessage({ jobId, ...job });
+		return promise;
+	}
+
+	/**
+	 * Drive `jobs` through the pool with bounded in-flight concurrency. At most
+	 * `maxInFlight` jobs are pending at once — back-pressure that keeps the workers'
+	 * mailboxes from filling up with all of `jobs[]` at once. Critical for big deps:
+	 * submitting all 7,634 jobs for Base Application at once means structured-cloning
+	 * 97 MB of source into mailboxes and queueing 97 k routine arrays of results back,
+	 * which is enough to OOM the runtime. Returns results in `jobs[]` order (the
+	 * caller sorts later if it needs a different order).
+	 */
+	async mapBounded(
+		jobs: ParseIndexJob[],
+		maxInFlight: number = this.workers.length * 2,
+		onComplete?: (result: WorkerResult) => void,
+	): Promise<WorkerResult[]> {
+		const results: WorkerResult[] = new Array(jobs.length);
+		let nextIdx = 0;
+		const limit = Math.max(1, Math.min(maxInFlight, jobs.length));
+		const runOne = async (slot: number): Promise<void> => {
+			while (true) {
+				const idx = nextIdx++;
+				if (idx >= jobs.length) return;
+				const job = jobs[idx];
+				if (!job) continue;
+				const r = await this.submit(job);
+				results[idx] = r;
+				onComplete?.(r);
+			}
+		};
+		const runners: Promise<void>[] = new Array(limit);
+		for (let i = 0; i < limit; i++) runners[i] = runOne(i);
+		await Promise.all(runners);
+		return results;
+	}
+
+	terminate(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		for (const w of this.workers) w.terminate();
+		for (const job of this.pending.values()) {
+			job.reject(new Error("ParseIndexPool terminated before job completed"));
+		}
+		this.pending.clear();
+	}
+}
+
+/**
+ * Default pool size: physical-cores-minus-one, clamped to [2, 16]. Leave one core for
+ * the main thread doing the merge/sort and the OS. Override via the
+ * `AL_SEM_PARSE_POOL_SIZE` env var if needed.
+ *
+ * The clamp ceiling is 16 (was 8): on Microsoft Base Application (8,124 embedded files,
+ * 108,848 routines) measured cold-parse wall time was 8w=10.0s, 16w=7.6s, 24w=6.4s — the
+ * knee is ~16. Past it, the serial result-merge (sorted insertion of 108k routines on the
+ * main thread) dominates, so more workers buy little. Power users on many-core boxes can
+ * push higher via `AL_SEM_PARSE_POOL_SIZE`.
+ */
+export function defaultPoolSize(): number {
+	const envOverride = process.env.AL_SEM_PARSE_POOL_SIZE;
+	if (envOverride !== undefined) {
+		const n = Number.parseInt(envOverride, 10);
+		if (Number.isFinite(n) && n >= 1) return n;
+	}
+	const cores = (() => {
+		try {
+			const os = require("node:os") as {
+				availableParallelism?: () => number;
+				cpus?: () => unknown[];
+			};
+			if (typeof os.availableParallelism === "function") return os.availableParallelism();
+			if (typeof os.cpus === "function") return os.cpus().length;
+		} catch {}
+		return 4;
+	})();
+	return Math.max(2, Math.min(16, cores - 1));
+}