# Nexus Language Core Specification 1.0

## Status

This document freezes the syntax and semantics implemented by the Nexus 1.0 bootstrap toolchain. It is a **core-language stability point**, not a claim that every long-term Nexus feature is complete.

## Source and modules

- Nexus source files use `.nx`.
- A file may declare `module Name;`.
- `import Name;` resolves a sibling `Name.nx` and is recursively merged by the bootstrap compiler.

## Primitive types

`i32`, `i64`, `u32`, `u64`, `f32`, `f64`, `bool`, `str`, and `void` for function returns.

## Bindings

- `let` creates an immutable binding.
- `var` creates a mutable binding.
- Local type inference is supported when the annotation is omitted.
- `move name` transfers a local binding. Reading the source after a move is a compile-time error until a mutable source is explicitly reinitialized.

## Data model

- `struct` with named fields.
- field access with `value.field`.
- simple enums.
- exhaustive enum `match` with optional `else`.
- fixed local arrays inferred from literals.
- checked indexing: literal out-of-bounds indices are compile-time errors; dynamic indices receive a runtime bounds check in the hosted backend.

## Functions

- typed parameters and return values.
- `pure fn` enforces an empty effect set.
- functions may declare `effects(io, panic, unsafe, task, ...)`.
- an explicitly effect-restricted function cannot silently call operations outside its contract.

## Control flow

`if`/`else`, `while`, integer range `for name in start..end`, `break`, `continue`, and `return`.

## Safety boundary

- `unsafe { ... }` marks operations that intentionally cross the safe-language boundary.
- `addr(local)` is gated behind both an unsafe block and the `unsafe` effect where an explicit effect contract is present.
- `move` validation prevents use-after-move in the 1.0 local ownership model.

## Structured tasks

- `spawn worker();` starts a no-argument `void` function on a native hosted thread.
- `sync;` joins outstanding tasks.
- outstanding tasks are automatically joined before a function returns.
- task creation requires the `task` effect in an explicit effect contract.

## Builtins

- `print(value)` — hosted output, `io` effect.
- `len(str_or_array)`.
- `assert(condition, optional_message)` — `panic` effect.
- `addr(local)` — unsafe low-level address operation.

## Compiler representations

The compiler exposes:

- source AST
- NIR-1 typed structural intermediate representation
- C17 bootstrap backend
- direct x86-64 assembly backend for the freestanding Frames profile

## Frames executable profile

`--target frames-x64` produces a PE32+ native-subsystem executable with a `.nxmeta` section identifying Frames ABI v1. The direct backend does not depend on the Windows CRT or Win32 APIs.

## Explicitly outside the 1.0 core

Generics, traits, borrowing/lifetime syntax, payload enums, async/await, a remote package registry, self-hosting, ARM64, WebAssembly, macOS output, and the finalized Frames kernel/syscall/UI APIs are not part of the implemented 1.0 core and remain future work.