fzy (fozzylang)

Linguagem de sistemas de propósito geral e toolchain de produção com uma superfície de linguagem segura por padrão, correção verificável, execução determinística e depuração baseada em replay integrada.

O fzy fornece uma CLI de produção, fz, para fluxos de trabalho do compilador e validação determinística. Correção, determinismo, replay, artefatos de incidentes e evidências de produção fazem parte do fluxo de trabalho normal, e não uma reflexão tardia. Para um tour visual rápido da linguagem, abra o FZL showcase enviado no seu navegador com open fzl-showcase.html. Para uma breve argumentação sobre por que você pode escolhê-lo, veja WHYFZY.md.

A política de arquitetura do repositório é tipada internamente e JSON apenas em fronteiras reais.

Comece Aqui

• Instalação: INSTALL.md
• Manual completo: USAGE.md
• Por que fzy: WHYFZY.md
• Exemplos de sintaxe e comandos: CODE.md
• Fluxo de trabalho de produção: docs/production-workflow-v1.md
• Programação e validação de GPU: docs/gpu-v1.md
• Modelo de segurança e confiança: docs/system-safety-trust-model-v1.md
• Criação de módulos inseguros: docs/unsafe-contract-authoring-v1.md
• Níveis de estabilidade: docs/language-stability-v1.md
• Herança de política do workspace: docs/workspace-policy-v1.md
• Insights operacionais: docs/operational-insights-v1.md
• fzyllm: saint0x/fzyllm

Instalar

Instalação recomendada:

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

Isso instala fz em ~/.local/bin, atualiza PATH se necessário e verifica a instalação com fz version e fz env.

Alternativa a partir da fonte:

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

Visão Rápida

Quer a visão geral mais rápida? Abra fzl-showcase.html com open fzl-showcase.html, leia WHYFZY.md para o argumento do produto e depois use o exemplo abaixo como um esboço executável compacto.

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
}

Para uma cobertura mais ampla da linguagem, use CODE.md, examples/ e o FZL showcase compatível com navegadores.

Os pacotes de framework seguem as regras normais de pacotes: declare-os em fozzy.toml sob [deps], depois importe-os no código-fonte com use fzbounds;, use fzweb; e nomes de pacotes semelhantes. Verificações diretas de código-fonte, como fz check src/services/mod.fzy --json, agora validam através do contexto do pacote proprietário, para que importações de dependências e módulos irmãos se comportem da mesma forma que nas verificações de projeto completo.

O que o fzy Contém

