Specification

This is the normative half of the docs. Where the Guide is a narrative tour, the Specification is the reference you reach for when you need the exact rule — the keyword table, the resolution precedence, the IL a construct lowers to, the diagnostic a mistake triggers. Terse and tabular by design; the prose lives in the Guide.

What is authoritative

The compiler is the language. E# compiles .es source directly to a CLR assembly (.es → Mono.Cecil → .dll) over one typed IR; the compiler owns the semantics, and every emitted assembly is required to pass ILVerify. Every claim here is demonstrable. The corpus is drawn from the language’s own test suite and samples — passing test cases, showcases, and integration tests (some sizeable, multi-file) — and each entry earns its place: it compiles cleanly (or, for the negative cases, is rejected with exactly its expected diagnostic) and either produces its asserted output or stands as a real, well-formed program. The Diagnostics catalog deep-links each error code to the negative examples that provoke it, so the corpus is browsable by diagnostic.

Casing

Casing is convention throughout. No rule below is enforced, and the compiler reads the same program whichever case a name is written in.

Kind	Casing
Types — struct, class, union, ref union, enum, static, delegate func	PascalCase
Interfaces	I-prefixed PascalCase (ISized)
Free functions	camelCase
Methods (a function with a receiver block) and static members	PascalCase, to match .NET
const	SCREAMING_SNAKE_CASE

Notation

Grammar is given in EBNF, in the style of the Go specification:

Production  = production_name "=" [ Expression ] "." .
Expression  = Term { "|" Term } .
Term        = Factor { Factor } .
Factor      = production_name | token | "(" Expression ")" | "[" Expression "]" | "{" Expression "}" .

[ x ] is optional, { x } is zero-or-more repetition, ( x ) groups, a | b alternates, "x" is a literal token, and a … b is a character range. Lower-case names are lexical (token) productions; upper-case names are syntactic. “It is an error if …” and “shall” introduce normative static-semantic rules, each cross-referenced to the diagnostic it raises.

Conformance

A conforming program is one the IL compiler accepts and whose emitted assembly passes ILVerify. A program that violates a static-semantic rule is ill-formed; the compiler shall reject it with the named diagnostic. Behaviour the compiler accepts but this document does not describe is unspecified.

The pages

Page	Covers
Lexical structure	encoding, comments, identifiers, keyword tables, operators, literals, string interpolation
Names & resolution	namespaces, using forms, the 3-tier resolution precedence, ambiguity, per-file scope
Programs & execution	compilation units → one assembly, the namespace/module host classes, the main entry point, initialization order
Type system	the kinds, value/reference semantics, the exact struct/class-promotion policy, equality, conversions
Generics	reification, arity keying, the open/closed distinction, the type-argument-inference algorithm, default(T)
Declarations	the grammar and static semantics of every declared entity; const, derive, attributes
Compile-time providers	derives, analyzers and templates as one provider model; acquisition, phases, the delimited-region grammar, determinism
Expressions · Statements	operator precedence, the expression grammar, the statement forms
Pattern matching	match — scrutinee typing, payload binding and case views, exhaustiveness, match-as-expression, lowering
Functions · Pointers & by-ref · Memory model	methods & receivers, lambdas, function pointers; *T, &, out; copy semantics, escape, evaluation order
Errors · Concurrency · Delegates & events	Result/?, await/spawn/chan/select, nominal delegates and events
CLR mapping	the full E# → IL lowering table, with the C# equivalent alongside
Numerics & performance	Debug/Release policy, array loops, Span safety, allocation diagnostics, explicit SIMD, floating-point semantics
Low-level & unmanaged	stack-allocated spans, span-returning lifetime rules, the unmanaged generic bound, byte-string literals
Grammar	the complete lexical + syntactic grammar in one EBNF reference
Diagnostics	every ES#### code — trigger, fix, and the corpus examples that demonstrate it
Limitations & roadmap	what E# does not yet do, with workarounds, and the design in flight

Status

E# is pre-alpha: no packaged editor extension, type inference limited to generic-argument inference at call sites (no local := inference yet), a young .esproj build. The language is real and tested, but the surface still moves. Where a feature is absent or a C# convenience is missing, the relevant page says so plainly rather than dressing the gap as a design statement — see Limitations & roadmap.