grammar-contract

name	grammar-contract
description	How the .uetkx grammar stays byte-compatible with the family (.uitkx Unity — the origin; .guitkx Godot) and how the two in-repo implementations (C++ compiler, TS language server) stay in lockstep — corpus cases, goldens, the .pending divergence protocol, and cross-repo sync. Use for ANY lexer/parser/formatter change, and at release time for the sibling drift check.

Grammar contract

Two invariants, one mechanism.

Invariant 1 — in-repo lockstep: the C++ compiler is the grammar of record; the TS language server reproduces it, never the reverse. Both run the SAME corpus.

Invariant 2 — family byte-compat (D-22e, ES-modules revision): markup structure, the import/ export SURFACE (named / rename-as / * as / default imports, export { … }; lists, export default), directives, and reserved props parse identically across Unity, Godot, and this repo. Declaration kinds (component / hook / value / util) are classified from the SIGNATURE alone (G-03) — uniform CONCEPTS, but each engine spells declarations in its own native idiom (C# / GDScript / C++), so the new decl HEAD grammar lives in the per-leg corpus tier, not familyCore. The legacy component/hook/module wrappers parse family-wide for one deprecation minor (2320). Only the embedded-language LEXIS differs per host — corpus cases pin BEHAVIOR, not code.

The rule for every grammar-touching change

A lexer/parser/formatter change lands WITH its corpus case(s) in the same commit — no exceptions, including "behavior-preserving" perf work (a contract diff during such a change is by definition a bug in the change).

• Scanner cases: ide-extensions/lsp-server/test-fixtures/uetkx-scanner-cases.json — { "input": …, "at": …, "expect": … } per section (skipNoncode / findMatching / markup variants). Offsets are Unicode CODE POINTS (D-18) — the TS side converts from UTF-16 (codePoints.ts), the C++ side from UTF-8; include non-BMP (surrogate-pair) cases whenever touching offset logic.
• Formatter goldens: uetkx-formatter-cases.json — pins the formatter byte-identical on both sides; invariants: verbatim-on-parse-error, idempotent, fellBack distinguishable.
• Full-file fixtures + goldens (Phase 3+): fixtures under Source/RuiHostTests/ContractFixtures/ (EXCLUDED from the RUICompile sweep and UBT); goldens dumped by -run=RUIContractDump; --check is the CI drift mode; the TS side replays every golden.
• Both sides run in CI: the C++ side via ReactiveUI.Contract, the TS side via node --test in lsp-server.

The .pending protocol (known divergences)

A divergence you can't fix now gets pinned, not ignored: rename the fixture <name>.pending.uetkx; the test asserts the divergence STILL EXISTS (so fixing it forces the rename+regen and the books stay honest). A .pending never ships past a release without an owner decision.

Cross-repo sync (all three siblings)

• Outbound (this repo changed the shared grammar): land the corpus case here; open the mirrored corpus PR against the Godot repo (and flag the Unity repo) — track in plans/TECH_DEBT.md until both merge. A grammar change is not "done" while a sibling's corpus lacks its case.
• Inbound (a sibling released a grammar change — they demonstrably still do): import their new cases, run both in-repo implementations, reconcile or .pending-pin.
• Release-time drift check (release-process §3): hash-compare the shared corpus sections against ReactiveUI-Gadot/ide-extensions/lsp-server/test-fixtures/scanner-cases.json (and the Unity repo's corpus). Host-lexis-specific sections are exempt; structural sections must match.
• The vendored lsp-server's family-shared files (markup.ts, sourceMap.ts, formatter, corpora) sync by the same procedure (D-30): diff against the sibling's copy, port deliberately, never let them drift silently.

Scar tissue (why these steps exist)

• The corpus is why two implementations in two languages stayed byte-identical in production in the Godot repo (GDScript compiler ↔ TS server) — three implementations without it would already have diverged.
• Code points, explicitly: the sibling repo retrofitted codePoints.ts after UTF-16 vs code-point offsets silently mismatched on astral characters — here the unit is pinned in the spec and the corpus carries non-BMP cases from day one.
• .pending exists because "we'll fix that divergence later" with no tripwire became permanent in early family history; a pinned divergence that BLOCKS fixing silently is one you'll actually fix.