• fz: CLI do compilador para build, run, test, verify, docs, IR, RPC, headers, verificação de ABI e muito mais
• Formatação e geração de documentação integradas: fz fmt, fz doc gen
• Pipeline front-end e IR: crates/parser, crates/ast, crates/hir, crates/fir
• Verificador e aplicação de segurança: crates/verifier
• Primitivas de runtime determinísticas: crates/runtime
• Orquestração de driver e artefatos: crates/driver
• Cenários executáveis do Fozzy: tests/*.fozzy.json

Estado Atual

Implementado e validado hoje:

• Escopo de linguagem de sistemas de propósito geral, não uma ferramenta de domínio único e nicho
• Seguro por padrão, com ilhas inseguras explícitas, inventário/documentação de insegurança gerado pelo compilador e gerenciamento manual de memória opcional via alloc(...) / free(...)
• Semântica real de defer em tempo de execução em todo código normal e ilhas unsafe { ... }, para que a limpeza determinística seja aplicada em vez de apenas documentada
• Regras de propriedade, empréstimo, capacidade, FFI e reduzibilidade nativa aplicadas pelo verificador
• Gerenciamento explícito de memória manual é suportado dentro desse modelo, com fluxos alloc(...) / free(...) cientes de propriedade e verificações de ciclo de vida visíveis pelo verificador
• Rastreamento determinístico, replay e validação do escalonador como portões de produção normais
• Caminhos de confiança com suporte do host para comportamento de sistema de arquivos, processo e HTTP
• Modos de escalonador determinísticos: fifo, random, coverage_guided
• Artefatos de decisão para execução assíncrona, threads e RPC
• Eventos de quadro RPC: rpc_send, , ,

Alegações de Produção

O fzy está configurado para suportar estas alegações de produção hoje:

• A superfície de linguagem segura fornecida é segura para memória por padrão dentro do escopo documentado das regras do verificador/compilador, com fronteiras inseguras auditadas explícitas e gerenciamento manual de memória rastreado por propriedade opcional
• A semântica interna do compilador/runtime/ferramentas permanece uma fonte de verdade tipada, com JSON reservado para fronteiras externas, artefatos gerados e saída de máquina para operadores
• alloc(...) / free(...) permanecem em código seguro quando o compilador ainda pode verificar propriedade, proveniência e execução de limpeza
• Correção verificável através do verificador, diagnósticos, testes determinísticos, replay e artefatos de CI
• Execução determinística através de rastreamentos gravados, replay e controle do escalonador
• Cobertura de sistemas de propósito geral abrangendo async/tarefas, RPC, ADTs, traits/genéricos, controle de processo, E/S de terminal, logging, sistema de arquivos/caminho, estado interno tipado, JSON de fronteira e HTTP de streaming
• Cobertura de serviço web de produção através de fzweb mais primitivas de segurança que mantêm fluxos de sessão/cookie/auth dentro da superfície de runtime suportada

Veja também:

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

Build e Teste

cargo check --workspace
cargo test --workspace

CLI Principal

# Scaffold de um projeto no diretório atual ou caminho de destino
fz init [path] [--name package] [--template minimal|rust|ts] [--with run,fuzz,explore,memory,host|all] [--force]

# Build do código-fonte/projeto
fz build [path] [--release] [--lib] [--threads N] [--backend llvm|cranelift] [--pgo-generate|--pgo-use file] [-l lib] [-L path] [-framework name] [--json]

# Executar código-fonte/projeto ou cenário .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]

# Testar código-fonte/projeto ou cenário .fozzy
fz test [path] [--det] [--strict-verify] [--sched fifo|random|coverage_guided] [--seed N] [--record path] [--backend llvm|cranelift] [--filter substring] [--json]

# Verificar/verificar/documentação/ferramentas
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]

# Saídas FFI / RPC / docs
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]

A integração com VS Code está em tooling/vscode e tem como alvo fz lsp serve.

Padrões de runtime e comportamento exposto:

• bind do host padrão: 127.0.0.1
• porta padrão: 8787
• o alvo de bind efetivo é impresso em listen bem-sucedido
• .env ou FZ_DOTENV_PATH é carregado uma vez antes de operações de env/HTTP
• logs de texto são o padrão; logs JSON são opt-in via log.set_json(1)
• a superfície da biblioteca padrão inclui core.process, core.term, core.thread, core.log, core.text, core.io, core.path e core.util

Artefatos Determinísticos

Com fz test <file.fzy> --det --record artifacts/name.trace.json --json, o driver emite:

• *.trace.json: rastreamento de execução determinístico
• *.timeline.json: decisões do escalonador
• *.report.json: resumo, descobertas e agrupamento de falhas
• *.explore.json: candidatos a escalonador e prioridades de cenário
• *.shrink.json: dicas de redução determinísticas
• *.scenarios/ e *.scenarios.json: cenários nativos da linguagem gerados
• *.manifest.json: mapa de artefatos incluindo o caminho do cenário principal

Superfície CLI Nativa

Divisão de criação canônica:

• core.process, core.term, core.text: argv e UX de terminal
• core.log: política de logging e saída estruturada
• core.io, core.path: descoberta de sistema de arquivos e montagem de caminhos
• proc.*: execução de processos filhos

Exemplo:

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 é explícito:

• linha vazia: term.read_line() == "" e term.stdin_eof() == 0
• EOF: term.read_line() == "" e term.stdin_eof() == 1

Para trabalho sério com CLI/runtime, use tanto o lançador integrado ao compilador quanto o binário compilado quando o comportamento exato do terminal for importante.

Política de Backend Nativo

• backends suportados: cranelift e llvm
• ordem de seleção: --backend explícito, depois FZ_NATIVE_BACKEND, depois padrão do perfil
• padrões de perfil: dev -> cranelift, release -> llvm

Bloqueio de Dependências + Vendor

• builds de projeto impõem verificações de desvio de fozzy.lock para dependências de caminho
• atualize o estado do bloqueio com fz vendor [project] --json
• saída do vendor inclui fozzy.lock e vendor/fozzy-vendor.json
• especificação: docs/dependency-locking-v1.md

Portão de Compatibilidade ABI

fz abi-check impõe:

• validade do esquema
• identidade do pacote
• compatibilidade de fronteira de pânico
• presença de exportações de baseline e imutabilidade de assinatura
• imutabilidade de contrato de baseline
• não regressão de versão de símbolo

Exportações aditivas são permitidas.

Interoperabilidade com C

• guia: docs/c-interop-production-v1.md
• toda pubext c fn exportada requer #[ffi_panic(abort|error)]
• prefira ext unsafe c fn para importações C inseguras e chame-as apenas dentro de unsafe { ... }
• fz build --lib emite bibliotecas estáticas/compartilhadas mais um cabeçalho instalável e manifesto ABI
  • o contrato atual do backend é apenas Cranelift para builds de biblioteca; --backend llvm explícito é rejeitado com uma dica de migração

Artefatos de Documentação Insegura

• unsafe é cidadão de primeira classe via unsafe fn e unsafe { ... }
• fz audit unsafe --workspace --json emite .fz/unsafe-map.workspace.json, .fz/unsafe-docs.workspace.json, .fz/unsafe-docs.workspace.md e .fz/unsafe-docs.workspace.html
• campos de metadados como reason, invariant, owner, scope, risk_class e proof_ref são gerados pelo compilador e orientados por política
• o fluxo de produção padrão não bloqueia para metadados ausentes, a menos que a política insegura estrita esteja ativada

Contrato de Validação Determinística

Use esta sequência para confiança estrita:

# 1) Auditoria de determinismo primeiro
fz doctor --deep --scenario tests/run.pass.fozzy.json --runs 5 --seed 42 --json

# 2) Testes determinísticos estritos
fz test --det --strict-verify tests/run.pass.fozzy.json tests/memory.pass.fozzy.json --json

# 3) Gravar um rastreamento real
fz run tests/run.pass.fozzy.json --det --record artifacts/trace.fozzy --json

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

# 5) Passagem de confiança com suporte do host
fz run tests/host.pass.fozzy.json --host-backends --json

Portão de liberação estrito:

./scripts/ship_release_gate.sh

Isso inclui verificações de integridade de alegação de documentação que bloqueiam a liberação via scripts/safety_claim_integrity_gate.py.

Exemplo: Ciclo de Vida de Teste Nativo

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

Inspecione os artefatos de teste nativo emitidos diretamente:

• artifacts/demo.trace.native.trace.json
• artifacts/demo.trace.report.json
• artifacts/demo.trace.timeline.json quando artefatos ricos estão ativados
• artifacts/demo.trace.manifest.json

Manifestos de teste nativo são entradas de primeira classe para trace verify / replay / ci para execuções de teste nativo gravadas. Eles não são entradas de cenário e não participam do shrink de cenário.

Projetos de Exemplo

Todos os exemplos fornecidos seguem a convenção de DX narrativa v1:

• src/main.fzy é apenas orquestração e coloca fn main por último
• testes residem em src/tests/*
• raízes de módulo de domínio usam mod.fzy

Projetos disponíveis:

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

Validação e fluxos de projeto:

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

Se você estiver contribuindo de um checkout em vez de instalar um lançamento, use cargo run -q -p fz -- <args> como alternativa apenas com fonte.

Acompanhamento de Plano

Mantenha estes documentos de entrega versionados atualizados durante a implementação:

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