Skip to content

DIRECTIVES.md

Latest commit

 

History

History
54 lines (37 loc) · 3.65 KB

DIRECTIVES.md

File metadata and controls

54 lines (37 loc) · 3.65 KB
Raw

bytecode-lang — Engineering Directives

Engineering standards and the definition of done for this project. Read alongside REPS.md (root, authoritative) and dev/ROADMAP.md (current phase). If anything here conflicts with REPS.md, REPS.md wins. Family plan: ../_lexersketch/ (README rules of engagement, ARCHITECTURE, ISSUES, ROADMAP).

0. Philosophy

This library is built and maintained to a production standard and treated as a flagship piece of work. Plan the full path, then build one verified step at a time. "Good enough" is treated as a defect. It is part of the LexerSketch runtime tier (LXRT) of the -lang family that LexerSketch assembles.

1. What this is

bytecode-lang owns the format and its static checks. It does not execute (bvm-lang), generate (codegen-lang), or load images (loader-lang).

One bytecode format replaces the incompatible ISAs that grew separately in codegen-lang and bvm-lang, and the private byte format of aot-lang. It is a load-bearing wall: the VM, debugger, and hybrid images all depend on it.

2. Engineering law (non-negotiable)

  • Ours, not rented. No third-party runtime dependency. First-party -lang crates only, wired when first used. Dev-only test tooling is allowed.
  • Performance. Peak is the baseline: allocation-free hot paths where feasible, dense ids instead of maps, no "faster" claim without criterion numbers at realistic scale (100k+ items).
  • Correctness. Every invariant in section 4 is covered by property tests, cross-checked against a simple reference implementation wherever one can be written.
  • Hostile-input hardening. Any input this crate accepts may be adversarial: explicit budgets (depth, size, steps), iterative algorithms, no quadratic paths, no reachable panics.
  • Architecture. SOLID, KISS, YAGNI; one responsibility; a Tier-1 one-call entry point headlines the docs.
  • Cross-platform. Linux, macOS, and Windows are first-class, verified by CI on stable and MSRV 1.85.
  • Error handling. Every fallible path returns Result/Option per a documented contract; errors are #[non_exhaustive] and actionable.
  • Production-ready. #![forbid(unsafe_code)] and #![deny(missing_docs)] from the first commit; no unwrap/expect/todo!/dbg!/printing in library code; every public item has rustdoc with a runnable example; every claim in the docs maps to a test.

3. Definition of done

  1. Compiles clean on Linux/macOS/Windows, stable and MSRV 1.85.
  2. fmt, clippy -D warnings (all targets, all/no-default features), test --all-features, cargo doc -D warnings clean.
  3. cargo audit + cargo deny check pass.
  4. No unwrap/expect/todo!/dbg! in shipping code.
  5. A Tier-1 API exists and headlines the docs.
  6. Property tests cover every section-4 invariant; a fuzz target exists for every decoder or parser.
  7. Hot-path changes carry benchmarks; no regression over 5%.
  8. README.md, docs/API.md, and CHANGELOG.md updated; the matching docs/release/vX.Y.Z.md written before the tag.
  9. v1.0.0 only after a real consumer has exercised the API end to end (LexerSketch decision D18).

4. Project-specific invariants

  • The verifier is total and sound: every module it accepts has in-range registers, constants, and jump targets, consistent types, and well-formed frames; every module it rejects gets a precise error.
  • Encoding round-trips exactly and is deterministic; the header carries a format version and decoding refuses unknown versions.
  • Decoding is budgeted (size, counts, nesting); hostile input never panics or allocates without bound.
  • Every instruction has a written semantics that every execution tier implements identically.