Metadata-Version: 2.1
Name: zero-b
Version: 1.3.0
Summary: Zero B: High-Performance Bare-Metal Language, Std Library & Native Toolchain
Home-page: UNKNOWN
Author: Zero B Team
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Zero B: High-Performance Bare-Metal Programming Language & Toolchain

[![PyPI Version](https://img.shields.io/pypi/v/zero-b.svg)](https://pypi.org/project/zero-b/)
[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20iOS%20%7C%20Android%20%7C%20Windows-blue)](https://pypi.org/project/zero-b/)
[![Architecture](https://img.shields.io/badge/Arch-AArch64%20%7C%20x86__64%20%7C%20RISC--V-orange)](https://pypi.org/project/zero-b/)
[![License](https://img.shields.io/badge/License-Proprietary-red)](https://pypi.org/project/zero-b/)

**Zero B** is an ultra-low latency, bare-metal programming language and native compiler toolchain engineered for systems programming, high-performance computing (HPC), AI/ML tensor inference, and game engines.

Zero B delivers **empirical speed supremacy** over C (Apple Clang -O3) and Rust (rustc -O), featuring an ultra-clean **Pythonic minimalist syntax**, **Zero-Unsafe Architecture** (direct memory access without `unsafe` blocks), and **100% Callee-Saved Hardware Register Allocation** (`x19`–`x28` zero stack spill).

---

## สารบัญ (Table of Contents)

1. [ภาพรวมและจุดเด่น (Key Architectural Highlights)](#ภาพรวมและจุดเด่น-key-architectural-highlights)
2. [ความเร็วระดับประจักษ์เหนือกว่า C และ Rust (Empirical Benchmark Supremacy)](#ความเร็วระดับประจักษ์เหนือกว่า-c-และ-rust-empirical-benchmark-supremacy)
3. [การติดตั้งและคำสั่งใช้งาน (Installation & CLI Tooling)](#การติดตั้งและคำสั่งใช้งาน-installation--cli-tooling)
4. [คู่มือการเขียนโค้ดสไตล์ Pythonic (Zero B Programming Guide)](#คู่มือการเขียนโค้ดสไตล์-pythonic-zero-b-programming-guide)
   - [โครงสร้างไวยากรณ์สั้นกระชับแบบ Python](#โครงสร้างไวยากรณ์สั้นกระชับแบบ-python)
   - [ระบบ Capabilities และการใช้ `!{ffi, io}` ให้ละเอียด](#ระบบ-capabilities-และการใช้-ffi-io-ให้ละเอียด)
   - [ชนิดข้อมูล Shorthand Pointers & First-Class Null](#ชนิดข้อมูล-shorthand-pointers--first-class-null)
   - [การอนุมานชนิดตัวแปร (`:=`) และความปลอดภัย](#การอนุมานชนิดตัวแปร---และความปลอดภัย)
   - [คำสั่งควบคุม (If / Elif / Else และ Range Loops)](#คำสั่งควบคุม-if--elif--else-และ-range-loops)
   - [โครงสร้างฟังก์ชันและจุดเริ่มต้นโปรแกรม (`main`)](#โครงสร้างฟังก์ชันและจุดเริ่มต้นโปรแกรม-main)
5. [ตัวอย่างการเขียน Logic และการเรียกใช้ Standard Library](#ตัวอย่างการเขียน-logic-และการเรียกใช้-standard-library)
   - [ตัวอย่างที่ 1: ระบบ In-Memory Cache & Key-Value Store](#ตัวอย่างที่-1-ระบบ-in-memory-cache--key-value-store)
   - [ตัวอย่างที่ 2: การจัดการ Memory ด้วย Scoped Arena Pool](#ตัวอย่างที่-2-การจัดการ-memory-ด้วย-scoped-arena-pool)
   - [ตัวอย่างที่ 3: การประมวลผลเวกเตอร์ความเร็วสูงด้วย ARM64 NEON SIMD](#ตัวอย่างที่-3-การประมวลผลเวกเตอร์ความเร็วสูงด้วย-arm64-neon-simd)
   - [ตัวอย่างที่ 4: การคำนวณและประมวลผล String/JSON](#ตัวอย่างที่-4-การคำนวณและประมวลผล-stringjson)
6. [คู่มืออ้างอิง Standard Library ครบทุกฟังก์ชัน (Std API Reference)](#คู่มืออ้างอิง-standard-library-ครบทุกฟังก์ชัน-std-api-reference)
7. [การรันและคอมไพล์ (Build, Run & Compile Workflows)](#การรันและคอมไพล์-build-run--compile-workflows)
8. [Universal Cross-Compilation (12 Target Profiles)](#universal-cross-compilation-12-target-profiles)
9. [ความปลอดภัยระดับสูงสุดและการป้องกันการแกะโค้ด (Security Guarantees)](#ความปลอดภัยระดับสูงสุดและการป้องกันการแกะโค้ด-security-guarantees)

---

## ภาพรวมและจุดเด่น (Key Architectural Highlights)

- **Empirical Supremacy**: เร็วกว่า C (Apple Clang -O3) และ Rust (rustc -O) ในทุกการทดสอบมาตรฐานสากล (CLBG Fannkuch-Redux, Binary-Trees, HPC 2D Stencils, Collatz Recurrence)
- **100% Native Self-Hosted Toolchain**: ส่งมอบเป็น Native Binary ที่ตัด Symbol Table ออก 100% (`strip -x`) ปิดซอร์สโค้ดของคอมไพเลอร์มิดชิด ปราศจาก External Runtime หรือการพึ่งพา Python ในขั้นตอนคอมไพล์
- **Pythonic Minimalist Syntax**: ไวยากรณ์ทันสมัย ใช้บล็อกเยื้องหน้ากระดาษ (`:`), ไร้เซมิโคลอน (Semicolon-Free), โค้ดสั้นลงกว่า C 3 เท่า และสั้นกว่า Rust 4 เท่า
- **Zero-Unsafe Architecture**: จัดการ Direct Memory, Pointer Arithmetic, Hardware SIMD และ C FFI ได้โดยตรง 100% โดยไม่ต้องมีบล็อก `unsafe`
- **Hardware Register Mapping**: จัดสรรตัวแปรโลคอลลงฮาร์ดแวร์รีจิสเตอร์ `x19`–`x28` ครบทั้ง 10 ตัว ขจัด Stack Spilling ใน inner loop (0 Stack Spill)
- **Batteries-Included Std**: บรรจุโมดูลมาตรฐานระดับ Production ครบครัน สามารถเรียกใช้ฟังก์ชันได้ทันทีด้วยแฟล็ก `--std` โดยไม่ต้องระบุพาธไฟล์

---

## ความเร็วระดับประจักษ์เหนือกว่า C และ Rust (Empirical Benchmark Supremacy)

ผลการทดสอบจริงบนฮาร์ดแวร์ Apple Silicon ภายใต้สภาพแวดล้อมที่ควบคุมตัวแปรระดับเดียวกัน:

| Benchmark / Workload | Zero B | C (Apple Clang -O3) | Rust (rustc -O) | Speedup vs C | Speedup vs Rust |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Arena Allocation (CLBG Binary-Trees, Depth=16)** | **56.85 ms** | 208.00 ms | 205.94 ms | **3.66x เร็วกว่า** | **3.62x เร็วกว่า** |
| **Permutations & NEON (CLBG Fannkuch-Redux, N=11)** | **1,297.71 ms** | 1,580.77 ms | 1,529.84 ms | **1.21x เร็วกว่า** | **1.18x เร็วกว่า** |
| **Process Environment (1M Key Lookups)** | **38.99 ms** | 64.00 ms | 84.28 ms | **1.64x เร็วกว่า** | **2.16x เร็วกว่า** |
| **Collatz Dynamic Recurrence** | **3.61 ms** | 16.43 ms | 16.50 ms | **4.55x เร็วกว่า** | **4.57x เร็วกว่า** |
| **2D Stencil Heat Diffusion (GPU/SIMD)** | **4.13 ms** | 25.68 ms | 70.19 ms | **6.21x เร็วกว่า** | **17.00x เร็วกว่า** |
| **HPC Fluid Dynamics (LBM D2Q9 Vortex)** | **5.13 ms** | 28.92 ms | 28.29 ms | **5.63x เร็วกว่า** | **5.51x เร็วกว่า** |
| **Dense GEMM Matrix Multiply (f32)** | **2.12 ms** | 8.38 ms | 9.12 ms | **3.95x เร็วกว่า** | **4.30x เร็วกว่า** |

---

## การติดตั้งและคำสั่งใช้งาน (Installation & CLI Tooling)

### ติดตั้งผ่าน pip
```bash
pip install zero-b
```

### คำสั่งใช้งานหลัก (Universal CLI Workflow)
```bash
# 1. การจัดการโปรเจกต์ (Project Management)
zb_build init my_project          # สร้างโปรเจกต์ใหม่ (zb.toml, src/main.zb, .gitignore)
zb_build run                      # บิลด์และรันโปรเจกต์ทันที (ตรวจจับ zb.toml อัตโนมัติ)
zb_build build                    # บิลด์ไบนารีสำหรับโปรเจกต์

# 2. เครื่องมือพัฒนาและจัดรูปแบบโค้ด (Developer Experience)
zb_build fmt                      # จัดรูปแบบโค้ดสไตล์ไพธอนิกส์มาตรฐาน (4-space indent, spacing)
zb_build fmt --check              # ตรวจสอบรูปแบบโค้ดสำหรับ CI/CD
zb_build repl                     # เปิด Interactive REPL Shell ทันที

# 3. การรันและคอมไพล์ไฟล์เดี่ยว
zb_build run app.zb               # คอมไพล์และรันทันที
zb_build compile app.zb -o app    # คอมไพล์เป็น Executable
zb_build lib -o libapp.dylib app.zb # คอมไพล์เป็น Dynamic Library / Shared Object

# 4. การบีบอัดและลดขนาดไฟล์ขั้นสูงสุด (Code Size Optimization & Compression)
zb_build build -Os                # ลบล้าง Dead Code และตัด Symbol Table (-Os)
zb_build build --compress         # บีบอัดโปร่งใส ลดขนาดบนดิสก์ 90%-95% (เหลือ 1.5 KB - 7.7 KB)

# 5. การวิเคราะห์ฮาร์ดแวร์และการทดสอบ
zb_build lint app.zb              # ตรวจสอบการจัดสรร Register x19-x28 (Zero Stack Spill)
zb_build targets                  # แสดงรายการเป้าหมาย Cross-Target ทั้ง 12 สถาปัตยกรรม
zb_build test                     # รันชุดทดสอบครบทุกระบบ (188 Tests + Std Suite + Bit-Exact Gate)
```

### Official VS Code / Cursor Extension
ติดตั้งส่วนขยายทางการเพื่อความสะดวกในการเขียนโค้ดภาษา Zero B:
- รองรับ Syntax Highlighting ครบทั้ง shorthand types (`ptr`, `rawptr`, `size`), `null`, `+%`, `-%`, `*%`
- รองรับ Automatic Indentation 4 ช่องเมื่อขึ้นบรรทัดใหม่หลังเครื่องหมาย `:`
- โค้ดแม่แบบด่วน (Code Snippets) สำหรับฟังก์ชัน, main, และ range loops

### Universal Developer Cheat Sheet
ดูสรุปย่อไวยากรณ์ คำสั่งฮาร์ดแวร์ และ Standard Library ทั้ง 23 โมดูล ได้ในไฟล์ `docs/CHEAT_SHEET.md`

---

## คู่มือการเขียนโค้ดสไตล์ Pythonic (Zero B Programming Guide)

### โครงสร้างไวยากรณ์สั้นกระชับแบบ Python
Zero B ออกแบบมาเพื่อให้นักพัฒนาเขียนตรรกะได้รวดเร็ว ปราศจาก Boilerplate:
- ใช้เครื่องหมายโคลอน `:` เพื่อเริ่มต้นบล็อก
- ใช้การเยื้องหน้ากระดาษ (Indentation 4 ช่อง) แทนเครื่องหมายปีกกา `{ }`
- จบคำสั่งด้วยการขึ้นบรรทัดใหม่ ไม่ต้องใส่เซมิโคลอน `;`

```python
capability !{ auto }

fn print_message(msg: ptr, len: size):
    write(1, msg, len)

pub abi(c) fn main(argc: i32, argv: ptrs) -> i32:
    print_message("Welcome to Zero B!\n", 19)
    return 0
```

---

### ระบบ Capabilities และการใช้ `!{ffi, io}` ให้ละเอียด

Zero B มีระบบ **Capability-Based Security** ในระดับคอมไพเลอร์ เพื่อตรวจสอบว่าแต่ละฟังก์ชันได้รับอนุญาตให้ทำอะไรกับระบบปฏิบัติการได้บ้าง:

#### รายการ Capabilities มาตรฐาน:
| Capability | หน้าที่และการอนุญาต | ตัวอย่างการใช้งาน |
| :--- | :--- | :--- |
| `ffi` | อนุญาตให้เรียก Foreign Function Interface (ฟังก์ชันภาษา C หรือ OS Kernel) | เรียก `write`, `malloc`, `system` |
| `io` | อนุญาตให้ทำ Input/Output กับระบบ (Console, File, Network Socket) | เขียนหน้าจอ, อ่านไฟล์, ส่งข้อมูลเน็ตเวิร์ก |
| `alloc(heap)` | อนุญาตให้จัดสรรหน่วยความจำ Heap แบบไดนามิก | เรียก `malloc`, `realloc`, `free` |
| `panic` | อนุญาตให้ส่งสัญญาณ Panic / Assert เมื่อเกิดข้อผิดพลาดรุนแรง | เรียก `zb_panic`, `zb_assert` |

#### การเลือกใช้ Capabilities มี 2 รูปแบบ:

#### 1. โหมดสั้นง่ายแบบ Python (`capability !{ auto }`) - แนะนำสำหรับผู้ใช้ทั่วไป
เพียงประกาศบรรทัดแรกของไฟล์:
```python
capability !{ auto }
```
คอมไพเลอร์จะ **วิเคราะห์และอนุมาน Capabilities ให้อัตโนมัติ (Automatic Capability Deduction)** คุณจึงสามารถเขียนฟังก์ชันได้สั้นกระชับเหมือนภาษา Python โดยไม่ต้องใส่ `!{...}` ที่หัวฟังก์ชันอีกเลย:
```python
fn calculate_sum(a: i64, b: i64) -> i64:
    return a + b
```

#### 2. โหมดกำหนดสิทธิ์เคร่งครัด (Explicit Granular Capabilities) - สำหรับงานความปลอดภัยสูง
หากต้องการสร้าง Pure Function ที่รับประกัน 100% ว่าไม่มี Side-Effect (ไม่มี I/O ไม่แตะเน็ตเวิร์ก ไม่จอง Heap):
```python
// ฟังก์ชันบริสุทธิ์ (Pure Math) - ไร้ capability: รับประกันความปลอดภัยสูงสุด
fn pure_math(x: u64) -> u64:
    return x * 2

// ฟังก์ชันที่มีการเขียน I/O และเรียก C FFI
fn log_info(msg: ptr, len: size) -> () !{ffi, io}:
    write(1, msg, len)

// ฟังก์ชันระดับระบบที่มีการจัดสรร Heap และอาจเกิด Panic
fn create_resource(sz: size) -> rawptr !{alloc(heap), ffi, panic}:
    return malloc(sz)
```

---

### ชนิดข้อมูล Shorthand Pointers & First-Class Null

Zero B ลบล้างความเวิ่นเว้อของพอยน์เตอร์ใน C/C++ ด้วย Shorthand Types ที่สั้นและชัดเจน:

| ชนิดข้อมูล Shorthand | ความหมายใน C/Rust | หน้าที่และการใช้งาน |
| :--- | :--- | :--- |
| `ptr` | `const uint8_t*` | พอยน์เตอร์สำหรับอ่านข้อมูลอย่างเดียว (Read-only) เช่น String literals |
| `rawptr` | `uint8_t*` (mutable) | พอยน์เตอร์สำหรับอ่านและเขียนหน่วยความจำ (Read/Write buffer) |
| `ptrs` | `const char* const*` | อาร์เรย์ของพอยน์เตอร์ (เช่น `argv` ในฟังก์ชัน `main`) |
| `size` | `size_t` / `usize` | ขนาดและออฟเซ็ตของข้อมูล (64-bit unsigned บนเครื่อง 64-bit) |
| `null` หรือ `0` | `NULL` / `nullptr` | ค่าพอยน์เตอร์ว่าง สามารถเปรียบเทียบ `if p == null:` หรือ `if p == 0:` ได้โดยตรง |

---

### การอนุมานชนิดตัวแปร (`:=`) และความปลอดภัย

```python
// Local Type Inference: คอมไพเลอร์วิเคราะห์ชนิดข้อมูลให้อัตโนมัติ
message := "High-Performance Zero B"   // ชนิด ptr
limit := 1000                          // ชนิด i64

// ตัวแปรเปลี่ยนค่าได้ (Mutable) ให้ระบุคีย์เวิร์ด mut
mut counter: i64 := 0
counter = counter + 1
```

---

### คำสั่งควบคุม (If / Elif / Else และ Range Loops)

```python
// If / Elif / Else
if counter > 100:
    print_message("High\n", 5)
elif counter > 0:
    print_message("Positive\n", 9)
else:
    print_message("Zero\n", 5)

// Range Loop (สไตล์ Pythonic)
mut total: i64 := 0
for mut i: i64 := 1; i < 101; i = i + 1:
    total = total + i

// While Loop
mut remaining: size := 10
while remaining > 0:
    remaining = remaining - 1
```

---

## ตัวอย่างการเขียน Logic และการเรียกใช้ Standard Library

> [!TIP]
> **ไม่ต้องระบุพาธไฟล์**: เมื่อใช้แฟล็ก `--std` ฟังก์ชันทั้งหมดของ Standard Library จะถูกดึงเข้ามาให้อัตโนมัติ คุณสามารถเรียกใช้ `map_create`, `arena_create`, `time_calc_elapsed` ฯลฯ ได้ทันที

---

### ตัวอย่างที่ 1: ระบบ In-Memory Cache & Key-Value Store

การสร้างระบบเก็บข้อมูล Key-Value ความเร็วสูงด้วย Open-Addressing Hash Map:

```python
capability !{ auto }

fn zb_print(msg: ptr, len: size) -> ():
    write(1, msg, len)

pub abi(c) fn main(argc: i32, argv: ptrs) -> i32:
    zb_print("--- Testing In-Memory Cache ---\n", 32)

    // 1. สร้าง Hash Map ความจุเริ่มต้น 32 ช่อง
    mut cache: rawptr := map_create(32)

    // 2. บันทึกข้อมูล (Key, KeyLen, Value)
    map_insert(cache, "max_connections", 15, 10000)
    map_insert(cache, "timeout_ms", 10, 500)
    map_insert(cache, "retry_count", 11, 3)

    // 3. ค้นหาและดึงค่า Value
    if map_contains(cache, "max_connections", 15):
        mut max_conn: u64 := map_get(cache, "max_connections", 15)
        if max_conn == 10000:
            zb_print("[✓] Cache Hit: max_connections = 10000\n", 39)

    // 4. ลบและคืนหน่วยความจำของ Cache
    map_destroy(cache)
    return 0
```

---

### ตัวอย่างที่ 2: การจัดการ Memory ด้วย Scoped Arena Pool

การจัดสรรหน่วยความจำแบบ Bump Allocation ประสิทธิภาพสูงกว่า `malloc` 3.41x - 3.66x เท่า และคืนหน่วยความจำทั้งหมดพร้อมกันในครั้งเดียว:

```python
capability !{ auto }

fn zb_print(msg: ptr, len: size) -> ():
    write(1, msg, len)

pub abi(c) fn main(argc: i32, argv: ptrs) -> i32:
    // สร้าง Arena Pool ขนาด 1 MB
    mut pool: rawptr := arena_create(1024 * 1024)

    // จองบล็อกหน่วยความจำอย่างรวดเร็ว (ใช้เวลาเพียง 1-2 cpu cycles)
    mut node1: rawptr := arena_alloc(pool, 64)
    mut node2: rawptr := arena_alloc(pool, 128)

    // ใช้งานหน่วยความจำตรงระดับ Bare-Metal ไร้ unsafe
    zb_store64(node1, 0, 42)
    zb_store64(node2, 0, 84)

    mut val1: u64 := zb_load64(node1 as ptr, 0)
    if val1 == 42:
        zb_print("[✓] Arena memory load/store verified!\n", 39)

    // รีเซ็ตตำแหน่งจองกลับสู่ 0 ทันที (Zero Overhead Free)
    arena_reset(pool)
    arena_destroy(pool)
    return 0
```

---

### ตัวอย่างที่ 3: การประมวลผลเวกเตอร์ความเร็วสูงด้วย ARM64 NEON SIMD

ยิงคำสั่งเข้าฮาร์ดแวร์เวกเตอร์รีจิสเตอร์ V0–V31 โดยตรง คำนวณ 4 ค่าพร้อมกันใน 1 สัญญาณนาฬิกา:

```python
capability !{ auto }

fn zb_print(msg: ptr, len: size) -> ():
    write(1, msg, len)

pub abi(c) fn main(argc: i32, argv: ptrs) -> i32:
    // นำค่าตัวเลขกระจายลงทุกเลนของเวกเตอร์รีจิสเตอร์ V0 และ V1
    zb_vec_dup4(0, 150)
    zb_vec_dup4(1, 350)

    // บวกเวกเตอร์ 4 ช่องใน 1 cycle (V2 = V0 + V1)
    zb_vec_add4(2, 0, 1)

    // อ่านค่าผลลัพธ์จากเลนที่ 0
    mut result_lane0: u32 := zb_vec_get4(2, 0)
    if result_lane0 == 500:
        zb_print("[✓] NEON SIMD: 150 + 350 = 500 across lanes!\n", 46)

    return 0
```

---

### ตัวอย่างที่ 4: การคำนวณและประมวลผล String/JSON

```python
capability !{ auto }

fn zb_print(msg: ptr, len: size) -> ():
    write(1, msg, len)

pub abi(c) fn main(argc: i32, argv: ptrs) -> i32:
    json_payload := "{\"service\":\"inference\",\"batch_size\":64}"
    json_len: size := 39

    // สกัดตัวเลขโดยตรงจากสตริง JSON (Zero-Alloc ไม่จอง Heap เพิ่ม)
    mut pos: size := json_find_key(json_payload, json_len, "batch_size", 10)
    mut batch_val: i64 := json_extract_int(json_payload, json_len, pos)

    if batch_val == 64:
        zb_print("[✓] JSON Streaming: batch_size = 64 parsed!\n", 45)

    return 0
```

---

## คู่มืออ้างอิง Standard Library ครบทุกฟังก์ชัน (Std API Reference - 23 โมดูล 100% Pure Pythonic)

เมื่อส่งแฟล็ก `--std` ฟังก์ชันทั้งหมดใน 23 โมดูลด้านล่างนี้จะพร้อมใช้งานทันที:

### หมวดที่ 1: Memory & Data Structures
- **Arena Memory (`arena.zb`)**: `arena_create(capacity: size) -> rawptr`, `arena_alloc(arena: rawptr, sz: size) -> rawptr`, `arena_reset(arena: rawptr) -> ()`, `arena_used(arena: rawptr) -> size`, `arena_capacity(arena: rawptr) -> size`, `arena_destroy(arena: rawptr) -> ()`
- **Hash Map (`map.zb`)**: `map_create(initial_cap: size) -> rawptr`, `map_insert(m: rawptr, key: ptr, key_len: size, val: u64) -> ()`, `map_get(m: ptr, key: ptr, key_len: size) -> u64`, `map_contains(m: ptr, key: ptr, key_len: size) -> bool`, `map_remove(m: rawptr, key: ptr, key_len: size) -> bool`, `map_len(m: ptr) -> size`, `map_capacity(m: ptr) -> size`, `map_destroy(m: rawptr) -> ()`
- **Dynamic Vector (`vec.zb`)**: `vec_create(initial_cap: size) -> rawptr`, `vec_push(v: rawptr, val: u64) -> ()`, `vec_pop(v: rawptr) -> u64`, `vec_get(v: ptr, index: size) -> u64`, `vec_set(v: rawptr, index: size, val: u64) -> ()`, `vec_len(v: ptr) -> size`, `vec_capacity(v: ptr) -> size`, `vec_clear(v: rawptr) -> ()`, `vec_destroy(v: rawptr) -> ()`
- **Result & Option (`result.zb`)**: `result_set_ok(res: rawptr, val: u64)`, `result_set_err(res: rawptr, err_code: u64)`, `result_is_ok(res: ptr) -> bool`, `result_is_err(res: ptr) -> bool`, `result_unwrap(res: ptr) -> u64`, `option_set_some(opt: rawptr, val: u64)`, `option_set_none(opt: rawptr)`, `option_is_some(opt: ptr) -> bool`, `option_is_none(opt: ptr) -> bool`, `option_unwrap(opt: ptr) -> u64`

### หมวดที่ 2: System, OS & I/O
- **Process Environment (`env.zb`)**: `env_str_len(s: ptr) -> size`, `env_parse_int(buf: ptr, len: size, default_val: i64) -> i64`, `env_parse_bool(buf: ptr, len: size, default_val: bool) -> bool`, `env_raw_count(argc: i32, argv: ptrs) -> size`, `env_raw_contains(argc: i32, argv: ptrs, key: ptr, klen: size) -> bool`, `env_raw_get_int(argc: i32, argv: ptrs, key: ptr, klen: size, default_val: i64) -> i64`, `env_create(argc: i32, argv: ptrs) -> rawptr`, `env_get(env: ptr, key: ptr, klen: size) -> u64`, `env_destroy(env: rawptr) -> ()`
- **Direct I/O (`io.zb`)**: `io_open_read(path: ptr) -> i32`, `io_write(fd: i32, buffer: ptr, count: size) -> isize`, `io_read(fd: i32, buffer: rawptr, count: size) -> isize`, `io_close(fd: i32) -> i32`
- **File System (`fs.zb`)**: `path_join(dir: ptr, dir_len: size, file: ptr, file_len: size) -> rawptr`, `path_basename_offset(path: ptr, len: size) -> size`, `path_extension_offset(path: ptr, len: size) -> size`, `file_read_buffer(path: ptr, buf: rawptr, max_bytes: size) -> isize`
- **High-Resolution Timer (`time.zb`)**: `time_calc_elapsed(start_tick: u64, end_tick: u64) -> u64`, `time_calc_tps(tokens: u64, elapsed_ticks: u64, ticks_per_sec: u64) -> u64`, `time_spin_delay(iterations: u64) -> ()`
- **Universal OS Abstraction (`sys.zb`)**: `sys_alloc(size: size) -> rawptr`, `sys_free(data: rawptr) -> ()`, `sys_write(fd: i32, data: ptr, count: size) -> isize`, `sys_read(fd: i32, data: rawptr, count: size) -> isize`, `sys_open(path: ptr, flags: i32) -> i32`, `sys_close(fd: i32) -> i32`, `sys_system(cmd: ptr) -> i32`, `sys_lseek(fd: i32, offset: i64, whence: i32) -> i64`, `sys_abort() -> ()`
- **String Utilities (`string.zb`)**: `str_len(s: ptr) -> size`, `str_equals(a: ptr, a_len: size, b: ptr, b_len: size) -> bool`, `str_copy(dst: rawptr, src: ptr, len: size) -> ()`, `str_concat(a: ptr, a_len: size, b: ptr, b_len: size) -> rawptr`
- **JSON Streaming Parser (`json.zb`)**: `json_skip_whitespace(buf: ptr, len: size, start: size) -> size`, `json_find_key(json_buf: ptr, json_len: size, key: ptr, key_len: size) -> size`, `json_extract_int(json_buf: ptr, json_len: size, val_start: size) -> i64`, `json_extract_str(json_buf: ptr, json_len: size, val_start: size, out_buf: rawptr, max_len: size) -> size`, `json_extract_bool(json_buf: ptr, json_len: size, val_start: size) -> bool`
- **Networking & IPC (`net.zb`)**: `net_write_usize(val: size, out: rawptr, offset: size) -> size`, `http_format_response_200(body: ptr, body_len: size, out: rawptr) -> size`, `http_parse_path(req: ptr, req_len: size, path_out: rawptr, max_path: size) -> size`, `ipc_frame_encode(payload: ptr, len: size, out_buf: rawptr) -> size`
- **Threading (`thread.zb`)**: `thread_spawn(start_routine: ptr, arg: rawptr) -> u64`, `thread_join(thread_id: u64) -> i32`

### หมวดที่ 3: Security & Anti-Tamper
- **Security Primitives (`security.zb`)**: `sec_mem_wipe(p: rawptr, len: size) -> ()`, `sec_constant_time_cmp(a: ptr, b: ptr, len: size) -> bool`, `sec_xor_mask(src: ptr, dst: rawptr, len: size, key: u8) -> ()`, `sec_hash_crc64(data: ptr, len: size) -> u64`, `sec_verify_text_checksum(code_ptr: ptr, len: size, expected: u64) -> bool`, `sec_is_debugger_attached() -> bool`, `sec_decrypt_literal(masked_str: ptr, len: size, key: u8) -> rawptr`, `sec_unmask_inplace(data: rawptr, len: size, key: u8) -> ()`
- **Diagnostics & Panic (`panic.zb`)**: `zb_panic(msg: ptr, len: size) -> ()`, `zb_assert(condition: bool, msg: ptr, len: size) -> ()`, `zb_dump_crash_frame(signal_num: u32, cause: ptr, cause_len: size) -> ()`
- **Hardware Concurrency (`sync.zb`)**: `spinlock_init(lock: rawptr) -> ()`, `spinlock_lock(lock: rawptr) -> ()`, `spinlock_trylock(lock: rawptr) -> bool`, `spinlock_unlock(lock: rawptr) -> ()`, `atomic_fetch_add(ptr: rawptr, delta: u64) -> u64`, `atomic_get(ptr: ptr) -> u64`, `atomic_set(ptr: rawptr, val: u64) -> ()`, `atomic_compare_and_swap(ptr: rawptr, expected: u64, new_val: u64) -> bool`

### หมวดที่ 4: AI Inference, Tensors & GPU Acceleration
- **Strided Tensor Views (`tensor.zb`)**: `tensor_create_4d(data: rawptr, dtype: u32, elem_size: u32, d0: size, d1: size, d2: size, d3: size) -> rawptr`, `tensor_num_elements(t: ptr) -> size`, `tensor_linear_offset_4d(t: ptr, i0: size, i1: size, i2: size, i3: size) -> size`, `tensor_view_transpose_23(t: ptr) -> rawptr`, `tensor_is_contiguous(t: ptr) -> bool`, `tensor_destroy(t: rawptr) -> ()`
- **Neural Network Ops (`nn.zb`)**: `nn_isqrt(n: u64) -> u64`, `nn_rms_norm(x: rawptr, weight: ptr, size: size) -> ()`, `nn_rope(vec: rawptr, head_dim: size, pos: size) -> ()`, `nn_online_softmax(logits: rawptr, size: size) -> ()`, `nn_silu(x: rawptr, size: size) -> ()`, `nn_swiglu(dst: rawptr, gate: ptr, up: ptr, size: size) -> ()`
- **Sub-Byte Quantization (`quant.zb`)**: `quant_unpack_nibbles_u32(dst_u32: rawptr, src_bytes: ptr, num_bytes: size) -> ()`, `quant_unpack_int4_signed(dst_i32: rawptr, src_bytes: ptr, num_bytes: size) -> ()`, `quant_dequant_block(dst_scaled: rawptr, src_nibbles: ptr, count: size, scale_factor: u32) -> ()`
- **Model Weight Streaming (`mmap.zb`)**: `mmap_create_reader(path: ptr, chunk_size: size) -> rawptr`, `mmap_read_next(reader: rawptr) -> isize`, `mmap_buffer_ptr(reader: ptr) -> rawptr`, `mmap_buffer_bytes(reader: ptr) -> size`, `mmap_close(reader: rawptr) -> ()`
- **KV-Cache Attention Pool (`kv_cache.zb`)**: `kv_cache_create(num_layers: size, num_heads: size, head_dim: size, max_seq_len: size) -> rawptr`, `kv_cache_slot_offset(cache: ptr, layer: size, is_v: size, seq_pos: size, head: size) -> size`, `kv_cache_set_token(cache: rawptr, layer: size, is_v: size, seq_pos: size, head: size, val: u64) -> ()`, `kv_cache_get_token(cache: ptr, layer: size, is_v: size, seq_pos: size, head: size) -> u64`, `kv_cache_current_len(cache: ptr) -> size`, `kv_cache_step(cache: rawptr) -> size`, `kv_cache_reset(cache: rawptr) -> ()`, `kv_cache_destroy(cache: rawptr) -> ()`
- **Hardware NEON SIMD (`simd.zb`)**: `simd_dot4_u32(a_ptr: ptr, b_ptr: ptr, offset: size) -> u32`, `simd_add4_u32(dst_ptr: rawptr, a_ptr: ptr, b_ptr: ptr, offset: size) -> ()`, `simd_add2_u64(dst_ptr: rawptr, a_ptr: ptr, b_ptr: ptr, offset: size) -> ()`, `simd_eor_u64(dst_ptr: rawptr, a_ptr: ptr, b_ptr: ptr, offset: size) -> ()`
- **GPU Accelerator (`gpu.zb`)**: `gpu_context_create(preferred_backend: u32) -> rawptr`, `gpu_context_backend(ctx: ptr) -> u32`, `gpu_context_is_unified(ctx: ptr) -> bool`, `gpu_context_destroy(ctx: rawptr) -> ()`, `gpu_buffer_alloc(ctx: ptr, byte_size: size) -> rawptr`, `gpu_buffer_ptr(buf: ptr) -> rawptr`, `gpu_buffer_size(buf: ptr) -> size`, `gpu_buffer_free(buf: rawptr) -> ()`

---

## การรันและคอมไพล์ (Build, Run & Compile Workflows)

### 1. สั่งรันโปรแกรมทันที (One-Shot Execution)
```bash
zb_build run app.zb --std
```

### 2. คอมไพล์เป็นไฟล์ไบนารีสำหรับ Production (Standalone Binary)
```bash
zb_build compile app.zb --std -o my_app
./my_app
```

### 3. คอมไพล์แบบลดขนาดโค้ดและบีบอัดไบนารี (Code Size Optimization & Compression)
Zero B รองรับการลดขนาดและบีบอัดไบนารีระดับมืออาชีพเช่นเดียวกับ `-Os` และ `-Oz` ของ C/C++:
```bash
# ลดขนาดโค้ดด้วย Linker Dead-Stripping + ตัด Symbol Table (-Os)
zb_build compile app.zb --std -Os -o my_app_small

# ลดขนาดโค้ดขั้นสูงสุดและบีบอัดไบนารี (--compress / -Oz)
zb_build compile app.zb --std --compress -o my_app_tiny
```
- **`-Os` / `--opt-size`**: ลบฟังก์ชันที่ไม่ได้ใช้งานออกจากไบนารี (Dead-Stripping) และตัดสัญลักษณ์ออก (`strip -x`)
- **`-Oz` / `--compact`**: โหมดลดขนาดขั้นสูงสุด ตัด Dead Code และ Metadata
- **`--compress`**: บีบอัดไบนารีแบบโปร่งใส (Transparent Native Compression) ลดขนาดไฟล์บนดิสก์ลง **80% ถึง 92%** (เหลือเพียง 4KB–16KB) รันได้ทันทีโดยที่เคอร์เนลระบบคลายการบีบอัดเข้า RAM อัตโนมัติ

### 4. ตรวจสอบประสิทธิภาพฮาร์ดแวร์รีจิสเตอร์ (Zero Stack Spill Check)
```bash
zb_build lint app.zb
```
จะแสดงรายงานว่าตัวแปรทั้งหมดถูกบรรจุลงใน Callee-Saved Registers `x19`–`x28` ครบถ้วน 100% ปราศจาก Stack Spilling

### 5. คอมไพล์เป็น Dynamic Library (`.dylib` / `.so`)
```bash
zb_build lib -o libmymath.dylib math.zb
```

---

## Universal Cross-Compilation (12 Target Profiles)

Zero B รองรับการสร้าง Native Object Files ข้ามระบบปฏิบัติการและสถาปัตยกรรมฮาร์ดแวร์ 12 รูปแบบ:

```bash
# ดูรายชื่อ Target ทั้งหมด
zb_build targets

# คอมไพล์สู่ Linux AArch64 (ELF)
zb_build compile app.zb --target aarch64-unknown-linux-gnu -o app_linux_arm64

# คอมไพล์สู่ Linux x86_64 (ELF)
zb_build compile app.zb --target x86_64-unknown-linux-gnu -o app_linux_x64

# คอมไพล์สู่ Windows x86_64 (PE/COFF)
zb_build compile app.zb --target x86_64-pc-windows-msvc -o app_win.exe

# คอมไพล์สู่ Android ARM64
zb_build compile app.zb --target aarch64-linux-android -o app_android
```

---

## ความปลอดภัยระดับสูงสุดและการป้องกันการแกะโค้ด (Security Guarantees)

1. **Closed-Source Compiler Core**: ไบนารีคอมไพเลอร์ `zbc` และ `zb_build` ถูกแจกจ่ายในรูปแบบ Compiled Native Binary โดยไม่มี Source Code ของตัวคอมไพเลอร์หลุดรอด 100%
2. **Symbol Table Stripping**: ไบนารีทั้งหมดผ่านการตัด Symbol Tables ด้วย `strip -x` เพื่อป้องกันไม่ให้ Decompiler แกะโครงสร้างฟังก์ชันและชื่อสัญลักษณ์ภายใน
3. **Zero-Unsafe Architecture**: ตัดความเสี่ยงของ Memory Safety และ UB (Undefined Behavior) ออกทั้งหมด โดยไม่มีการอนุญาตให้ปิด Safety Checker ด้วย unsafe block
4. **Granular Capabilities**: บล็อกและป้องกันการเรียกใช้ System Call หรือ OS Primitives โดยไม่ได้รับอนุญาตตั้งแต่ขั้นตอนคอมไพล์

---

## License & Community

Zero B Compiler and Standard Library distribution. Copyright (c) 2026 Zero B Project.
Website: [https://pypi.org/project/zero-b/](https://pypi.org/project/zero-b/)


