Zlang

Compilatore e runtime bytecode per il prototipo ZDOS x86_64.

Zlang è il compilatore e il runtime bytecode del prototipo ZDOS x86_64. Il percorso verificato è concreto: un file .zlang viene compilato in bytecode ZLB2 v2.5, incorporato in un kernel bare-metal ed eseguito durante il boot in QEMU.

In breve

Zlang definisce il linguaggio sorgente, il compilatore e il contratto bytecode utilizzato dal runtime ZDOS. Il progetto privilegia un comportamento esplicito: ciò che non appartiene al profilo supportato viene rifiutato invece di essere interpretato implicitamente.

Stato attuale: Zlang non è ancora un linguaggio general-purpose e ZDOS non è ancora un sistema operativo general-purpose. Variabili, funzioni, filesystem nativo, rete, processi, driver, loader esterno e syscall pubbliche sono ancora limitati o futuri. La capability Linux confinata storage.read-v1 è disponibile separatamente tramite bridge read-only.

Avvio rapido

Clona Zlang e ZDOS nella stessa directory, quindi esegui la verifica del target bare-metal:

git clone https://github.com/high-cde/Zlang.git
git clone https://github.com/high-cde/ZDOS.git

cd ZDOS/os/x86_64
make clean
make verify
sh tools/verify_qemu.sh

L’esecuzione completa deve produrre questa sequenza seriale:

ZDOS x86_64 bootstrap
Zlang runtime ZLB2 v2.5 ready
ZDOS: native Zlang program executed
ZDOS: Zlang halted cleanly

Per la build sono richiesti python3, gcc, binutils, make, grub-mkrescue, xorriso e qemu-system-x86_64.

Scrivere il primo programma

Il profilo ZLB2 v2.5 è volutamente minimale. Un programma può contenere commenti, righe vuote, istruzioni emit e il record capability storage.read:

# examples/hello.zlang
emit Ciao dal programma Zlang nativo
emit Il kernel ZDOS ha eseguito questo bytecode

Compila l’esempio in bytecode e header C:

python3 tools/zlangc.py examples/hello.zlang \
  --bytecode /tmp/hello.zlb \
  --header /tmp/hello.h

Il compilatore rifiuta ciò che non appartiene ancora al profilo:

let risposta = 42

La capability storage.read è valida soltanto con un path relativo al namespace autorizzato e viene eseguita nel percorso Linux dal bridge documentato più avanti.

zlangc v2.5 error: sintassi sconosciuta; il profilo rifiuta istruzioni non definite dal contratto

Questo comportamento mantiene allineati linguaggio, contratto, runtime e documentazione.

Supporto attuale e roadmap

Contratto ZLB2 v2.5

Il bytecode è il contratto esplicito tra compilatore e runtime. Ogni campo ha una funzione verificabile:

Il runtime rifiuta magic, versione, opcode, lunghezza o terminazione non validi. Questo modello default-deny stabilisce il primo confine di sicurezza: ciò che non è definito dal contratto non viene eseguito implicitamente.

Il riferimento tecnico completo è il profilo ZLB2 v2.5.

Catena di esecuzione

Il bytecode non riceve accesso diretto a shell, rete, credenziali o filesystem. Ogni futura syscall dovrà essere una capability esplicita, limitata, auditabile e disabilitata per default.

Roadmap guidata dall’evidenza

Prima di dichiarare supportata una nuova capacità, il progetto richiede contratto, implementazione, limiti, test positivi e test di diniego.

Verifica locale e CI

Esegui i test del contratto del compilatore senza dipendenze esterne:

python3 -m unittest discover -s tests -p 'test_*.py' -v

GitHub Actions esegue inoltre formattazione, build, Clippy e test Rust. La verifica end-to-end viene completata nel workflow ZDOS x86_64, che ricompila il kernel, valida l’header, crea l’ISO e avvia QEMU.

Ecosistema ZDOS

La mappa dei contratti e le convenzioni documentali dell’ecosistema sono disponibili in docs/ECOSYSTEM.md e docs/DOCUMENTATION_STYLE.md.

La pipeline evolutiva completa è orchestrata dal repository ZDOS tramite scripts/evolve-zlang-evidence.sh. Il comando collega il sorgente Zlang, il bytecode ZLB2, il kernel ZDOS, il boot QEMU e una registrazione append-only nella Evidence Chain. L’attestazione contiene hash degli artefatti e commit dei repository; non implica networking, consenso distribuito o esecuzione remota.

Documentazione

Contribuire

Mantieni le modifiche circoscritte, aggiorna la documentazione quando cambia il comportamento e includi test per ogni modifica al contratto o al compilatore. Prima di aprire una pull request:

python3 -m unittest discover -s tests -p 'test_*.py' -v
cargo fmt --all -- --check
cargo check --all-targets
git diff --check

Consulta CONTRIBUTING.md, SECURITY.md e CODE_OF_CONDUCT.md prima di contribuire.

Licenza

Questo progetto è distribuito secondo la licenza indicata in LICENSE.

---

Zlang · ZDOS — Build what you can prove.

storage.read-v1: capability read-only

Zlang v2.5 supporta il record ZLB2 0x06 tramite la sintassi:

storage.read ".zdos-persistence-marker"

Il percorso è relativo al namespace autorizzato. Path assoluti, .., NUL byte e accesso a /dev vengono rifiutati.

Nel percorso Linux verificato da ZDOS, la lettura reale avviene tramite il bridge confinato:

python3 tools/zlang_storage_read.py program.zlang \
  --root /mnt/data \
  --max-bytes 4096

Il bridge è read-only, applica un limite di dimensione, risolve il path dentro /mnt/data e restituisce ZLANG_STORAGE_READ_OK con path relativo, dimensione e hash del contenuto. La scrittura non è supportata.

Il runtime bare-metal ZDOS riconosce e valida l’opcode storage.read, ma dichiara esplicitamente che la capability richiede il bridge Linux finché il filesystem nativo del kernel non sarà disponibile. Non è accesso raw al disco e non implica che il target bare-metal possieda già un filesystem.

Verifica locale:

python3 tests/test_storage_read_v1.py

Questa milestone dimostra il contratto Zlang e la lettura confinata nel percorso Linux; non abilita syscall universali, accesso al filesystem host fuori dal namespace o scrittura persistente.