fzy (fozzylang)

Lenguaje de sistemas de propósito general y cadena de herramientas de producción con una superficie de lenguaje seguro incorporado, corrección verificable, ejecución determinista y depuración basada en repetición integrada.

fzy incluye una CLI de producción, fz, tanto para flujos de trabajo del compilador como para validación determinista. La corrección, el determinismo, la repetición, los artefactos de incidentes y la evidencia de producción son parte del flujo de trabajo normal, no un añadido posterior. Para un recorrido visual rápido del lenguaje, abre el FZL showcase incluido en tu navegador con open fzl-showcase.html. Para un breve argumento de por qué podrías elegirlo, consulta WHYFZY.md.

La política de arquitectura del repositorio está tipada internamente y solo en JSON en los límites reales.

Comenzar aquí

• Instalación: INSTALL.md
• Manual completo: USAGE.md
• Por qué fzy: WHYFZY.md
• Sintaxis y ejemplos de comandos: CODE.md
• Flujo de trabajo de producción: docs/production-workflow-v1.md
• Programación y validación de GPU: docs/gpu-v1.md
• Modelo de seguridad y confianza: docs/system-safety-trust-model-v1.md
• Autoría no segura: docs/unsafe-contract-authoring-v1.md
• Niveles de estabilidad: docs/language-stability-v1.md
• Herencia de políticas del espacio de trabajo: docs/workspace-policy-v1.md
• Información operativa: docs/operational-insights-v1.md
• fzyllm: saint0x/fzyllm

Instalación

Instalación recomendada:

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

Esto instala fz en ~/.local/bin, actualiza PATH si es necesario y verifica la instalación con fz version y fz env.

Alternativa desde el código fuente:

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

Vista rápida

¿Quieres la visión general más rápida? Abre fzl-showcase.html con open fzl-showcase.html, hojea WHYFZY.md para el argumento del producto, y luego usa la muestra a continuación como un bosquejo ejecutable 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 una cobertura más amplia del lenguaje, usa CODE.md, examples/, y el FZL showcase amigable para el navegador.

Los paquetes del framework siguen las reglas normales de paquetes: decláralos en fozzy.toml bajo [deps], luego impórtalos en el código con use fzbounds;, use fzweb; y nombres de paquete similares. Las comprobaciones directas de código fuente como fz check src/services/mod.fzy --json ahora validan a través del contexto del paquete propietario, por lo que las importaciones de dependencias y los módulos hermanos se comportan igual que en las comprobaciones de proyecto completo.

Lo que contiene fzy

