fzy (fozzylang)

通用系统语言及生产工具链，具有默认内存安全的已发布安全语言表面、可验证的正确性、确定性执行以及内置的以重放优先的调试功能。

fzy 提供一个生产 CLI fz，用于编译工作流和确定性验证。正确性、确定性、重放、事件工件和生产证据是正常工作流的一部分，而非事后补救。如需快速了解语言的可视化概览，请在浏览器中打开随附的 FZL 展示：open fzl-showcase.html。关于为何选择它的简短论证，请参阅 WHYFZY.md。

仓库架构策略在内部是类型化的，在真实边界处仅使用 JSON。

从这里开始

安装：INSTALL.md
完整手册：USAGE.md
为什么选择 fzy：WHYFZY.md
语法和命令示例：CODE.md
生产工作流：docs/production-workflow-v1.md
GPU 编程与验证：docs/gpu-v1.md
安全性与信任模型：docs/system-safety-trust-model-v1.md
不安全编写：docs/unsafe-contract-authoring-v1.md
稳定性层级：docs/language-stability-v1.md
工作区策略继承：docs/workspace-policy-v1.md
运维洞察：docs/operational-insights-v1.md
fzyllm：saint0x/fzyllm

安装

推荐安装方式：

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

这会安装 fz 到 ~/.local/bin，如需自动更新 PATH，并验证安装（fz version 和 fz env）。

源码回退方式：

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

快速概览

想要最快的概述？用 open fzl-showcase.html 打开 fzl-showcase.html，快速浏览 WHYFZY.md 了解产品论证，然后将下面的示例作为紧凑的可执行草稿。

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
}

更广泛的语言覆盖请使用 CODE.md、examples/ 以及浏览器友好的 FZL 展示。

框架包遵循普通包规则：在 fozzy.toml 的 [deps] 下声明它们，然后在源码中用 use fzbounds;、use fzweb; 等包名导入。直接源码检查（例如 fz check src/services/mod.fzy --json）现在通过所属包上下文进行验证，因此依赖导入和同级模块的行为与完整项目检查中相同。

fzy 包含的内容

