================================================================================
=== SECTION: 01_core_syntax.md
================================================================================

<nitpick-spec category="core-syntax">
<functions>
All functions return `Result<T>` implicitly unless `extern` or entrypoint.
Valid signatures:
`func:name = ReturnType(ArgType:argName)`
`pub func:name = ReturnType(ArgType:argName)`
`async func:name = ReturnType(...)`
`extern func:name = ReturnType(...)`
Use `pass(val);` or `fail(code);` to return.
Use `..*` for variadics: `func:log = void(string:fmt, ..*string[]:args)`
</functions>
<entrypoints>
Mandatory entrypoints. Do NOT return `Result`. DO NOT use `pass/fail`. MUST call `exit(N);`
`pub func:main = int32()` or `pub func:main = int32(int32:argc, int8[]->:argv)`
`pub func:failsafe = int32(tbb32:err)`
</entrypoints>
<control-flow>
NO semicolons after block braces (`}`, `if/while/pick`).
- **if/else**: `if (cond) { } else if (cond2) { } else { }`
- **while**: `while (cond) { }`
- **when/then/end**: `when (x > 0) { x-=1; } then { /* completed normally */ } end { /* exited early/break */ }`
- **loop**: `loop(start, limit, step) { print($); /* $ is iterator */ }`
- **till**: `till(limit, step) { print($); }`
- **pick (match)**: `pick (val) { (0) { }, label: (1) { fall next_label; }, next_label: (2) { }, (*) { /* default */ } }`
- **pick guards**: `pick (ast) { Macro!(a) where (a > 5) { } }`
</control-flow>
<operators>
- **Safe Unwrap `?`**: `val = fn() ? default;` (returns default if error)
- **Emphatic Unwrap `?!`**: `val = fn() ?! 5;` (calls failsafe(5) if error)
- **Null Coalesce `??`**: `val = ptr ?? fallback;`
- **Ternary `is`**: `int:x = is (a > b) : a : b;`
</operators>
<discard>
Use to ignore unused values/params: `discard(expr);` or `_~ expr;`
</discard>
</nitpick-spec>


================================================================================
=== SECTION: 02_type_system.md
================================================================================

<nitpick-spec category="type-system">
<primitives>
- **Integers**: `int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, `uint64`. (No implicit casting)
- **Floats**: `flt32`, `flt64`.
- **Booleans**: `bool` (`true`, `false`).
- **Strings**: `string` (UTF-8, immutable, dynamic).
- **Special**: `tbb32` ([-2147483647, +2147483647] with ERR sentinel), `any`, `void`.
</primitives>
<collections>
- **Arrays**: `int32[]:arr = [1,2,3];` (dynamic). `fixed [3]int32:arr = [1,2,3];` (static).
- **Tuples**: `(int32, string):t = (1, "a");`
</collections>
<structs>
Use `struct:` for data structures.
```nitpick
struct:Point { int32:x; int32:y; }
```
</structs>
<enums>
Support basic and tagged enums.
```nitpick
enum:Status { OK, ERROR }
enum:Event { Click(int32:x, int32:y), Key(string:code) }
```
</enums>
<casting>
Casting must be explicit.
- **Checked (warnings on loss)**: `a => int32` or `@cast<int32>(a)`
- **Unchecked (suppresses warnings)**: `@cast_unchecked<int32>(a)`
</casting>
<traits>
Interfaces for polymorphism.
```nitpick
trait:Display { func:show = void(); }
impl Display for Point { func:show = void() { /* ... */ }; }
```
</traits>
</nitpick-spec>


================================================================================
=== SECTION: 03_memory_and_safety.md
================================================================================

<nitpick-spec category="memory-and-safety">
<pointers>
Pointers are explicitly typed. 
- Struct pointer: `MyStruct->`
- Raw type pointer: `int32->`
Cannot cast integers directly to pointers via `@cast` (must use FFI or `int64` logic).
</pointers>
<allocation>
Nitpick has manual memory management and specialized allocators.
- **Heap Allocation**: `dalloc(size)`
- **Arenas**: `arena<T>->:a = alloc(1024i64) => arena<T>->;`
- **Handles**: `Handle<T>`. Contains `.index` (uint64) and `.generation` (uint32).
</allocation>
<safety-tos>
Nitpick prevents undefined behavior by default. You can bypass safety using explicitly marked "Terms of Service" (TOS) keywords which contain `!`, `raw`, `drop`, or `wild`.
- **raw**: Unwraps `Result<T>` bypassing error checking.
- **drop**: Runs function but discards `Result<T>`.
- **wild / wildx**: Blocks for unsafe memory manipulation and raw pointer arithmetic.
- **! operators**: `?!` (crash on err).
</safety-tos>
</nitpick-spec>


================================================================================
=== SECTION: 04_concurrency.md
================================================================================

<nitpick-spec category="concurrency">
<async-await>
Nitpick handles I/O bound concurrency via cooperative multitasking.
- Mark functions with `async`.
- Await them using `await`.
- Must handle the implicit `Result` wrapper of the async function: `raw await func()` or `val = await func() ? default;`
- `await` cannot be used inside standard synchronous functions.
</async-await>
<atomics>
CPU-bound parallelism via lock-free primitives. `atomic<T>` is a native LLVM-backed type.
- **Initialization**: `atomic<int32>:c = atomic_new(0i32);`
- **Aliasing**: `atomic_from_ptr<int32>(addr_int64)` aliases memory as atomic without allocation.
- **Operations**: `.load()`, `.store(v)`, `.swap(v)`, `.fetch_add(v)`, `.fetch_sub(v)`, `.compare_exchange(exp, des)`.
- **Memory Ordering**: Operations strictly enforce Sequential Consistency (SeqCst). No relaxed orderings permitted in standard code.
</atomics>
<threading>
No native `spawn` or `sync` keywords. Threading (mutexes, rwlocks) must be managed via `stdlib/concurrent` utilizing OS abstractions.
</threading>
</nitpick-spec>