Skip to content
Sigil KB

Design Synthesis R1–R18

Status: stub

Full Design Synthesis documentation is planned for Phase 2. This stub covers the purpose and structure of R1–R18.

Spec source: SYNTHESIS_V2.csl

What the Design Synthesis is

Section titled “What the Design Synthesis is”

The Design Synthesis (spec file: SYNTHESIS_V2.csl) is a document inside the compiler repo that records the rationale for every major architectural decision in Sigil. It is not documentation of what the compiler does — it is documentation of why it does it.

R1–R18 are the eighteen design rationales. They cover:

  • Why the effect system uses row polymorphism instead of a simpler model (R3)
  • Why the compiler targets Cranelift instead of building an LLVM backend (R6)
  • Why autodiff is a compiler transformation rather than a library (R8)
  • Why the capability system uses linear types for certain resources (R11)
  • Why SMT verification is compile-time only, not runtime-optional (R14)

Who should read this

Section titled “Who should read this”

The Design Synthesis is primarily for:

  1. Compiler contributors — understanding the rationale prevents you from accidentally “fixing” something that was designed intentionally
  2. Language implementors — if you’re building a tool, dialect, or alternative backend, the rationales explain which constraints are load-bearing

Language users don’t need to read R1–R18 to write Sigil programs. But reading it will give you a much clearer mental model of why the language behaves the way it does.

Coming in Phase 2

Section titled “Coming in Phase 2”

The full R1–R18 exposition, with cross-references to the relevant spec files and KB articles.

See also

Section titled “See also”