• fz: CLI del compilador para compilar, ejecutar, probar, verificar, documentar, IR, RPC, encabezados, comprobaciones ABI y más
• formato y generación de documentación integrados: fz fmt, fz doc gen
• front-end y pipeline IR: crates/parser, crates/ast, crates/hir, crates/fir
• verificador y aplicación de seguridad: crates/verifier
• primitivas de tiempo de ejecución deterministas: crates/runtime
• controlador y orquestación de artefactos: crates/driver
• escenarios Fozzy ejecutables: tests/*.fozzy.json

Estado actual

Implementado y validado hoy:

• alcance de lenguaje de sistemas de propósito general, no una herramienta de nicho de un solo dominio
• seguro por defecto, con islas explícitas no seguras, inventario/documentación de no seguridad generado por el compilador y gestión manual de memoria opcional mediante alloc(...) / free(...)
• semántica real de defer en tiempo de ejecución en código normal e islas unsafe { ... }, por lo que la limpieza determinista se aplica en lugar de solo documentarse
• reglas de propiedad, préstamo, capacidad, FFI y capacidad de reducción nativa verificadas por el verificador
• la gestión manual explícita de memoria es compatible dentro de ese modelo, con flujos de alloc(...) / free(...) conscientes de la propiedad y comprobaciones de ciclo de vida visibles para el verificador
• traza determinista, repetición y validación del planificador como puertas de producción normales
• rutas de confianza respaldadas por el host para el comportamiento del sistema de archivos, procesos y HTTP
• modos de planificador deterministas: fifo, random, coverage_guided
• artefactos de decisión para ejecución asíncrona, de hilos y RPC
• eventos de trama RPC: rpc_send, , ,

Afirmaciones de producción

fzy está configurado para respaldar estas afirmaciones de producción hoy:

• la superficie de lenguaje seguro incluida es segura en cuanto a memoria por defecto dentro del alcance de las reglas documentadas del verificador/compilador, con límites no seguros auditados explícitos y gestión manual de memoria rastreada por propiedad optativa
• la semántica interna del compilador/tiempo de ejecución/herramientas sigue siendo una fuente de verdad tipada, con JSON reservado para límites externos, artefactos generados y salida de máquina orientada al operador
• alloc(...) / free(...) permanecen en código seguro cuando el compilador aún puede verificar la propiedad, la procedencia y la ejecución de la limpieza
• corrección verificable a través del verificador, diagnósticos, pruebas deterministas, repetición y artefactos de CI
• ejecución determinista a través de trazas registradas, repetición y control del planificador
• cobertura de sistemas de propósito general en asincronía/tareas, RPC, ADT, traits/genéricos, control de procesos, E/S de terminal, registro, sistema de archivos/rutas, estado interno tipado, JSON de límites y HTTP de transmisión
• cobertura web/servicio de producción a través de fzweb más primitivas de seguridad que mantienen los flujos de sesión/cookie/auth dentro de la superficie de tiempo de ejecución compatible

Ver también:

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

Compilar y probar

cargo check --workspace
cargo test --workspace

CLI principal

# Scaffold de un proyecto en el directorio actual o una ruta de destino
fz init [path] [--name package] [--template minimal|rust|ts] [--with run,fuzz,explore,memory,host|all] [--force]

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

# Ejecutar código/proyecto o escenario .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]

# Probar código/proyecto o escenario .fozzy
fz test [path] [--det] [--strict-verify] [--sched fifo|random|coverage_guided] [--seed N] [--record path] [--backend llvm|cranelift] [--filter substring] [--json]

# Verificar/comprobar/documentar/herramientas
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 / salidas de documentación
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]

La integración con VS Code vive en tooling/vscode y apunta a fz lsp serve.

Valores predeterminados del tiempo de ejecución y comportamiento expuesto:

• destino de enlace del host predeterminado: 127.0.0.1
• puerto predeterminado: 8787
• el destino de enlace efectivo se imprime en listen exitoso
• .env o FZ_DOTENV_PATH se carga una vez antes de las operaciones de entorno/HTTP
• los registros de texto son el valor predeterminado; los registros JSON son optativos mediante log.set_json(1)
• la superficie de la biblioteca estándar incluye core.process, core.term, core.thread, core.log, core.text, core.io, core.path y core.util

Artefactos deterministas

Con fz test <file.fzy> --det --record artifacts/name.trace.json --json, el controlador emite:

• *.trace.json: traza de ejecución determinista
• *.timeline.json: decisiones del planificador
• *.report.json: resumen, hallazgos y agrupación de fallos
• *.explore.json: candidatos a programación y prioridades de escenario
• *.shrink.json: sugerencias de reducción determinista
• *.scenarios/ y *.scenarios.json: escenarios nativos del lenguaje generados
• *.manifest.json: mapa de artefactos que incluye la ruta del escenario principal

Superficie CLI nativa

División de autoría canónica:

• core.process, core.term, core.text: argv y UX de terminal
• core.log: política de registro y salida estructurada
• core.io, core.path: descubrimiento del sistema de archivos y ensamblaje de rutas
• proc.*: ejecución de procesos hijo

Ejemplo:

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

• línea vacía: term.read_line() == "" y term.stdin_eof() == 0
• EOF: term.read_line() == "" y term.stdin_eof() == 1

Para trabajo serio con CLI/tiempo de ejecución, usa tanto el lanzador integrado en el compilador como el binario compilado cuando el comportamiento exacto del terminal sea importante.

Política de backends nativos

• backends compatibles: cranelift y llvm
• orden de selección: --backend explícito, luego FZ_NATIVE_BACKEND, luego perfil predeterminado
• valores predeterminados del perfil: dev -> cranelift, release -> llvm

Bloqueo de dependencias + proveedor

• las compilaciones de proyecto aplican comprobaciones de deriva de fozzy.lock para dependencias de ruta
• actualiza el estado del bloqueo con fz vendor [project] --json
• la salida del proveedor incluye fozzy.lock y vendor/fozzy-vendor.json
• especificación: docs/dependency-locking-v1.md

Puerta de compatibilidad ABI

fz abi-check aplica:

• validez del esquema
• identidad del paquete
• compatibilidad del límite de pánico
• presencia de exportaciones de referencia e inmutabilidad de firmas
• inmutabilidad del contrato de referencia
• no regresión de versión de símbolo

Se permiten exportaciones aditivas.

Interoperabilidad con C

• guía: docs/c-interop-production-v1.md
• cada pubext c fn exportado requiere #[ffi_panic(abort|error)]
• prefiere ext unsafe c fn para importaciones C no seguras y llámalas solo dentro de unsafe { ... }
• fz build --lib emite bibliotecas estáticas/compartidas más un encabezado instalable y un manifiesto ABI
  • el contrato actual del backend es solo Cranelift para compilaciones de bibliotecas; --backend llvm explícito se rechaza con una sugerencia de migración

Artefactos de documentación no segura

• unsafe es ciudadano de primera clase mediante unsafe fn y unsafe { ... }
• fz audit unsafe --workspace --json emite .fz/unsafe-map.workspace.json, .fz/unsafe-docs.workspace.json, .fz/unsafe-docs.workspace.md y .fz/unsafe-docs.workspace.html
• campos de metadatos como reason, invariant, owner, scope, risk_class y proof_ref son generados por el compilador y guiados por políticas
• el flujo de producción predeterminado no bloquea por metadatos faltantes a menos que la política estricta de unsafe esté habilitada

Contrato de validación determinista

Usa esta secuencia para una confianza estricta:

# 1) Auditoría de determinismo primero
fz doctor --deep --scenario tests/run.pass.fozzy.json --runs 5 --seed 42 --json

# 2) Pruebas deterministas estrictas
fz test --det --strict-verify tests/run.pass.fozzy.json tests/memory.pass.fozzy.json --json

# 3) Grabar una traza real
fz run tests/run.pass.fozzy.json --det --record artifacts/trace.fozzy --json

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

# 5) Pase de confianza respaldado por el host
fz run tests/host.pass.fozzy.json --host-backends --json

Puerta de liberación estricta:

./scripts/ship_release_gate.sh

Esto incluye comprobaciones de integridad de afirmaciones de documentación que bloquean el lanzamiento mediante scripts/safety_claim_integrity_gate.py.

Ejemplo: Ciclo de vida de prueba nativa

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

Inspecciona directamente los artefactos de prueba nativa emitidos:

• artifacts/demo.trace.native.trace.json
• artifacts/demo.trace.report.json
• artifacts/demo.trace.timeline.json cuando los artefactos enriquecidos están habilitados
• artifacts/demo.trace.manifest.json

Los manifiestos de prueba nativa son entradas de primera clase para trace verify / replay / ci en ejecuciones de prueba nativa registradas. No son entradas de escenario y no participan en la shrink de escenarios.

Proyectos de ejemplo

Todos los ejemplos incluidos siguen la convención narrativa DX v1:

• src/main.fzy es solo de orquestación y coloca fn main al final
• las pruebas viven bajo src/tests/*
• las raíces de módulos de dominio usan mod.fzy

Proyectos disponibles:

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

Validación y flujos de proyecto:

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

Si contribuyes desde un clon en lugar de instalar una compilación de lanzamiento, usa cargo run -q -p fz -- <args> como alternativa solo con código fuente.

Seguimiento del plan

Mantén estos documentos de entrega versionados actualizados durante la implementación:

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