Program assembly - Design model

import SpecArticleChrome from '@beskid/beskid-ui/platform-spec/SpecArticleChrome.astro';

<SpecArticleChrome />

Core objects

Object	Role
EffectiveCompilationRoots	Host + dependency source roots; materialized paths from PreparedProjectWorkspace or Project.lock take precedence over plan source_root paths
SourceUnit	One parsed .bd file: logical name, path, text, Spanned<Program>
ModuleIndex	Cross-unit module graph and item table used to prefetch resolution for the entry unit
ProgramAssembly	Roots, units, entry index, discovery mode, and ModuleIndex
AssemblyOptions	discovery (ImportClosure vs WorkspaceScan), include_std_prelude, max_units

Hybrid discovery (normative)

• Build / run / lower / test — ImportClosure: entry file, transitive use edges, and implicit std/prelude when CompilePlan.has_std_dependency is true.
• LSP workspace file index — WorkspaceScan: all *.bd files under each effective root for closed-buffer diagnostics indexing, capped by max_units (deterministic sort order).
• LSP / IDE document snapshots — ImportClosure via CompilationContext::assembly_for_entry so IntelliSense resolution matches compile/lower (ModuleIndex::resolve_entry_hir on the entry buffer).

use aliases and step-6 resolution

• A use declaration registers an import alias (explicit as name or default tail of the path, e.g. use Std.System.IO → alias IO) mapped to the full logical module path in the merged ModuleGraph from ModuleIndex.
• Value and type paths such as IO.PrintLine or String.IsEmpty must resolve through alias expansion to Std::System::IO::PrintLine (etc.) during the resolver pass, producing ordinary Item bindings—not ItemKind::Use placeholders.
• Staged semantic E1105 (unknown import path) must consult assembly-known module paths when ProgramAssembly is available, not file-local root heuristics alone.

IDE consumption

• beskid_analysis::services::build_document_analysis_with_context lowers and normalizes the entry program, then calls assembly.module_index.resolve_entry_hir when assembly is available.
• Resolved items from dependency units carry ItemInfo.source_path so LSP go-to-definition, find references, and hover map to the declaring .bd file URI.
• Workspace find references on non-entry units use ModuleIndex::resolve_unit_hir per dependency unit when merging matches into references_at_offset_workspace.
• Import aliases collected in the entry unit are exposed on Resolution.module_imports for member completion (IO. → Std::System::IO scope).

CLI and JIT/AOT parity

• beskid build and beskid run must use the same PreparedProjectWorkspace materialized roots and ModuleIndex::resolve_entry_hir on the entry unit before codegen.
• beskid run must call compile_front_end_from_resolved_input (or equivalent) with prepared_workspace from project resolve — not a second assemble path with prepared_workspace: None.

Backend boundary

Assembly and the shared front-end spine end at typed HIR and CodegenArtifact. beskid_engine (JIT) and beskid_aot (link) must not rebuild CompilePlan or rediscover modules.

Implementation owner

beskid_analysis::projects::assembly and beskid_analysis::services::front_end (see Implementation map).