🔷 Zafira Programming Language

"Rigid, crystal-clear, unbreakable — as flawless as a sapphire"
Silicon-Native | Dual-Mode (Draft & Seal) | AI-First & Python-Interop Programming Language

🇬🇧 English | 🇺🇿 O'zbekcha versiya

---

📖 What is Zafira and Why Does It Exist?

Zafira is a modern Silicon-Native & Dual-Mode programming language designed specifically for the generative AI era. It communicates directly with silicon hardware (CPU, GPU, NPU) at the language grammar level while bridging high developer ergonomics with C/Rust-grade performance.

Historically, software engineers have been forced to make a painful compromise:

• Choose Python for its expressiveness, rapid iteration, and unmatched AI ecosystem — at the cost of slow single-threaded execution, memory bloat, and runtime type fragility.
• Choose C++ or Rust for bare-metal speed and type safety — at the cost of steep learning curves, verbose syntax, and long compile times.

Zafira eliminates this tradeoff through its Dual-Mode Execution Architecture:

1. draft Mode: Write freeform, dynamic code for ultra-fast prototyping without cumbersome boilerplate or strict annotations.
2. seal Mode: When preparing for production, seal functions with strict types and formal where invariants that are statically proven at compile-time before code ever runs.
3. Zero-Overhead Python Bridge: Seamlessly import any library in the Python universe (import py.torch, import py.pandas, import py.numpy) with zero FFI glue.

📚 Official Documentation & Flagship Projects:

• Complete Language Specification (SPECIFICATION.md)
• 1-Page High-Density Developer Cheatsheet (CHEATSHEET.md)
• 💎 SapphireKV — In-Memory Key-Value & Cache Engine (100% Zafira)
• Flagship Production Showcase (examples/v1_showcase.zf)

---

⚡ Language Comparison Matrix

---

📦 Features Matrix Across Releases

---

🚀 Quick Start (Up & Running in 60 Seconds)

Step 1: Clone the Repository

git clone https://github.com/salomh46-rgb/Zafira-.git
cd Zafira-

Step 2: Check Python Runtime

Zafira runs on Python 3.11+ (CPython or PyPy):

python --version

Step 3: Run the Flagship v1.0 Showcase

Execute the complete multi-module showcase exercising every single language capability:

py -3 -X utf8 zafira.py run examples/v1_showcase.zf

Step 4: Interactive REPL

Fire up the lightning-fast Zafira terminal REPL:

py -3 -X utf8 zafira.py repl

zf> let name = "World"
zf> "Hello, " + name + "!"
=> Hello, World!
zf> 2 ** 10
=> 1024

Step 5: Web Interactive Studio

Launch the dark-mode obsidian web studio directly in your browser:

py -3 -X utf8 zafira.py playground

---

💻 Code Examples & Syntax Tour

1. Variables, Constants, and Invariants

let balance = 1000.0             // Mutable variable
const MAX_RETRIES = 5           // Immutable constant (compile-time protected)

// Sealed function with static invariant guarantee:
seal fn calculate_commission(amount: Float, rate: Float) -> Float
    where amount > 0.0 and rate >= 0.0  // If violated, fails statically!
{
    return amount * rate
}

2. Structs and impl Methods (OOP)

struct User {
    id: String,
    username: String,
    score: Int
}

impl User {
    fn introduce(self) {
        return "User: " + self.username + " (Score: " + String(self.score) + ")"
    }

    fn add_score(self, points: Int) {
        self.score = self.score + points
        return self.score
    }
}

let user = User("uuid-123", "jasper", 100)
user.add_score(50)
print(user.introduce()) // "User: jasper (Score: 150)"

3. Pattern Matching (match =>)

let score = 85

let grade = match score {
    90..101 => "A+",
    80..90  => "A",
    70..80  => "B",
    60..70  => "C",
    _       => "F"
}

print("Final Grade: " + grade)

4. Async / Await Concurrency

async fn fetch_telemetry(sensor_id: Int) {
    // Simulates non-blocking network I/O
    return "Telemetry Data for Sensor #" + String(sensor_id)
}

// Kick off tasks concurrently across worker threads:
let t1 = fetch_telemetry(101)
let t2 = fetch_telemetry(102)

// Await values without blocking the event loop:
print(await t1)
print(await t2)

5. Silicon Directives (@gpu, @npu, @auto) & Tensors

import std.ai

