Quick Orientation

This page is a map. It tells you what concepts are load-bearing in Sigil, what order to encounter them in, and where to find them in this KB.

The six non-negotiables

These six properties are invariants of the language, not configuration options. Every other design decision defers to them.

F1 — GPU/CPU distinction is a type-level fact

Code that runs on the GPU has a different type than code that runs on the CPU. Cross-boundary calls are a compile error, not undefined behavior.

F2 — Effect system is non-optional

Every function’s effects are part of its type. The effect row is inferred automatically; you cannot opt out of effect tracking.

F3 — Autodiff is compiler-native

The ∂ differentiation operator is a first-class language construct, not a library. Gradient computation is a compile-time transformation.

F4 — Coordinate spaces are distinct types

Vec3<World>, Vec3<View>, Vec3<Clip> are incompatible types. No implicit coercion. Coordinate-space confusion is a compile error.

F5 — Verification is zero-cost at runtime

SMT-checked invariants are verified at compile time. No runtime overhead unless you explicitly add runtime assertions.

F6 — No LLVM dependency

The backend is Cranelift. The compiler is self-contained, fast to build, and safe to embed in JIT-heavy tools.

Key concepts to understand before reading further

Effect rows

An effect row is the set of effects a function is allowed to perform. Common effects:

Effect	Meaning
!pure	No effects — safe to inline, reorder, memoize
!io	Touches I/O: filesystem, network, window, stdout
!gpu	GPU-resident — cannot be called from CPU context
!alloc	Performs heap allocation
!mut	Mutates state visible outside the function

A function with no effect annotation is inferred. The compiler propagates effects up the call graph automatically. You only need to annotate when you want to enforce a constraint (e.g., “this function must be pure”).

Phantom types

A phantom type is a type parameter that carries no runtime data. Sigil uses phantom types extensively for:

• Coordinate spaces: Vec3<World>, Vec3<Clip>, Vec3<Screen>
• Unit systems: f32<Meters>, f32<Pixels>
• Ownership contexts: Buffer<T> (GPU-owned) vs. Vec<T> (CPU-owned)

The phantom parameter is erased at codegen — there’s no runtime cost. It exists only for the type checker.

The IR pipeline

Sigil’s compiler has several intermediate representations:

Source (.cssl)
  ↓ Parser
AST
  ↓ Type checker (effects, phantoms, capabilities)
HAIR (High-level, annotated IR)
  ↓ Effect elaboration
  ↓ Autodiff transform (if ∂ used)
  ↓ Staging evaluation (if staging used)
MIR (Mid-level IR)
  ↓ Cranelift (CPU) / SPIR-V emit (GPU)
Native binary + SPIR-V modules

You don’t interact with the IR pipeline directly as a language user, but understanding that it exists explains why certain errors appear at specific compilation stages.

CSLv3 vs. Sigil

You will see blocks labeled “Spec source” throughout this KB. They contain text in CSLv3 notation — a dense formal notation used in the compiler’s internal specs. CSLv3 is:

• Not a programming language
• Not compiled to machine code
• Not what you write your programs in

CSLv3 is how the compiler’s behavior is specified. Think of it as the compiler’s spec language, like TLA+ or Alloy, but designed for describing type systems and effect semantics. If you’re a language user, you can ignore spec blocks. If you’re a contributor or implementor, they are the authoritative reference.

Reading guide

If you want to use Sigil

Follow the Newcomer path on the Learning Paths page. Focus on §A and §B. You can skip §C–§F entirely until you need a specific feature.

If you want to contribute to the compiler

Read §A and §B first. Then read §E.1 Design Synthesis — it contains R1–R18, the eighteen design rationales that explain why the compiler’s architecture is the way it is. Then read the spec source blocks in §B and §C carefully — those are the normative reference.

If you’re implementing a backend or dialect

Start with §E.1 (Design Synthesis), then §B.2 (Types) and §B.3 (Effects), which define the core invariants your implementation must preserve. Then move to §F Compiler Architecture (arriving in Phase 3 of this KB).

If you want to understand the autodiff system

Read §B.2 (Types) → §B.3 (Effects) → §C.1 Autodiff → §C.2 Jets. Autodiff in Sigil is not a library bolted on — it is a transformation over the HAIR that requires understanding the effect and type systems to use correctly.

What’s missing from this KB

This is Phase 1. The following will be added:

• §F Compiler Architecture — full IR pipeline docs, MLIR dialect, bootstrapping (Phase 3)
• §G Observability & Testing — telemetry and test harness (Phase 3)
• §H Architecture Decisions — sanitized DECISIONS.md (Phase 3)
• Spec export pipeline — auto-exported spec blocks from the compiler repo’s CI (Phase 3)

If you need something that’s missing, the compiler repo’s specs/ directory is the canonical reference.

Where to go from here

You’ve now read the orientation. The suggested next step depends on your goal:

• Using Sigil → §B.1 Surface Syntax
• Understanding the design → §E.1 Design Synthesis
• Seeing a real program → §I.1 Hello Triangle walkthrough