Beskid Tracker

import SpecPageHeader from '@beskid/beskid-ui/platform-spec/SpecPageHeader.astro'; import SpecSection from '@beskid/beskid-ui/platform-spec/SpecSection.astro'; import DomainTiles from '@beskid/beskid-ui/platform-spec/DomainTiles.astro'; import DomainOrAreaHub from '@beskid/beskid-ui/platform-spec/DomainOrAreaHub.astro';

<SpecSection title="Canonical ownership" id="ownership"> This **compiler** area defines the Rust-side behavior for compiler mods. **[Project manifest contract](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/)** defines the **`Mod` project type** and package metadata. **[Compiler Mod SDK](/platform-spec/language-meta/metaprogramming/compiler-mod-sdk/)** defines Beskid-side contracts; this area defines discovery, AOT artifact lifecycle, execution phases, typed merge semantics, diagnostics transport, and incremental invalidation. </SpecSection> <SpecSection title="Scope" id="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. </SpecSection>

<SpecSection title="Compiler mods (concept)" id="compiler-mods"> **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. </SpecSection> <SpecSection title="Mod API shape (modules)" id="mod-api-shape"> 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. </SpecSection>

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. </SpecSection>

<DomainOrAreaHub pathPrefix="platform-spec/compiler/compiler-mods" summaryTitle="Subtree summary" /> <SpecSection title="Relationship diagram" id="architecture"> The embedded architecture graph summarizes how `Mod` manifests, Beskid SDK contracts, the Rust host bridge, and downstream pipelines connect. </SpecSection> <SpecSection title="Feature index" id="feature-index"> Use the tiles for normative **feature** contracts (`status` + owner metadata on each hub). </SpecSection> <DomainTiles pathPrefix="platform-spec/compiler/compiler-mods" heading="Features" />