Program assembly - Design model

Platform spec article

Program assembly - Design model

Back to Program assembly ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-feature-hub-authority Feature hub authority Accepted

   This feature hub owns normative MUST/SHOULD contract text for Program assembly.

   Context

   Sibling articles under this feature previously restated requirements in inconsistent forms.

   Decision

   This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

   Verification anchors

   • site/website/src/content/docs/platform-spec/compiler/build-pipeline/program-assembly/index.mdx
   • article bundle under the same feature directory.

   Open full ADR page

2. 0002-spec-over-implementation-notes Specification over implementation notes Accepted

   Platform-spec text supersedes informal crate comments for Program assembly.

   Context

   Implementation crates accumulated informal notes that diverged from published contracts.

   Decision

   Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.

   Consequences

   Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

   Verification anchors

   • compiler/crates/beskid_analysis/

   Open full ADR page

3. 0003-primary-contract-choice Primary contract for Program assembly Accepted

   This feature hub defines how the reference compiler turns a resolved **`CompilePlan`** plus **effective (materialized-fi

   Context

   This feature hub defines how the reference compiler turns a resolved CompilePlan plus effective (materialized-first) source roots into a ProgramAssembly: discovered .bd units, a shared ModuleIndex for cross-module resolution, and a single front-end spine consumed by CLI, LSP, analyze, and codegen. JIT and AOT backends consume CodegenArtifact only and do not re-run assembly.

   Decision

   The reference compiler must implement Program assembly as documented in this feature hub and its article bundle.

   Consequences

   Changes require hub/ADR updates and verification anchor extensions.

   Verification anchors

   • compiler/crates/beskid_analysis/

   Open full ADR page

Articles

• Program assembly - Contracts and edge cases Materialized-first roots, discovery caps, and parity across CLI and LSP. article Standard Reviewed Wed May 20
• Program assembly - Design model EffectiveCompilationRoots, ProgramAssembly, ModuleIndex, and hybrid discovery modes. article Standard Reviewed Wed May 20
• Program assembly - Flow and algorithm Ordered assembly after workspace materialize and before multi-unit parse and HIR resolution. article Standard Reviewed Wed May 20
• Program assembly - Verification and traceability Test and source anchors for ProgramAssembly and effective roots. article Standard Reviewed Wed May 20

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 1 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Program assembly

  Parent feature hub

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).