Syntax domain model generation - Design model

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

<SpecArticleChrome />

This article documents the design model for SyntaxMirror domain model generation.

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

• 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

• Rust AST in beskid_analysis is authoritative; SyntaxMirror is generated/mirrored for mod packages.
• Legacy MetaDefinition nodes 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 see Node contract + NodeRef instead.

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

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

• Query-pipeline transforms run against one immutable SyntaxSnapshot generation 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.