fz：编译器 CLI，用于构建、运行、测试、验证、文档、IR、RPC、头文件、ABI 检查等
内置格式化和文档生成：fz fmt、fz doc gen
前端和 IR 流水线：crates/parser、crates/ast、crates/hir、crates/fir
验证器和安全执行：crates/verifier
确定性运行时原语：crates/runtime
驱动和工件编排：crates/driver
可执行的 Fozzy 场景：tests/*.fozzy.json

当前状态

目前已实现并验证：

通用系统语言范畴，而非狭窄的单域工具
默认安全，带有显式的不安全孤岛、编译器生成的不安全清单/文档，以及通过 alloc(...) / free(...) 选择加入的手动内存管理
在常规代码和 unsafe { ... } 孤岛中都有真正的运行时 defer 语义，从而强制确定性清理而非仅仅文档记录
验证器强制的所有权、借用、能力、FFI 和原生降级规则
在该模型内支持显式手动内存管理，具有所有权感知的 alloc(...) / free(...) 流程和验证器可见的生命周期检查
确定性跟踪、重放和调度器验证作为正常的生产门控
文件系统、进程和 HTTP 行为的主机支持置信路径
确定性调度器模式：fifo、random、coverage_guided
异步、线程和 RPC 执行的决策工件
RPC 帧事件：rpc_send、rpc_recv、rpc_deadline、rpc_cancel
用于重放/最小化工作流的探索和收缩元数据

生产声明

fzy 目前已设定支持以下生产声明：

已发布的安全语言表面在文档化的验证器/编译器规则范围内默认内存安全，具有显式的审计不安全边界和选择加入的所有权跟踪手动内存管理
内部编译器/运行时/工具链语义保持为类型化的真实来源，JSON 保留用于外部边界、生成的工件和面向操作员的机器输出
当编译器仍能验证所有权、来源和清理执行时，alloc(...) / free(...) 保持在安全代码中
通过验证器、诊断、确定性测试、重放和 CI 工件实现可验证的正确性
通过记录的跟踪、重放和调度器控制实现确定性执行
通用系统覆盖面：异步/任务、RPC、ADT、trait/泛型、进程控制、终端 I/O、日志、文件系统/路径、类型化内部状态、边界 JSON 和流式 HTTP
通过 fzweb 以及将会话/cookie/auth 流程保持在支持的运行时表面内的安全原语，实现生产级 Web/服务覆盖

另见：

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

构建与测试

cargo check --workspace
cargo test --workspace

核心 CLI

# 在当前目录或目标路径中搭建项目
fz init [path] [--name package] [--template minimal|rust|ts] [--with run,fuzz,explore,memory,host|all] [--force]

# 构建源码/项目
fz build [path] [--release] [--lib] [--threads N] [--backend llvm|cranelift] [--pgo-generate|--pgo-use file] [-l lib] [-L path] [-framework name] [--json]

# 运行源码/项目或 .fozzy 场景
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]

# 测试源码/项目或 .fozzy 场景
fz test [path] [--det] [--strict-verify] [--sched fifo|random|coverage_guided] [--seed N] [--record path] [--backend llvm|cranelift] [--filter substring] [--json]

# 验证/检查/文档/工具
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 / 文档输出
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]

VS Code 集成位于 tooling/vscode，目标为 fz lsp serve。

运行时默认值和暴露的行为：

主机绑定默认值：127.0.0.1
端口默认值：8787
成功 listen 时打印有效的绑定目标
.env 或 FZ_DOTENV_PATH 在环境/HTTP 操作之前加载一次
文本日志是默认值；JSON 日志通过 log.set_json(1) 选择加入
标准库表面包括 core.process、core.term、core.thread、core.log、core.text、core.io、core.path 和 core.util
终端安全字符串转义、结构化日志字段、类型化集合构建器、边界 JSON 帮助器和映射支持的对象字面量是第一类公民
进程帮助器支持 argv/env 构建器以及带有 wait/stdout/stderr/exit 检查的 spawn/run 流程

确定性工件

使用 fz test <file.fzy> --det --record artifacts/name.trace.json --json 时，驱动会生成：

*.trace.json：确定性执行跟踪
*.timeline.json：调度决策
*.report.json：摘要、发现和失败分组
*.explore.json：调度候选和场景优先级
*.shrink.json：确定性收缩提示
*.scenarios/ 和 *.scenarios.json：生成的语言原生场景
*.manifest.json：包含主场景路径的工件映射

原生 CLI 表面

规范编写拆分：

core.process、core.term、core.text：argv 和终端 UX
core.log：日志策略和结构化输出
core.io、core.path：文件系统发现和路径组装
proc.*：子进程执行

示例：

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 是显式的：

空行：term.read_line() == "" 且 term.stdin_eof() == 0
EOF：term.read_line() == "" 且 term.stdin_eof() == 1

对于严肃的 CLI/运行时工作，当精确的终端行为至关重要时，请使用编译器集成的启动器和构建的二进制文件。

原生后端策略

支持的后端：cranelift 和 llvm
选择顺序：显式 --backend，然后 FZ_NATIVE_BACKEND，最后配置文件默认值
配置文件默认值：dev -> cranelift，release -> llvm

依赖锁定 + Vendor

项目构建强制对路径依赖进行 fozzy.lock 漂移检查
使用 fz vendor [project] --json 刷新锁定状态
vendor 输出包括 fozzy.lock 和 vendor/fozzy-vendor.json
规范：docs/dependency-locking-v1.md

ABI 兼容性门控

fz abi-check 强制：

模式有效性
包标识
panic 边界兼容性
基线导出存在性和签名不可变性
基线契约不可变性
符号版本非回归

允许添加性导出。

C 互操作

指南：docs/c-interop-production-v1.md
每个导出的 pubext c fn 需要 #[ffi_panic(abort|error)]
对于不安全的 C 导入，首选 ext unsafe c fn，并且仅在其内部调用 unsafe { ... }
fz build --lib 生成静态/共享库以及可安装的头文件和 ABI 清单
- 当前后端约定仅对库构建使用 Cranelift；显式 --backend llvm 会被拒绝并带有一个迁移提示

不安全文档工件

不安全通过 unsafe fn 和 unsafe { ... } 成为第一类公民
fz audit unsafe --workspace --json 生成 .fz/unsafe-map.workspace.json、.fz/unsafe-docs.workspace.json、.fz/unsafe-docs.workspace.md 和 .fz/unsafe-docs.workspace.html
元数据字段如 reason、invariant、owner、scope、risk_class 和 proof_ref 由编译器生成，并由策略驱动
默认生产流对于缺失的元数据是非阻塞的，除非启用了严格的不安全策略
可选的强化作用域控制位于 fozzy.toml 中

确定性验证契约

使用以下序列进行严格的置信度验证：

# 1) 首先进行确定性审计
fz doctor --deep --scenario tests/run.pass.fozzy.json --runs 5 --seed 42 --json

# 2) 严格的确定性测试
fz test --det --strict-verify tests/run.pass.fozzy.json tests/memory.pass.fozzy.json --json

# 3) 记录一个真实跟踪
fz run tests/run.pass.fozzy.json --det --record artifacts/trace.fozzy --json

# 4) 验证重放流水线
fz trace verify artifacts/trace.fozzy --strict --json
fz replay artifacts/trace.fozzy --json
fz ci artifacts/trace.fozzy --json

# 5) 主机支持置信通道
fz run tests/host.pass.fozzy.json --host-backends --json

严格发布门控：

./scripts/ship_release_gate.sh

这包括通过 scripts/safety_claim_integrity_gate.py 进行的发布阻塞文档声明完整性检查。

示例：原生测试生命周期

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

直接检查生成的原生测试工件：

artifacts/demo.trace.native.trace.json
artifacts/demo.trace.report.json
artifacts/demo.trace.timeline.json（当启用丰富工件时）
artifacts/demo.trace.manifest.json

原生测试清单是记录的原生测试运行的一等 trace verify / replay / ci 输入。它们不是场景输入，不参与场景 shrink。

示例项目

所有附带的示例都遵循 v1 叙事 DX 约定：

src/main.fzy 仅用于编排，并将 fn main 放在最后
测试位于 src/tests/* 下
领域模块根目录使用 mod.fzy

可用项目：

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

验证和项目流程：

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

如果你是从检出贡献，而不是安装发布版本，请使用 cargo run -q -p fz -- <args> 作为仅源码回退方式。

计划跟踪

在实现过程中保持以下版本化交付文档的更新：

PLAN.md
FEATURES-TO-SHIP.md

最受欢迎

fzy