fzy

un linguaggio di programmazione di sistema che dà priorità alla correttezza verificabile, al determinismo e alle prestazioni

Installa

Installazione consigliata:

Questo installa fz in ~/.local/bin, aggiorna PATH se necessario e verifica l'installazione con fz version e fz env.

Fallback dal sorgente:

Panoramica Rapida

Vuoi la panoramica più veloce? Apri fzl-showcase.html con open fzl-showcase.html, sfoglia WHYFZY.md per l'argomentazione del prodotto, poi usa l'esempio qui sotto come schizzo eseguibile compatto.

Per una copertura linguistica più ampia, usa CODE.md, examples/ e la vetrina FZL ottimizzata per browser.

I pacchetti framework seguono le normali regole dei pacchetti: dichiarali in fozzy.toml sotto [deps], poi importali nel sorgente con use fzbounds;, use fzweb; e nomi di pacchetto simili. I controlli diretti sul sorgente come fz check src/services/mod.fzy --json ora convalidano attraverso il contesto del pacchetto proprietario, quindi le importazioni delle dipendenze e i moduli fratelli si comportano allo stesso modo dei controlli sull'intero progetto.

Cosa Contiene fzy

• fz: CLI del compilatore per build, esecuzione, test, verifica, documentazione, IR, RPC, header, controlli ABI e altro
• formattazione e generazione documentazione integrate: fz fmt, fz doc gen
• pipeline front-end e IR: crates/parser, crates/ast, crates/hir, crates/fir
• verificatore e applicazione della sicurezza: crates/verifier
• primitive runtime deterministico: crates/runtime
• driver e orchestrazione artefatti: crates/driver
• scenari Fozzy eseguibili: tests/*.fozzy.json

Stato Attuale

Implementato e validato oggi:

• ambito di linguaggio per sistemi di uso generale, non uno strumento di nicchia per singolo dominio
• sicuro di default, con isole unsafe esplicite, inventario/documentazione unsafe generati dal compilatore e gestione manuale della memoria con opt-in tramite alloc(...) / free(...)
• semantica runtime reale defer sia nel codice normale che nelle isole unsafe { ... }, quindi la pulizia deterministica è imposta anziché solo documentata
• regole di proprietà, prestito, capacità, FFI e abbassabilità nativa imposte dal verificatore
• gestione manuale esplicita della memoria è supportata all'interno di quel modello, con flussi alloc(...) / free(...) consapevoli della proprietà e controlli del ciclo di vita visibili al verificatore
• traccia deterministica, replay e validazione dello scheduler come normali porte di produzione
• percorsi di fiducia basati su host per filesystem, processi e comportamento HTTP
• modalità scheduler deterministico: fifo, random, coverage_guided
• artefatti decisionali per esecuzione asincrona, thread e RPC
• eventi frame RPC: rpc_send, rpc_recv, rpc_deadline, rpc_cancel
• metadati di esplorazione e riduzione per flussi di lavoro replay/minimizzazione
• generazione nativa di scenari dal linguaggio a partire dai blocchi test analizzati
• caricamento ricorsivo di moduli multi-file dalle dichiarazioni mod
• generazione di header C dalle firme pubext c fn esportate
• generazione di schema RPC, stub client e server tramite fz rpc gen
• superficie moderna linguaggio/runtime con ADT, pattern matching, trait, generici, modellazione del dominio tipizzata, processi, terminale, logging, filesystem/path, JSON ai confini e HTTP in streaming in uscita
• superficie crittografica/di sicurezza di produzione tramite core.crypto e core.security, inclusi random sicuro, hashing, HMAC, confronto tempo costante e codifiche URL-safe
• moduli framework web di produzione fzweb per routing applicazioni, cookie, sessioni, upload multipart, persistenza, SSE, websocket ed export OpenAPI
• fz run esegue direttamente l'output nativo con streaming di testo live o cattura JSON
• backend nativi LLVM e Cranelift con validazione orientata alla parità
• porte di rilascio di memoria diretta:
  • python3 scripts/direct_memory_architecture_gate.py
  • python3 scripts/direct_memory_perf_gate.py
• superficie GPU di produzione tramite core.gpu, con esecuzione Metal live su Apple più contratti adattatore spirv/nvptx condivisi

Affermazioni di Produzione

fzy è configurato per supportare queste affermazioni di produzione oggi:

• la superficie linguistica sicura fornita è memory-safe di default entro l'ambito documentato delle regole del compilatore/verificatore, con confini unsafe espliciti e verificati e gestione manuale della memoria tracciata dalla proprietà con opt-in
• la semantica interna del compilatore/runtime/tooling rimane una fonte di verità tipizzata, con JSON riservato per confini esterni, artefatti generati e output macchina per operatori
• alloc(...) / free(...) rimangono in codice sicuro quando il compilatore può ancora verificare proprietà, provenienza ed esecuzione della pulizia
• correttezza verificabile tramite verificatore, diagnostica, test deterministici, replay e artefatti CI
• esecuzione deterministica tramite tracce registrate, replay e controllo dello scheduler
• copertura di sistemi di uso generale su async/task, RPC, ADT, trait/generici, controllo processi, I/O terminale, logging, filesystem/path, stato interno tipizzato, JSON ai confini e HTTP in streaming
• copertura web/servizi di produzione tramite fzweb più primitive di sicurezza che mantengono i flussi sessione/cookie/auth all'interno della superficie runtime supportata

Vedi anche:

• docs/system-safety-trust-model-v1.md
• docs/production-memory-model-v1.md
• docs/production-workflow-v1.md

Build e Test

CLI Principale

L'integrazione con VS Code si trova in tooling/vscode e ha come target fz lsp serve.

Valori predefiniti del runtime e comportamento esposto:

• binding host predefinito: 127.0.0.1
• porta predefinita: 8787
• il target di binding effettivo viene stampato su listen riuscito
• .env o FZ_DOTENV_PATH viene caricato una volta prima delle operazioni env/HTTP
• i log di testo sono predefiniti; i log JSON sono opt-in tramite log.set_json(1)
• la superficie della libreria standard include core.process, core.term, core.thread, core.log, core.text, core.io, core.path e core.util
• escape di stringhe sicure per terminale, campi di log strutturati, costruttori di collezioni tipizzate, helper JSON ai confini e letterali oggetto basati su mappe sono di prima classe
• gli helper di processo supportano costruttori argv/env più flussi spawn/run con ispezione wait/stdout/stderr/exit
• core.crypto e core.security coprono random sicuro, digest, HMAC, codifiche URL-safe e confronti a tempo costante per flussi di produzione auth/sessione
• fzweb fornisce moduli framework raggruppati per competenza più route integrate per health, readiness, metriche, inspect, search, cookie, sessioni, upload, eventi, websocket, CRUD di elementi, OpenAPI e asset statici

Artefatti Deterministici

Con fz test <file.fzy> --det --record artifacts/name.trace.json --json, il driver emette:

• *.trace.json: traccia di esecuzione deterministica
• *.timeline.json: decisioni dello scheduler
• *.report.json: riepilogo, risultati e raggruppamento dei fallimenti
• *.explore.json: candidati scheduler e priorità degli scenari
• *.shrink.json: suggerimenti di riduzione deterministica
• *.scenarios/ e *.scenarios.json: scenari nativi del linguaggio generati
• *.manifest.json: mappa degli artefatti inclusa il percorso dello scenario principale

Superficie CLI Nativa

Suddivisione di authoring canonica:

• core.process, core.term, core.text: argv e UX terminale
• core.log: politica di logging e output strutturato
• core.io, core.path: scoperta del filesystem e assemblaggio percorsi
• proc.*: esecuzione di processi figli

Esempio:

EOF è esplicito:

• riga vuota: term.read_line() == "" e term.stdin_eof() == 0
• EOF: term.read_line() == "" e term.stdin_eof() == 1

Per lavoro CLI/runtime serio, usa sia il launcher integrato nel compilatore che il binario compilato quando il comportamento esatto del terminale è importante.

Politica Backend Nativo

• backend supportati: cranelift e llvm
• ordine di selezione: --backend esplicito, poi FZ_NATIVE_BACKEND, poi predefinito del profilo
• predefiniti del profilo: dev -> cranelift, release -> llvm

Blocco delle Dipendenze + Vendor

• le build del progetto impongono controlli di deriva del fozzy.lock per le dipendenze di percorso
• aggiorna lo stato del lock con fz vendor [project] --json
• l'output del vendor include fozzy.lock e vendor/fozzy-vendor.json
• specifica: docs/dependency-locking-v1.md

Porta di Compatibilità ABI

fz abi-check impone:

• validità dello schema
• identità del pacchetto
• compatibilità dei confini di panic
• presenza dell'esportazione di base e immutabilità della firma
• immutabilità del contratto di base
• non regressione della versione del simbolo

Le esportazioni aggiuntive sono consentite.

Interoperabilità C

• guida: docs/c-interop-production-v1.md
• ogni pubext c fn esportata richiede #[ffi_panic(abort|error)]
• preferisci ext unsafe c fn per import C non sicuri e chiamali solo all'interno di unsafe { ... }
• fz build --lib emette librerie statiche/condivise più un header installabile e un manifest ABI
  • il contratto backend corrente è solo Cranelift per le build di librerie; --backend llvm esplicito viene rifiutato con un suggerimento di migrazione

Artefatti Documentazione Unsafe

• unsafe è di prima classe tramite unsafe fn e unsafe { ... }
• fz audit unsafe --workspace --json emette .fz/unsafe-map.workspace.json, .fz/unsafe-docs.workspace.json, .fz/unsafe-docs.workspace.md e .fz/unsafe-docs.workspace.html
• campi metadati come reason, invariant, owner, scope, risk_class e proof_ref sono generati dal compilatore e guidati da policy
• il flusso di produzione predefinito è non bloccante per metadati mancanti, a meno che non sia abilitata la policy unsafe rigorosa
• controlli di ambito opzionali rafforzati risiedono in fozzy.toml

Contratto di Validazione Deterministico

Usa questa sequenza per una fiducia rigorosa:

Porta di rilascio rigorosa:

Questo include controlli di integrità delle affermazioni nella documentazione bloccanti per il rilascio tramite scripts/safety_claim_integrity_gate.py.

Esempio: Ciclo di Vita del Test Nativo

Ispeziona direttamente gli artefatti del test nativo emessi:

• artifacts/demo.trace.native.trace.json
• artifacts/demo.trace.report.json
• artifacts/demo.trace.timeline.json quando gli artefatti ricchi sono abilitati
• artifacts/demo.trace.manifest.json

I manifest dei test nativi sono input di prima classe per trace verify / replay / ci per le esecuzioni di test nativi registrate. Non sono input di scenario e non partecipano alla shrink dello scenario.

Progetti di Esempio

Tutti gli esempi forniti seguono la convenzione narrativa DX v1:

• src/main.fzy è solo orchestrativo e pone fn main per ultimo
• i test risiedono sotto src/tests/*
• le radici dei moduli di dominio usano mod.fzy

Progetti disponibili:

• examples/agent_runtime
• examples/context_runtime
• examples/minimal_runtime
• examples/service_app
• examples/fullstack
• examples/robust_cli
• examples/live_server

Validazione e flussi di progetto:

Se stai contribuendo da un checkout invece di installare una build di rilascio, usa cargo run -q -p fz -- <args> come fallback solo sorgente.

Tracciamento del Piano

Mantieni aggiornati questi documenti di consegna con versione durante l'implementazione:

• PLAN.md
• FEATURES-TO-SHIP.md