fzy (fozzylang)

Allzweck-Systemsprache und Produktionstoolchain mit einer standardmäßig speichersicheren ausgelieferten sicheren Sprachoberfläche, verifizierbarer Korrektheit, deterministischer Ausführung und eingebautem wiederholungsorientierten Debugging.

fzy liefert eine Produktions-CLI, fz, sowohl für Compiler-Workflows als auch für deterministische Validierung. Korrektheit, Determinismus, Wiederholung, Vorfallartefakte und Produktionsnachweise sind Teil des normalen Workflows und kein nachträglicher Einfall. Für eine kurze visuelle Tour durch die Sprache öffnen Sie die mitgelieferte FZL-Showcase in Ihrem Browser mit open fzl-showcase.html. Für die kurze Begründung, warum Sie es wählen sollten, siehe WHYFZY.md.

Die Repository-Architekturpolitik ist intern typisiert und JSON nur an echten Grenzen.

Starte hier

• Installation: INSTALL.md
• Vollständiges Handbuch: USAGE.md
• Warum fzy: WHYFZY.md
• Syntax- und Befehlsbeispiele: CODE.md
• Produktionsworkflow: docs/production-workflow-v1.md
• GPU-Programmierung und -Validierung: docs/gpu-v1.md
• Sicherheits- und Vertrauensmodell: docs/system-safety-trust-model-v1.md
• Unsafe-Autorentätigkeit: docs/unsafe-contract-authoring-v1.md
• Stabilitätsstufen: docs/language-stability-v1.md
• Vererbung der Workspace-Richtlinie: docs/workspace-policy-v1.md
• Betriebliche Einblicke: docs/operational-insights-v1.md
• fzyllm: saint0x/fzyllm

Installation

Empfohlene Installation:

curl -fsSL https://raw.githubusercontent.com/saint0x/fzy/main/install.sh | sh

Das installiert fz nach ~/.local/bin, aktualisiert bei Bedarf den PATH und verifiziert die Installation mit fz version und fz env.

Quell-Fallback:

curl -fsSL https://raw.githubusercontent.com/saint0x/fzy/main/install.sh | sh -s -- --from-source

Kurzer Überblick

Möchten Sie den schnellsten Überblick? Öffnen Sie fzl-showcase.html mit open fzl-showcase.html, überfliegen Sie WHYFZY.md für das Produktargument und verwenden Sie dann das folgende Beispiel als kompakte ausführbare Skizze.

use core.log;
use core.path;
use core.process;
use core.time;

enum Mode {
    Fast,
    Safe,
}

trait Scorer {
    fn score(endpoint: Url) -> i32;
}

struct HttpScorer {}

impl Scorer for HttpScorer {
    fn score(endpoint: Url) -> i32 {
        discard endpoint;
        return 7;
    }
}

struct Config<TEndpoint> {
    retries: i32,
    endpoint: TEndpoint,
    mode: Mode,
}

fn weight(mode: Mode) -> i32 {
    match mode {
        Mode::Fast => return 3,
        Mode::Safe => return 1,
        _ => return 1,
    }
}

async fn boost(v: i32) -> i32 {
    checkpoint()
    return v + 1
}

fn normalize<T: Scorer>(cfg: Config<Url>) -> i32 {
    return weight(cfg.mode) + T.score(cfg.endpoint)
}

async fn run_once(cfg: Config<Url>) -> i32 {
    let base = normalize<HttpScorer>(cfg)
    return await boost(base)
}

fn main() -> i32 {
    let cfg = Config { retries: 4, endpoint: url.parse("https://example.test"), mode: Mode::Fast }
    let now = time.now()
    let out_path = path.join("tmp", "score.log")
    let mode = process.argv_or(1, "showcase")
    let score = normalize<HttpScorer>(cfg)
    log.info("snippet.run", out_path)
    discard mode
    discard run_once
    if score + now > 0 then return score
    return score
}

