Compiler Mods

Platform spec area

Compiler Mods

Back to Compiler ◎ Open in platform map

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs

No architecture decision records under adr/ for this feature yet. Standard features must publish at least one ADR or keep a ## Decisions summary on the hub.

Articles

• No directly attached article pages for this node. Nested descendants exist deeper in this subtree.

History

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

Open full history on GitHub

No commits recorded for this path.

Architecture

Compiler Mod contracts

Relationships between Mod projects, Compiler Mod SDK contracts, the Rust mod host, and downstream semantic/codegen stages.

Completeness

OKarea · 7 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
scope	yes	yes
features	yes	yes

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

Related spec docs

• Domain
  Compiler

  Parent domain hub

• Area
  Metaprogramming (language meta)

  Beskid-side Mod SDK and language-facing mod contracts

• Feature
  Compiler Mod SDK

  Beskid contracts for Collector/Generator/Analyzer/Rewriter

• Feature
  Project manifest contract

  Mod project type and manifest wiring

• Area
  Build pipeline

  Lowering and backends after mod merge

• Feature
  Stage ordering and lowering

  Where mod collection/generation/analyze phases sit in the compiler pipeline

Canonical ownership

This compiler area defines the Rust-side behavior for compiler mods. Project manifest contract defines the Mod project type and package metadata. Compiler Mod SDK defines Beskid-side contracts; this area defines discovery, AOT artifact lifecycle, execution phases, typed merge semantics, diagnostics transport, and incremental invalidation.

Scope

Normative pages specify interfaces, cache boundaries, and host policy—not product backlogs. They drive compiler/ and corelib surfaces exposed at compile time.

Mod projects in this area are strictly for Beskid-authored compile-time work: analysis, code generation (typed AST), and rewrites over host compilations. Compiler-core composition and IoC remain Rust-owned and are specified separately under compiler features.

Compiler mods (concept)

Compiler mods are Mod projects discovered from the dependency graph. The compiler compiles mods AOT and loads their artifacts during host compilation. Discovery is contract-driven (Collector, Generator, Analyzer, Rewriter, AttributeGenerator), not grammar-item-driven.

Mod API shape (modules)

The compile-time package groups the natural compilation shape into modules (exact naming may evolve; boundaries are normative):

Module	Role
Beskid.Syntax	Typed syntax node mirror with stable identities and structural builders.
Beskid.Compiler.Query	Declarative query surfaces over syntax and semantic snapshots.
Beskid.Compiler.Collect	Collector, Generator, Analyzer, Rewriter, and AttributeGenerator contracts plus target-selection primitives.
Beskid.Compiler.Diagnostics	Compiler-native diagnostics transport for analyzers and rewrite suggestions.
Beskid.Compiler.TypedEmitter	Typed AST contributions and typed rewrites; no raw text/formatting contract.

Beskid.Compiler.Compilation remains the handle for the active host compilation instance.

Feature hubs below map onto these boundaries with traceability into beskid_analysis, beskid_lsp, beskid_codegen, beskid_engine, and beskid_runtime.

Mod projects and pipeline phase ids

flowchart LR
  parse[parse]
  modload[mod.load]
  collect[mod.collect]
  generate[mod.generate]
  reparse[reparse if needed]
  semantic[semantic.snapshot]
  analyze[mod.analyze]
  rewrite[mod.rewrite]
  lowerready[lower.ready]
  parse --> modload --> collect --> generate --> reparse --> semantic --> analyze --> rewrite --> lowerready

For project.type = Mod, the host registers mod contracts and emits beskid_pipeline phase events for collection, generation, analyzer, and rewrite boundaries. Strings below are normative literals that must be defined in compiler/crates/beskid_pipeline/src/phases.rs and asserted by conformance tests.

Phase id (literal)	Rust constant (recommended)	When emitted	Typical invalidation
mod.load	MOD_LOAD	After dependency graph resolves and mod AOT artifacts are available	Full mod schedule rebuild
syntax.generation	SYNTAX_GENERATION	After parse produces a new immutable Program snapshot for a compilation unit	Query/collect keys tied to syntax ids
mod.collect	MOD_COLLECT	Collector contracts declare target sets for active mods	Collector cache boundaries
mod.generate	MOD_GENERATE	Generators emit typed AST contributions (incremental by default)	Generation replay boundaries
semantic.snapshot	SEMANTIC_SNAPSHOT	After semantic rules complete for merged host+generated program	Analyzer read boundary
mod.analyze	MOD_ANALYZE	Analyzer contracts emit diagnostics and fixes	Analyzer cache boundaries
mod.rewrite	MOD_REWRITE	Rewriter contracts apply typed node replacements	Rewrite replay boundaries
lower.ready	LOWER_READY	Immediately before HIR lowering on a consistent merged program	Lowering safety boundary

Insertion order (host compilation with mods) — After parse, run mod.load (if needed), mod.collect, mod.generate, then re-parse when generation changed syntax, followed by semantic/semantic.snapshot, mod.analyze, optional mod.rewrite, and then lower/backend phases. Exact ordering is pinned in Stage ordering and lowering / design model.

Budgets (maxGeneratorRounds, step caps) and capability checks are specified in Mod host bridge; cache keys in Incremental scheduling and determinism.

Subtree summary

• 61 page(s) under this subtree
• 6 direct child path segment(s)

Child entries

• Analysis, query, and diagnostics facades
• Beskid.Compiler.SyntaxMirror facade
• Incremental scheduling and determinism
• Mod host bridge
• Syntax domain model generation
• Typed emitter and transforms

Relationship diagram

The embedded architecture graph summarizes how Mod manifests, Beskid SDK contracts, the Rust host bridge, and downstream pipelines connect.

Feature index

Use the tiles for normative feature contracts (status + owner metadata on each hub).

Features

• Analysis, query, and diagnostics facadesSemantic queries, symbol handles, and diagnostic transport available inside meta execution.
• Beskid.Compiler.SyntaxMirror facadeTyped, allocation-bounded syntax node API exposed to compile-time Beskid modules.
• Incremental scheduling and determinismCache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads.
• Mod host bridgeReference compiler-owned execution, capability policy, and communication with compile-time Beskid modules.
• Syntax domain model generationContract for generating the immutable SyntaxMirror domain model consumed by Compiler Mod SDK facades.
• Typed emitter and transformsConstruction of syntax nodes and declarative transforms without raw text printing.