# Sanskrit Next (संस्कृत) Full Language Reference & Technical Specification

Version: 2.0.0
Author: Shaswat Raj (https://github.com/playlikeboy)
Repository: https://github.com/playlikeboy/sanskrit
Documentation: https://playlikeboy.github.io/sanskrit/

---

## 1. Overview & Architectural Principles

Sanskrit Next is a research-grade systems programming language engineered in native Rust.
It combines classical Paninian linguistic precision with modern compiler infrastructure (Tier-0 Bytecode VM, MLIR dialect pipeline, LLVM/IREE code generation).

### Empirical Performance Metrics (Apple Silicon M-series, aarch64-apple-darwin):
- Cold Boot Startup: 1.84 ms (Tier-0 Bytecode VM).
- Resident Memory Overhead: 3.1 MB under active program execution.
- Standalone Binary: 4.2 MB static executable (0 runtime dependencies).
- Automatic Differentiation: 4.09 ms for 100,000 forward-mode evaluations (~24.4 million evals/sec).
- Inner Loop Overhead: 0.0005 ms (<1 µs) for microbenchmark iterations.
- Zero-Copy Streaming Lexer: >140 MB/s throughput (~1.8 million tokens/sec).
- Bi-directional Dual-Script Parity: 100.0% AST/ABI equivalence across Devanagari and Latin.

---

## 2. Dual-Script Grammar & Keywords

| Devanagari Canonical | Latin ASCII Alias | Concept | Syntax Example |
| :--- | :--- | :--- | :--- |
| कार्य | fn | Function declaration | कार्य मुख्य(): / fn main(): |
| मान | let | Variable binding | मान x = 10 / let x = 10 |
| स्थिर | const | Constant binding | स्थिर PI = 3.14 / const PI = 3.14 |
| यदि | if | Conditional branch | यदि cond: / if cond: |
| अन्यथा | else | Else branch | अन्यथा: / else: |
| यावत् | while | While loop | यावत् cond: / while cond: |
| प्रत्येक | for | For loop | प्रत्येक x मध्ये arr: |
| प्रत्यागम | return | Function return | प्रत्यागम val / return val |
| प्रकार / संरचना | struct | Record structure | प्रकार Point { x: f64, y: f64 } |
| गुण | trait | Interface contract | गुण Printable { ... } |
| प्रयोजयतु | impl | Implementation | प्रयोजयतु Printable कृते Point |
| आयात | import | Module import | आयात std.tensor / import std.tensor |
| निर्यातः | export | Module export | निर्यातः कार्य func(): |
| अतुल्यकालिक | async | Async coroutine | अतुल्यकालिक कार्य task(): |
| प्रतीक्षते | await | Await expression | प्रतीक्षते task() |
| आत्मा | self | Receiver instance | आत्मा.field / self.field |

---

## 3. Type System

### Primitives
- पूर्णाङ्क / i32: 32-bit signed two's complement integer
- दशमलव / f64: 64-bit IEEE-754 double precision float
- f32: 32-bit single precision float
- तर्क / bool: Boolean logical truth value (सत्यम् / true, असत्यम् / false)
- सूत्र / str: UTF-8 validated immutable zero-copy string slice
- अक्षर / char: 4-byte Unicode scalar value
- शून्यम् / void: Unit / void return type

### Scientific & Tensor Types
- दिश[dtype, shape] / Tensor[dtype, shape]: First-class strided tensor
  - Allocators: दिश.zeros([M, N]), दिश.ones([M, N]), दिश.randn([M, N]), दिश.eye(N)
  - Properties: .shape, .strides, .dtype
  - Operations: @ (cache-blocked GEMM), .transpose(), .reshape([new_shape]), .sum(), .mean()
- Dual(primal, tangent): Forward-mode automatic differentiation dual number
- अवकलन(f, x) / diff(f, x): Scalar first derivative
- प्रवणता(f, x) / grad(f, x): Vector gradient

---

## 4. Standard Library (std)

### std.core
- मुद्रण(...args) / print(...args): Prints formatted values to stdout
- विफल(सन्देश: सूत्र) / panic(msg: str): Diagnostic runtime panic
- निश्चय(शर्त: तर्क, सन्देश: सूत्र) / assert(cond: bool, msg: str): Assertion guard

### std.tensor & std.linalg
High-performance matrix calculus, vector math, and tensor layout views.

### std.autodiff
Forward-mode automatic differentiation engine.

---

## 5. Toolchain CLI Commands

- `sanskrit run <file.skt>`: Run script instantly via Tier-0 Bytecode VM (<2ms)
- `sanskrit run --release <file.skt>`: Run with MLIR/LLVM optimization passes
- `sanskrit build <file.skt>`: Compile to standalone binary executable
- `sanskrit build --emit-mlir <file.skt>`: Lower to MLIR dialect representation
- `sanskrit check <file.skt>`: Run type checker and diagnostics
- `sanskrit test`: Run test suites (**/*.test.skt)
- `sanskrit bench`: Run performance benchmarks
- `sanskrit repl`: Launch interactive REPL
- `sanskrit fmt`: Format Sanskrit source code
- `sanskrit doctor`: Inspect GPU, toolchain, and cache health
- `sanskrit env --json`: Output environment telemetry in JSON
- `sanskrit lsp`: Start Language Server Protocol daemon