Language Specification

The full source of the specification is at github.com/nv-lang/nova/tree/main/spec. Below is the section overview with direct links.

Sections

• §1

  Introduction & Design Goals

  Motivation for Nova, comparison with related languages, and the core design philosophy: explicit effects, machine-checkable contracts, no hidden control flow.

  View on GitHub →
• §2

  Lexical Structure

  Source encoding (UTF-8), tokens, keywords, operators, string literals (raw, interpolated, byte), numeric literals, and comments.

  View on GitHub →
• §3

  Types

  Primitive types, structs, enums (sum types), tuples, arrays, slices, function types, generic parameters, trait bounds, and the Option[T] and Result[T, E] built-ins. Nominal vs. structural typing rules.

  View on GitHub →
• §4

  Effects

  The algebraic effect system: built-in effects, user-defined effect interfaces, effect handlers, effect polymorphism, and the uses clause in function signatures. Effect inference and checking rules.

  View on GitHub →
• §5

  Contracts

  requires, ensures, and invariant clauses: syntax, semantics, and the three checking modes (static via SMT, dynamic runtime assertion, erased). Contract inheritance, specialization, and the interaction with generics.

  View on GitHub →
• §6

  Expressions & Statements

  Operator precedence, pattern matching, if/else/when, loops, let bindings, closures, try operator ?, and expression-based control flow.

  View on GitHub →
• §7

  Functions & Methods

  Function declarations, associated functions (methods), trait implementations, overloading rules, variadic functions, and inline/extern annotations.

  View on GitHub →
• §8

  Modules & Packages

  Module system, visibility (pub, pub(pkg), private), the use import declaration, package layout conventions, and the nv package manager manifest format.

  View on GitHub →
• §9

  Concurrency & Runtime

  The M:N fiber model, the work-stealing scheduler, spawn, channels, structured concurrency scopes, and the realtime nogc annotation. Fiber lifecycle and cancellation.

  View on GitHub →
• §10

  Memory Model

  Managed memory, GC interface, realtime nogc regions, stack-only types, and the rules for sharing data across fibers. Eventual path to ownership-based memory management.

  View on GitHub →
• §11

  Error Handling

  Result[T, E] as the primary error mechanism, the ? propagation operator, error coercion via the From trait, panic semantics, and the distinction between recoverable and unrecoverable errors.

  View on GitHub →
• §12

  FFI & Interoperability

  Calling C from Nova (extern "C"), calling Nova from C, ABI stability, unsafe blocks, and the @repr layout annotations.

  View on GitHub →
• §13

  Grammar

  Complete EBNF grammar for the Nova language, machine-readable and used to generate the parser. Updated automatically on each language change.

  View on GitHub →

---

Design Decisions (D-blocks)

Every non-trivial language design choice is captured in a numbered D-block document in spec/. D-blocks record the question, the options considered, the decision made, and the rationale. This makes the spec a readable history of the language, not just a reference.

Current D-block range: D1–D120. Selected highlights:

• D1 — Why algebraic effects instead of monads or async/await
• D7 — Contract checking modes and SMT solver integration
• D15 — M:N runtime vs. async executor vs. OS threads
• D33 — Contract inheritance and trait specialization rules
• D45 — Documentation tooling and nv doc format
• D52 — Redundant field specification in struct literals
• D63 — Package manager manifest schema

Browse all D-blocks on GitHub →