Sibling articles under this feature previously restated requirements in inconsistent forms.
Syntax domain model generation - Design model
Platform spec article
Syntax domain model generation - Design model
Spec standingStandard
-
This feature hub owns normative MUST/SHOULD contract text for Syntax domain model generation.
Context
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/compiler-mods/syntax-domain-model-generation/index.mdxarticle bundle under the same feature directory.
-
Platform-spec text supersedes informal crate comments for Syntax domain model generation.
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/src/syntax/compiler/crates/beskid_analysis/src/beskid.pestcompiler/crates/beskid_analysis/src/syntax/items/
-
Hand-maintained parallel syntax trees diverged from the host parser.
Context
Hand-maintained parallel syntax trees diverged from the host parser.
Decision
Canonical syntax model is generated via
beskid_ast_reflect_genintoBeskid.Compiler.*SDK sources from the Rust AST—aligned with D-INC-0006.Consequences
Mods consume generated facades; internal
beskid_analysis::syntaxremains host-only.Verification anchors
beskid_ast_reflect_gencompiler/crates/beskid_analysis/src/syntax/.
- Syntax domain model generation - Contracts and edge cases Contract for generating the immutable Beskid syntax domain model consumed by Mod SDK facades and meta discovery.
- Syntax domain model generation - Design model Contract for generating the immutable SyntaxMirror domain model consumed by Compiler Mod SDK facades.
- Syntax domain model generation - Examples Contract for generating the immutable Beskid syntax domain model consumed by Mod SDK facades and meta discovery.
- Syntax domain model generation - FAQ and troubleshooting Contract for generating the immutable Beskid syntax domain model consumed by Mod SDK facades and meta discovery.
- Syntax domain model generation - Flow and algorithm Contract for generating the immutable Beskid syntax domain model consumed by Mod SDK facades and meta discovery.
- Syntax domain model generation - Verification and traceability Contract for generating the immutable Beskid syntax domain model consumed by Mod SDK facades and meta discovery.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).
This article documents the design model for SyntaxMirror domain model generation.
Language alignment
Section titled “Language alignment”Collector predicates compile to keys over syntax identities from this model. The host regenerates or diffs snapshots so Generator and Rewriter never observe torn trees.
Persistent entities
Section titled “Persistent entities”- Compilation instance — active host compilation under transformation.
- Syntax snapshot — immutable tree with stable node identities for incremental keys.
- SyntaxMirror projection — Beskid-facing typed mirror of syntax nodes with query/AST operation contracts.
Boundaries
Section titled “Boundaries”- Rust AST in
beskid_analysisis authoritative; SyntaxMirror is generated/mirrored for mod packages. - Legacy
MetaDefinitionnodes are removed from the mirror inventory. - The Rust inner item enum (
syntax::Node) is host-only and is not emitted into the Mod SDK. Mod packages seeNodecontract +NodeRefinstead.
Generated artifacts
Section titled “Generated artifacts”beskid_ast_reflect_gen emits, under Beskid.Syntax.Nodes:
| Artifact | Role |
|---|---|
Per-type shape .bd | Struct/enum mirrors for typed emit and rewrite (FunctionDefinition, …) |
Node.bd | pub contract Node — kind, ref, child push |
NodeRef.bd | Opaque stable handle |
NodeSpan.bd | Span DTO for one node in one generation |
NodeKind.bd | Classification tokens (mirrors query::NodeKind) |
NodeList.bd | Vec<Node> as cons-list of NodeRef |
TraversalManifest.bd | Child-slot table derived from Rust #[ast(child|children|skip)] |
Traversal metadata must stay aligned with beskid_ast_derive::AstNode wiring in beskid_analysis.
Stable identities
Section titled “Stable identities”Each node must have a stable identity within a syntax_generation_id window. Identities must survive trivia-only edits where language law marks them stable and must change on structural edits that affect collection predicates.
Torn tree prohibition — Hosts must not expose partial syntax trees to mod contracts. Parse failures abort the current generation round with diagnostics, leaving the previous committed generation untouched.
Multi-root workspaces — Identities must be qualified by normalized root path + in-root span so different projects cannot collide in caches.
Transformation model
Section titled “Transformation model”- Query-pipeline transforms run against one immutable
SyntaxSnapshotgeneration and produce one new committed generation on success. - Pipeline application must be transactional: validation completes before any mutation becomes visible to mod code.
- Span propagation is explicit:
- untouched nodes preserve original spans;
- replaced nodes receive source spans from replacement payloads when available;
- synthetic nodes may use host-synthetic spans but must remain diagnosable.