fzy (fozzylang)

لغة عامة الأغراض للأنظمة وأدوات إنتاج مع سطح لغة آمنة بشكل افتراضي مشحون، صحة قابلة للتحقق، تنفيذ حتمي، وتصحيح أخطاء قائم على إعادة التشغيل مدمج.

تقوم fzy بشحن واجهة أوامر إنتاج واحدة، 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

نظرة سريعة

تريد أسرع نظرة عامة؟ افتح 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 الملائم للمتصفح.

تتبع حزم الإطار قواعد الحزم العادية: قم بتعريفها في fozzy.toml تحت [deps]، ثم استوردها في المصدر باستخدام use fzbounds; و use fzweb; وأسماء حزم مماثلة. تتحقق عمليات الفحص المباشر للمصدر مثل fz check src/services/mod.fzy --json الآن من خلال سياق الحزمة المالكة، لذلك تتصرف استيرادات التبعيات والوحدات الشقيقة بنفس الطريقة التي تتصرف بها في فحوصات المشروع الكامل.

ما يحتويه fzy

• fz: واجهة أوامر المترجم للبناء، التشغيل، الاختبار، التحقق، التوثيق، 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
• أدلة قرار لتنفيذ async، الخيط، وRPC
• أحداث إطار RPC: rpc_send, rpc_recv, rpc_deadline,

ادعاءات إنتاجية

تم إعداد fzy لدعم هذه الادعاءات الإنتاجية اليوم:

• سطح اللغة الآمنة المشحون هو آمن للذاكرة بشكل افتراضي ضمن نطاق قواعد المدقق/المترجم الموثقة، مع حدود غير آمنة مدققة صراحة وإدارة ذاكرة يدوية متتبعة للملكية اختيارية
• دلالات المترجم/وقت التشغيل/الأدوات الداخلية تبقى مصدر حقيقة مطبوع، مع حجز JSON للحدود الخارجية، القطع الأثرية المولدة، والمخرجات الآلية الموجهة للمشغل
• تبقى alloc(...) / free(...) في الكود الآمن عندما لا يزال المترجم يستطيع التحقق من الملكية، المصدر، وتنفيذ التنظيف
• صحة قابلة للتحقق عبر المدقق، التشخيصات، الاختبار الحتمي، إعادة التشغيل، وقطع CI الأثرية
• تنفيذ حتمي عبر الآثار المسجلة، إعادة التشغيل، والتحكم بالجدولة
• تغطية أنظمة عامة الأغراض عبر async/المهام، RPC، ADTs، السمات/الأدوية العامة، التحكم بالعملية، I/O الطرفية، التسجيل، نظام الملفات/المسار، الحالة الداخلية المطبوعة، 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

واجهة الأوامر الأساسية

# 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 مرة واحدة قبل عمليات البيئة/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: خريطة القطع الأثرية بما في ذلك مسار السيناريو الأساسي

سطح واجهة الأوامر الأصلية

تقسيم التأليف القياسي:

• core.process, core.term, core.text: argv وتجربة المستخدم الطرفية
• 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

للعمل الجاد مع واجهة الأوامر/وقت التشغيل، استخدم كل من المشغل المدمج في المترجم والثنائي المبني عندما تكون سلوك الطرفية الدقيق مهماً.

سياسة الخلفية الأصلية

• الخلفيات المدعومة: cranelift و llvm
• ترتيب الاختيار: --backend صريح، ثم FZ_NATIVE_BACKEND، ثم ملف التعريف الافتراضي
• الإعدادات الافتراضية لملف التعريف: dev -> cranelift, release -> llvm

قفل التبعيات + التوريد

• عمليات بناء المشروع تفرض فحوصات انحراف fozzy.lock للتبعيات المسارية
• تحديث حالة القفل باستخدام fz vendor [project] --json
• مخرجات التوريد تتضمن fozzy.lock و vendor/fozzy-vendor.json
• المواصفات: docs/dependency-locking-v1.md

بوابة توافق ABI

يفرض fz abi-check:

• صحة المخطط
• هوية الحزمة
• توافق حدود الذعر
• وجود التصدير الأساسي وعدم قابلية تغيير التوقيع
• عدم قابلية تغيير العقد الأساسي
• عدم تراجع إصدار الرمز

يُسمح بالتصديرات الإضافية.

التوافق مع C

• الدليل: 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 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 يتم إنشاؤها بواسطة المترجم وتوجيهها بالسياسة
• التدفق الإنتاجي الافتراضي غير محظور للبيانات الوصفية المفقودة ما لم يتم تمكين سياسة غير آمنة صارمة

عقد التحقق الحتمي

استخدم هذا التسلسل للثقة الصارمة:

# 1) Determinism audit first
fz doctor --deep --scenario tests/run.pass.fozzy.json --runs 5 --seed 42 --json

# 2) Strict deterministic tests
fz test --det --strict-verify tests/run.pass.fozzy.json tests/memory.pass.fozzy.json --json

# 3) Record one real trace
fz run tests/run.pass.fozzy.json --det --record artifacts/trace.fozzy --json

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

# 5) Host-backed confidence pass
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 السردية لتجربة المطور:

• 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