run @auto {
    let v1 = ai.tensor([0.2, 0.4, 0.8, 1.0])
    let v2 = ai.tensor([0.2, 0.4, 0.8, 1.0])
    
    // Dot product on hardware tensor core:
    let similarity = ai.similarity(v1, v2)
    print("Cosine Similarity: " + String(similarity)) // 1.0
}

6. Full Exception Handling (try / catch / throw / finally)

try {
    let denominator = 0
    if denominator == 0 {
        throw "Division by zero intercepted!"
    }
} catch (error) {
    print("Caught safely: " + error)
} finally {
    print("Audit log closed.")
}

7. File System (std.fs) and Cryptography (std.crypto)

import std.fs
import std.crypto

let secret_token = crypto.uuid()
fs.write_text("token.txt", "TOKEN=" + secret_token)

if fs.exists("token.txt") {
    let content = fs.read_text("token.txt")
    print("Saved: " + content)
    fs.remove("token.txt")
}

8. Native C FFI (std.ffi)

Call functions directly from shared libraries (.dll, .so, .dylib) without writing C headers:

import std.ffi

let libc = ffi.load("libc")
let absolute_val = libc.call("abs", [-123], "int")
print("Absolute value from C: " + String(absolute_val)) // 123

---

🏛️ System Architecture

                      Zafira Source Code (.zf)
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │    Lexer / Scanner    │  ───► 50+ Tokens (UTF-8, Comments, Directives)
                     └───────────────────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │  Pratt AST Parser     │  ───► Abstract Syntax Tree (Precedence-aware)
                     └───────────────────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │  Static Type Checker  │  ───► Seal Verification & Where Proofs
                     │     (Seal Guard)      │       • Param/Return match & Invariants
                     └───────────────────────┘       • Const checks & Typo suggestions
                                 │
             ┌───────────────────┴───────────────────┐
             ▼                                       ▼
 ┌───────────────────────┐               ┌───────────────────────┐
 │ Tree-Walk Interpreter │               │   AOT / C Compiler    │
 │     (Draft Mode)      │               │      (Seal Mode)      │
 └───────────────────────┘               └───────────────────────┘
             │                                       │
             ▼                                       ▼
 ┌───────────────────────┐               ┌───────────────────────┐
 │ Python Interop Bridge │               │ Standalone Executable │
 │ (py.torch, py.pandas) │               │   (myapp.exe / ELF)   │
 └───────────────────────┘               └───────────────────────┘
             │                                       │
             └───────────────────┬───────────────────┘
                                 ▼
               ┌───────────────────────────────────┐
               │         Hardware Engines          │
               │   CPU Cores  │  GPU  │  NPU Core   │
               └───────────────────────────────────┘

---

🛠️ CLI Tooling & Package Manager (zpm)

Zafira includes a comprehensive developer toolchain right out of the box:

---

🧩 Visual Studio Code Extension

Official syntax highlighting, bracket matching, and code snippets are available for VS Code:

Installation:

1. Locate the package at vscode-zafira/zafira-lang-0.1.0.vsix.
2. In VS Code, press Ctrl + Shift + P -> "Extensions: Install from VSIX..."
3. Select zafira-lang-0.1.0.vsix and enjoy first-class .zf syntax highlighting!

For more details, see VS Code Extension Installation Guide.

---

🧪 Verification & Test Suite

The language engine enforces Zero-Regression Doubt-Driven Development. Every commit is backed by automated tests:

# Run the entire test suite (333 tests):
py -3 -m unittest discover tests

Output:

......................................................................................
Ran 333 tests in 59.812s
OK (100% Passing, 0 errors, 0 regressions)

---

🤝 Contributing

We welcome open-source contributions from developers worldwide!

1. Fork the repository on GitHub.
2. Create your feature branch:

   git checkout -b feature/cutting-edge-feature
   

3. Run the automated test suite to ensure 100% green compliance:

   py -3 -m unittest discover tests
   

4. Commit your changes:

   git commit -m "feat: added new silicon tensor operator"
   

5. Push to your branch and open a Pull Request (PR).

---

👥 Authors & Credits

• Jasper (Javohirbek Asqarov) — Founder, Language Philosophy, Architecture, and Lead Designer.
• Antigravity AI — Systems Engineering, Pratt AST Parsers, Type Checker Verification, and Compilers.

---

📄 License

Zafira is open-source software licensed under the MIT License.

_{Established in 2026 | Tashkent, Uzbekistan 🇺🇿}