fzy (fozzylang)

Универсальный системный язык и производственный инструментарий с безопасной по умолчанию поверхностью безопасного языка, проверяемой корректностью, детерминированным выполнением и встроенной отладкой на основе воспроизведения первого шага.

fzy поставляет один производственный CLI, fz, как для рабочих процессов компилятора, так и для детерминированной валидации. Корректность, детерминизм, воспроизведение, артефакты инцидентов и производственные доказательства являются частью обычного рабочего процесса, а не второстепенной мыслью. Для быстрого визуального обзора языка откройте прилагаемый FZL showcase в браузере с помощью 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

Быстрый взгляд

Хотите самый быстрый обзор? Откройте fzl-showcase.html с помощью open 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 showcase.

Пакеты фреймворков следуют обычным правилам для пакетов: объявите их в 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(...)
• реальная семантика defer времени выполнения как в обычном коде, так и в островках unsafe { ... }, поэтому детерминированная очистка обеспечивается принудительно, а не просто документируется
• правила владения, заимствования, возможностей, FFI и проверяемые верификатором возможности понижения до нативного кода
• явное ручное управление памятью поддерживается в рамках этой модели, с учетом владения потоками alloc(...) / free(...) и проверками жизненного цикла, видимыми верификатору
• детерминированная трассировка, воспроизведение и валидация планировщика как обычные производственные шлюзы
• доверительные пути с поддержкой хоста для поведения файловой системы, процессов и HTTP
• детерминированные режимы планировщика: fifo, random, coverage_guided
• артефакты решений для асинхронного, потокового и RPC-выполнения
• события RPC-кадров: rpc_send, , ,

Производственные утверждения

fzy настроен на поддержку следующих производственных утверждений сегодня:

• поставляемая безопасная поверхность языка безопасна по памяти по умолчанию в рамках задокументированной области правил верификатора/компилятора, с явными проверенными небезопасными границами и дополнительным ручным управлением памятью с отслеживанием владения
• внутренняя семантика компилятора/среды выполнения/инструментария остается типизированным источником истины, при этом JSON зарезервирован для внешних границ, сгенерированных артефактов и машинного вывода, ориентированного на оператора
• alloc(...) / free(...) остаются в безопасном коде, когда компилятор все еще может проверить владение, происхождение и выполнение очистки
• проверяемая корректность через верификатор, диагностику, детерминированное тестирование, воспроизведение и артефакты CI
• детерминированное выполнение через записанные трассы, воспроизведение и управление планировщиком
• покрытие универсального системного обеспечения: асинхронные задачи, RPC, ADT, трейты/обобщения, управление процессами, терминальный ввод-вывод, логирование, файловая система/пути, типизированное внутреннее состояние, граничный JSON и потоковый HTTP
• покрытие производственных веб/сервисов через fzweb плюс примитивы безопасности, которые поддерживают потоки сессий/куки/аутентификации в рамках поддерживаемой поверхности среды выполнения

См. также:

• 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

# Scaffold a project in the current directory or a target path
fz init [path] [--name package] [--template minimal|rust|ts] [--with run,fuzz,explore,memory,host|all] [--force]

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

# Run source/project or .fozzy scenario
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]

# Test source/project or .fozzy scenario
fz test [path] [--det] [--strict-verify] [--sched fifo|random|coverage_guided] [--seed N] [--record path] [--backend llvm|cranelift] [--filter substring] [--json]

# Verify/check/docs/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 outputs
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 загружается один раз перед операциями env/HTTP
• текстовые логи используются по умолчанию; JSON-логи включаются через log.set_json(1)
• поверхность стандартной библиотеки включает core.process, core.term, core.thread, core.log, core.text, core.io, core.path и core.util

Детерминированные артефакты

С помощью 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 обеспечивает:

• корректность схемы
• идентичность пакета
• совместимость границы паники
• наличие базового экспорта и неизменность сигнатур
• неизменность базового контракта
• нерегрессию версии символа

Добавочные экспорты разрешены.

C Interop

• руководство: docs/c-interop-production-v1.md
• каждый экспортированный pubext c fn требует #[ffi_panic(abort|error)]
• предпочитайте ext unsafe c fn для небезопасных импортов C и вызывайте их только внутри unsafe { ... }
• fz build --lib выдает статические/разделяемые библиотеки плюс устанавливаемый заголовок и манифест ABI
  • текущий контракт бэкенда — только Cranelift для сборок библиотек; явный --backend llvm отклоняется с подсказкой по миграции

Артефакты документации Unsafe

• unsafe является первоклассным через 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, генерируются компилятором и определяются политикой
• стандартный производственный поток не блокируется при отсутствии метаданных, если только не включена строгая политика unsafe

Детерминированный контракт валидации

Используйте эту последовательность для строгой уверенности:

# 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