fzy

a systems programming language prioritizing verifiable correctness, determinism, and performance

Install

Recommended install:

That installs fz to ~/.local/bin, updates PATH if needed, and verifies the install with fz version and fz env.

Source fallback:

Quick Look

Want the fastest overview? Open fzl-showcase.html with open fzl-showcase.html, skim WHYFZY.md for the product argument, then use the sample below as a compact executable sketch.

For broader language coverage, use CODE.md, examples/, and the browser-friendly FZL showcase.

Framework packages follow normal package rules: declare them in fozzy.toml under [deps], then import them in source with use fzbounds;, use fzweb;, and similar package names. Direct source checks such as fz check src/services/mod.fzy --json now validate through the owning package context, so dependency imports and sibling modules behave the same way they do in full-project checks.

What fzy Contains

• fz: compiler CLI for build, run, test, verify, docs, IR, RPC, headers, ABI checks, and more
• built-in formatting and docs generation: fz fmt, fz doc gen
• front-end and IR pipeline: crates/parser, crates/ast, crates/hir, crates/fir
• verifier and safety enforcement: crates/verifier
• deterministic runtime primitives: crates/runtime
• driver and artifact orchestration: crates/driver
• executable Fozzy scenarios: tests/*.fozzy.json

Current State

Implemented and validated today:

• general-purpose systems-language scope, not a niche single-domain tool
• safe by default, with explicit unsafe islands, compiler-generated unsafe inventory/docs, and opt-in manual memory management via alloc(...) / free(...)
• real runtime defer semantics across normal code and unsafe { ... } islands, so deterministic cleanup is enforced rather than merely documented
• verifier-enforced ownership, borrow, capability, FFI, and native-lowerability rules
• explicit manual memory management is supported inside that model, with ownership-aware alloc(...) / free(...) flows and verifier-visible lifecycle checks
• deterministic trace, replay, and scheduler validation as normal production gates
• host-backed confidence paths for filesystem, process, and HTTP behavior
• deterministic scheduler modes: fifo, random, coverage_guided
• decision artifacts for async, thread, and RPC execution
• RPC frame events: rpc_send, rpc_recv, rpc_deadline, rpc_cancel
• explore and shrink metadata for replay/minimization workflows
• language-native scenario generation from parsed test blocks
• recursive multi-file module loading from mod declarations
• C header generation from exported pubext c fn signatures
• RPC schema, client, and server stub generation via fz rpc gen
• modern language/runtime surface across ADTs, pattern matching, traits, generics, typed domain modeling, process, terminal, logging, filesystem/path, boundary JSON, and outbound streaming HTTP
• production crypto/security surface via core.crypto and core.security, including secure random, hashing, HMAC, constant-time compare, and URL-safe encodings
• fzweb production web framework modules for app routing, cookies, sessions, multipart uploads, persistence, SSE, websockets, and OpenAPI export
• fz run executes native output directly with live text streaming or JSON capture
• LLVM and Cranelift native backends with parity-oriented validation
• direct-memory release gates:
  • python3 scripts/direct_memory_architecture_gate.py
  • python3 scripts/direct_memory_perf_gate.py
• production GPU surface through core.gpu, with live Metal execution on Apple plus shared spirv/nvptx adapter contracts

Production Claims

fzy is set up to support these production claims today:

• the shipped safe-language surface is memory-safe by default within the documented verifier/compiler rule scope, with explicit audited unsafe boundaries and opt-in ownership-tracked manual memory management
• internal compiler/runtime/tooling semantics remain a typed source of truth, with JSON reserved for external boundaries, generated artifacts, and operator-facing machine output
• alloc(...) / free(...) stay in safe code when the compiler can still verify ownership, provenance, and cleanup execution
• verifiable correctness through the verifier, diagnostics, deterministic testing, replay, and CI artifacts
• deterministic execution through recorded traces, replay, and scheduler control
• general-purpose systems coverage across async/tasks, RPC, ADTs, traits/generics, process control, terminal I/O, logging, filesystem/path, typed internal state, boundary JSON, and streaming HTTP
• production web/service coverage through fzweb plus security primitives that keep session/cookie/auth flows inside the supported runtime surface

See also:

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

Build And Test

Core CLI

VS Code integration lives in tooling/vscode and targets fz lsp serve.

Runtime defaults and surfaced behavior:

• host bind default: 127.0.0.1
• port default: 8787
• effective bind target is printed on successful listen
• .env or FZ_DOTENV_PATH is loaded once before env/HTTP operations
• text logs are the default; JSON logs are opt-in via log.set_json(1)
• standard library surface includes core.process, core.term, core.thread, core.log, core.text, core.io, core.path, and core.util
• terminal-safe string escapes, structured log fields, typed collection builders, boundary-JSON helpers, and map-backed object literals are first-class
• process helpers support argv/env builders plus spawn/run flows with wait/stdout/stderr/exit inspection
• core.crypto and core.security cover secure random, digests, HMAC, URL-safe encodings, and constant-time comparisons for production auth/session flows
• fzweb ships concern-grouped framework modules plus built-in routes for health, readiness, metrics, inspect, search, cookies, sessions, uploads, events, websockets, item CRUD, OpenAPI, and static assets

Deterministic Artifacts

With fz test <file.fzy> --det --record artifacts/name.trace.json --json, the driver emits:

• *.trace.json: deterministic execution trace
• *.timeline.json: schedule decisions
• *.report.json: summary, findings, and failure grouping
• *.explore.json: schedule candidates and scenario priorities
• *.shrink.json: deterministic shrink hints
• *.scenarios/ and *.scenarios.json: generated language-native scenarios
• *.manifest.json: artifact map including the primary scenario path

Native CLI Surface

Canonical authoring split:

• core.process, core.term, core.text: argv and terminal UX
• core.log: logging policy and structured output
• core.io, core.path: filesystem discovery and path assembly
• proc.*: child-process execution

Example:

EOF is explicit:

• empty line: term.read_line() == "" and term.stdin_eof() == 0
• EOF: term.read_line() == "" and term.stdin_eof() == 1

For serious CLI/runtime work, use both the compiler-integrated launcher and the built binary when exact terminal behavior matters.

Native Backend Policy

• supported backends: cranelift and llvm
• selection order: explicit --backend, then FZ_NATIVE_BACKEND, then profile default
• profile defaults: dev -> cranelift, release -> llvm

Dependency Locking + Vendor

• project builds enforce fozzy.lock drift checks for path dependencies
• refresh lock state with fz vendor [project] --json
• vendor output includes fozzy.lock and vendor/fozzy-vendor.json
• spec: docs/dependency-locking-v1.md

ABI Compatibility Gate

fz abi-check enforces:

• schema validity
• package identity
• panic boundary compatibility
• baseline export presence and signature immutability
• baseline contract immutability
• symbol version non-regression

Additive exports are allowed.

C Interop

• guide: docs/c-interop-production-v1.md
• every exported pubext c fn requires #[ffi_panic(abort|error)]
• prefer ext unsafe c fn for unsafe C imports and call them only inside unsafe { ... }
• fz build --lib emits static/shared libraries plus an installable header and ABI manifest
  • current backend contract is Cranelift-only for library builds; explicit --backend llvm is rejected with a migration hint

Unsafe Docs Artifacts

• unsafe is first-class via unsafe fn and unsafe { ... }
• fz audit unsafe --workspace --json emits .fz/unsafe-map.workspace.json, .fz/unsafe-docs.workspace.json, .fz/unsafe-docs.workspace.md, and .fz/unsafe-docs.workspace.html
• metadata fields such as reason, invariant, owner, scope, risk_class, and proof_ref are compiler-generated and policy-driven
• the default production flow is non-blocking for missing metadata unless strict unsafe policy is enabled
• optional hardened scope controls live in fozzy.toml

Deterministic Validation Contract

Use this sequence for strict confidence:

Strict release gate:

This includes release-blocking docs claim-integrity checks via scripts/safety_claim_integrity_gate.py.

Example: Native Test Lifecycle

Inspect the emitted native test artifacts directly:

• artifacts/demo.trace.native.trace.json
• artifacts/demo.trace.report.json
• artifacts/demo.trace.timeline.json when rich artifacts are enabled
• artifacts/demo.trace.manifest.json

Native test manifests are first-class trace verify / replay / ci inputs for recorded native test runs. They are not scenario inputs and do not participate in scenario shrink.

Example Projects

All shipped examples follow the v1 narrative DX convention:

• src/main.fzy is orchestration-only and places fn main last
• tests live under src/tests/*
• domain module roots use mod.fzy

Available projects:

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

Validation and project flows:

If you are contributing from a checkout instead of installing a release build, use cargo run -q -p fz -- <args> as a source-only fallback.

Plan Tracking

Keep these versioned delivery documents updated during implementation:

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