Für eine breitere Sprachabdeckung verwenden Sie CODE.md, examples/ und die browserfreundliche FZL-Showcase.

Framework-Pakete folgen normalen Paketregeln: Deklarieren Sie sie in fozzy.toml unter [deps] und importieren Sie sie dann im Quellcode mit use fzbounds;, use fzweb; und ähnlichen Paketnamen. Direkte Quellprüfungen wie fz check src/services/mod.fzy --json validieren jetzt über den Kontext des Besitzerpakets, sodass sich Abhängigkeitsimporte und Geschwistermodule genauso verhalten wie bei Vollprojektprüfungen.

Was fzy enthält

• fz: Compiler-CLI für Build, Run, Test, Verify, Docs, IR, RPC, Header, ABI-Prüfungen und mehr
• integrierte Formatierung und Dokumentationsgenerierung: fz fmt, fz doc gen
• Frontend- und IR-Pipeline: crates/parser, crates/ast, crates/hir, crates/fir
• Verifizierer und Sicherheitsdurchsetzung: crates/verifier
• deterministische Laufzeitprimitive: crates/runtime
• Treiber und Artefaktorchestrierung: crates/driver
• ausführbare Fozzy-Szenarien: tests/*.fozzy.json

Aktueller Stand

Implementiert und heute validiert:

• Allzweck-Systemsprachenumfang, kein Nischenwerkzeug für eine einzelne Domäne
• standardmäßig sicher, mit expliziten unsicheren Inseln, compiler-generierten unsicheren Inventaren/Dokumenten und optionalem manuellen Speichermanagement über alloc(...) / free(...)
• echte Laufzeit-defer-Semantik über normalen Code und unsafe { ... }-Inseln hinweg, sodass deterministische Bereinigung erzwungen und nicht nur dokumentiert wird
• vom Verifizierer erzwungene Besitz-, Ausleihe-, Fähigkeits-, FFI- und native Absenkungsregeln
• explizites manuelles Speichermanagement wird innerhalb dieses Modells unterstützt, mit besitzbewussten alloc(...) / free(...)-Abläufen und für den Verifizierer sichtbaren Lebenszyklusprüfungen
• deterministische Ablaufverfolgung, Wiederholung und Scheduler-Validierung als normale Produktionsgates
• hostgestützte Vertrauenspfade für Dateisystem-, Prozess- und HTTP-Verhalten
• deterministische Scheduler-Modi: fifo, random, coverage_guided
• Entscheidungsartefakte für asynchrone Ausführung, Thread- und RPC-Ausführung
• RPC-Frame-Ereignisse: rpc_send, , ,

Produktionsansprüche

fzy ist darauf ausgelegt, heute diese Produktionsansprüche zu unterstützen:

• Die ausgelieferte sichere Sprachoberfläche ist standardmäßig speichersicher innerhalb des dokumentierten Verifizierer/Compiler-Regelumfangs, mit expliziten geprüften unsicheren Grenzen und optionalem, besitzverfolgtem manuellem Speichermanagement
• Interne Compiler-/Laufzeit-/Tooling-Semantik bleibt eine typisierte Quelle der Wahrheit, wobei JSON für externe Grenzen, generierte Artefakte und bedienerorientierte Maschinenausgabe reserviert ist
• alloc(...) / free(...) bleiben in sicherem Code, wenn der Compiler weiterhin Besitz, Herkunft und Bereinigungsausführung verifizieren kann
• Verifizierbare Korrektheit durch Verifizierer, Diagnostik, deterministisches Testen, Wiederholung und CI-Artefakte
• Deterministische Ausführung durch aufgezeichnete Ablaufverfolgungen, Wiederholung und Scheduler-Steuerung
• Allzweck-Systemabdeckung über Async/Tasks, RPC, ADTs, Traits/Generics, Prozesssteuerung, Terminal-I/O, Logging, Dateisystem/Pfad, typisierter interner Zustand, Grenz-JSON und Streaming-HTTP
• Produktions-Web-/Service-Abdeckung durch fzweb plus Sicherheitsprimitive, die Session-/Cookie-/Auth-Abläufe innerhalb der unterstützten Laufzeitoberfläche halten

Siehe auch:

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

Build und Test

cargo check --workspace
cargo test --workspace

Kern-CLI

# Ein Projekt im aktuellen Verzeichnis oder in einem Zielpfad erstellen
fz init [path] [--name package] [--template minimal|rust|ts] [--with run,fuzz,explore,memory,host|all] [--force]

# Quellcode/Projekt bauen
fz build [path] [--release] [--lib] [--threads N] [--backend llvm|cranelift] [--pgo-generate|--pgo-use file] [-l lib] [-L path] [-framework name] [--json]

# Quellcode/Projekt oder .fozzy-Szenario ausführen
fz run [path] [--det] [--strict-verify] [--seed N] [--record path] [--host-backends] [--backend llvm|cranelift] [--max-seconds N] [--exit-on-healthcheck URL] [--smoke-http URL] [-- <args>] [--json]

# Quellcode/Projekt oder .fozzy-Szenario testen
fz test [path] [--det] [--strict-verify] [--sched fifo|random|coverage_guided] [--seed N] [--record path] [--backend llvm|cranelift] [--filter substring] [--json]

# Überprüfen/Prüfen/Dokumentation/Tooling
fz fmt [path ...] [--check] [--json]
fz check [path] [--json]
fz verify [path] [--json]
fz lint [path] [--tier production|pedantic|compat] [--json]
fz dx-check [project] [--strict] [--json]
fz spec-check [--json]
fz emit-ir [path] [--json]
fz perf [--artifact artifacts/bench_core_rust_vs_fzy.json] [--json]
fz stability-dashboard [--json]
fz parity [path] [--seed N] [--json]
fz audit unsafe [path] [--workspace] [--json]
fz vendor [project] [--json]
fz abi-check <current.abi.json> --baseline <baseline.abi.json> [--json]
fz debug-check [path] [--json]
fz pgo merge [path] [--out file] [--json]
fz lsp diagnostics [path] [--json]
fz lsp definition <path> <symbol> [--json]
fz lsp hover <path> <symbol> [--json]
fz lsp rename <path> <from> <to> [--json]
fz lsp smoke [path] [--json]
fz lsp serve [--path <workspace>] [--json]
fz map suites [--root dir] [--scenario-root dir] [--profile pedantic|production|compat] [--json]
fz artifacts ls latest [--json]
fz report show latest [--format json|text] [--json]
fz usage [--json]
fz env [--json]
fz version [--json]
fz inspect stdlib <module> [--json]
fz schema [--json]
fz validate <scenario> [--json]
fz trace verify <trace> [--strict] [--json]
fz replay <trace> [--json]
fz shrink <trace> [--json]
fz ci <trace> [--json]
fz trace-native <trace.fozzy> [--out path] [--json]

# FFI / RPC / Docs-Ausgaben
fz headers [path] [--out path] [--json]
fz rpc gen [path] [--out-dir dir] [--json]
fz doc gen [path] [--format json|html|markdown] [--out path] [--reference path] [--json]

Die VS-Code-Integration befindet sich in tooling/vscode und zielt auf fz lsp serve.

Standardwerte der Laufzeit und offengelegtes Verhalten:

• Standard-Host-Bindung: 127.0.0.1
• Standard-Port: 8787
• Das effektive Bindungsziel wird bei erfolgreichem listen ausgegeben.
• .env oder FZ_DOTENV_PATH wird einmal vor Umgebungs-/HTTP-Operationen geladen.
• Textlogs sind die Voreinstellung; JSON-Logs sind optional über log.set_json(1).
• Die Standardbibliotheksoberfläche umfasst core.process, core.term, core.thread, core.log, core.text, core.io, core.path und core.util.

Deterministische Artefakte

Mit fz test <file.fzy> --det --record artifacts/name.trace.json --json erzeugt der Treiber:

• *.trace.json: deterministische Ausführungsablaufverfolgung
• *.timeline.json: Planungsentscheidungen
• *.report.json: Zusammenfassung, Ergebnisse und Fehlergruppierung
• *.explore.json: Planungskandidaten und Szenarioprioritäten
• *.shrink.json: deterministische Schrumpfungshinweise
• *.scenarios/ und *.scenarios.json: generierte sprachnative Szenarien
• *.manifest.json: Artefaktkarte mit dem primären Szenariopfad

Native CLI-Oberfläche

Kanonische Aufteilung der Autorentätigkeit:

• core.process, core.term, core.text: argv und Terminal-Benutzererfahrung
• core.log: Logging-Richtlinie und strukturierte Ausgabe
• core.io, core.path: Dateisystemerkundung und Pfadzusammenstellung
• proc.*: Ausführung von Unterprozessen

Beispiel:

use core.log;
use core.process;
use core.term;
use core.text;

fn main() -> i32 {
    let mode = process.argv_or(1, "serve")
    discard log.set_sink_name("stderr")
    discard log.set_level_name("warn")
    discard term.transcript_kv("mode", mode, 8)
    if term.is_interactive() == 1 {
        discard term.eprint_line(str.concat("interactive=", str.from_i32(term.is_interactive())))
    }
    discard term.print_line(text.indent("ready\nwaiting", "  "))
    return 0
}

EOF ist explizit:

• leere Zeile: term.read_line() == "" und term.stdin_eof() == 0
• EOF: term.read_line() == "" und term.stdin_eof() == 1

Für ernsthafte CLI-/Laufzeitarbeit verwenden Sie sowohl den compilerintegrierten Launcher als auch das gebaute Binary, wenn exaktes Terminalverhalten wichtig ist.

Native Backend-Richtlinie

• unterstützte Backends: cranelift und llvm
• Auswahlreihenfolge: explizit --backend, dann FZ_NATIVE_BACKEND, dann Profilvorgabe
• Profilvorgaben: dev -> cranelift, release -> llvm

Abhängigkeitssperrung + Vendor

• Projekt-Builds erzwingen fozzy.lock-Abweichungsprüfungen für Pfadabhängigkeiten.
• Sperrzustand mit fz vendor [project] --json aktualisieren.
• Vendor-Ausgabe enthält fozzy.lock und vendor/fozzy-vendor.json.
• Spezifikation: docs/dependency-locking-v1.md

ABI-Kompatibilitäts-Gate

fz abi-check erzwingt:

• Schema-Gültigkeit
• Paketidentität
• Panikgrenzkompatibilität
• Vorhandensein von Basislinien-Exporten und Signaturunveränderlichkeit
• Unveränderlichkeit des Basislinienvertrags
• Symbolversions-Nichtregression

Additive Exporte sind erlaubt.

C-Interop

• Anleitung: docs/c-interop-production-v1.md
• Jede exportierte pubext c fn erfordert #[ffi_panic(abort|error)]
• Bevorzugen Sie ext unsafe c fn für unsichere C-Importe und rufen Sie sie nur innerhalb von unsafe { ... } auf.
• fz build --lib gibt statische/geteilte Bibliotheken sowie einen installierbaren Header und ein ABI-Manifest aus.
  • Der aktuelle Backend-Vertrag ist Cranelift-only für Bibliotheks-Builds; explizites --backend llvm wird mit einem Migrationshinweis abgelehnt.

Unsichere Dokumentationsartefakte

• Unsafe ist erstklassig über unsafe fn und unsafe { ... }.
• fz audit unsafe --workspace --json erzeugt .fz/unsafe-map.workspace.json, .fz/unsafe-docs.workspace.json, .fz/unsafe-docs.workspace.md und .fz/unsafe-docs.workspace.html.
• Metadatenfelder wie reason, invariant, owner, scope, risk_class und proof_ref werden vom Compiler generiert und sind richtliniengesteuert.
• Der standardmäßige Produktionsablauf blockiert nicht bei fehlenden Metadaten, es sei denn, eine strenge Unsafe-Richtlinie ist aktiviert.

Deterministischer Validierungsvertrag

Verwenden Sie diese Sequenz für strenges Vertrauen:

# 1) Determinism audit first
fz doctor --deep --scenario tests/run.pass.fozzy.json --runs 5 --seed 42 --json

# 2) Strict deterministic tests
fz test --det --strict-verify tests/run.pass.fozzy.json tests/memory.pass.fozzy.json --json

# 3) Record one real trace
fz run tests/run.pass.fozzy.json --det --record artifacts/trace.fozzy --json

# 4) Validate replay pipeline
fz trace verify artifacts/trace.fozzy --strict --json
fz replay artifacts/trace.fozzy --json
fz ci artifacts/trace.fozzy --json

# 5) Host-backed confidence pass
fz run tests/host.pass.fozzy.json --host-backends --json

Strenges Freigabe-Gate:

./scripts/ship_release_gate.sh

Dies beinhaltet freigabeblockierende Prüfungen der Dokumentationsanspruchs-Integrität über scripts/safety_claim_integrity_gate.py.

Beispiel: Nativer Test-Lebenszyklus

cat >/tmp/demo.fzy <<'FZY'
test "alpha" {}
test "beta" nondet {}
rpc Ping(req: PingReq) -> PingRes;
async fn worker() -> i32 {}
fn main() -> i32 {
    timeout(1)
    return 0
}
FZY

fz test /tmp/demo.fzy --det --sched random --seed 13 --record artifacts/demo.trace.json --json

Untersuchen Sie die erzeugten nativen Testartefakte direkt:

• artifacts/demo.trace.native.trace.json
• artifacts/demo.trace.report.json
• artifacts/demo.trace.timeline.json, wenn umfangreiche Artefakte aktiviert sind
• artifacts/demo.trace.manifest.json

Native Testmanifeste sind erstklassige Eingaben für trace verify / replay / ci für aufgezeichnete native Testläufe. Sie sind keine Szenario-Eingaben und nehmen nicht an der Szenario-shrink teil.

Beispielprojekte

Alle ausgelieferten Beispiele folgen der v1 narrativen DX-Konvention:

• src/main.fzy ist nur zur Orchestrierung und platziert fn main zuletzt
• Tests befinden sich unter src/tests/*
• Domänen-Modulwurzeln verwenden mod.fzy

Verfügbare Projekte:

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

Validierungs- und Projektabläufe:

fz dx-check examples/fullstack --strict --json

fz check examples/fullstack --json
fz build examples/fullstack --backend cranelift --json
fz build examples/fullstack --release --backend llvm --json
fz run examples/fullstack --backend cranelift --json
fz test examples/fullstack --det --seed 41 --backend llvm --json
fz headers examples/fullstack --json
fz abi-check examples/fullstack/include/fullstack.abi.json --baseline examples/fullstack/include/fullstack.abi.json --json

fz dx-check examples/robust_cli --strict --json
fz build examples/robust_cli --backend cranelift --json
fz run examples/robust_cli --backend llvm --json
fz test examples/robust_cli --det --seed 55 --backend cranelift --json

fz dx-check examples/live_server --strict --json
fz build examples/live_server --backend cranelift --json
fz run examples/live_server --backend llvm --json
fz test examples/live_server --det --seed 77 --backend cranelift --record artifacts/live_server.stats.trace.json --rich-artifacts --json

fz run tests/live.server.interhttp.fozzy.json --host-backends --json

Wenn Sie von einem Checkout aus beitragen, anstatt einen Release-Build zu installieren, verwenden Sie cargo run -q -p fz -- <args> als quellbasierten Fallback.

Planverfolgung

Halten Sie diese versionierten Lieferdokumente während der Implementierung auf dem neuesten Stand:

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