Engineering

Development Philosophy

The founding constraint

This is a decade-scale mastery project. There is no application to ship. The goal is to master every layer — cryptography, derivation, protocol design. Code that arrives faster than understanding is a regression.

Everything about how Zajil is built follows from that one sentence. The deliverable is not a product; it is complete command of the system and a protocol that holds up for decades.

The rules

• One small module at a time

  Bottom-up, per the implementation plan. A module is done when it is tested, documented, and understood — not when it works.

• Never scaffold ahead

  No stubbed layers, no placeholder modules, no demo spanning layers not yet built. If a request would produce a large working system, decompose it and push back.

• Smallest testable unit

  Always propose the smallest thing that can be tested, not the largest thing that would be useful.

• Theory alongside code

  Each module comes with the reading that explains it. The point is to know why it works, not to receive something that works.

How the collaboration works

To keep understanding ahead of code, the working method is deliberate:

• Implementation code is typed by the author, not generated. Assistance comes as snippets in discussion, one function at a time, placed and understood by hand. Writing tests, docs, and empty todo!() signatures is fine — the implementations are the author's to write.
• Test-driven, strictly. Tests are written first and watched to fail. No logic is added that no test demands; if a check seems worth having, a failing test for it is written first.
• Nothing advances until the current piece is understood. The next snippet waits for the current one to be placed and grasped.

The SQLite standard, honestly

SQLite's famous ~590:1 test-to-code ratio (≈92M lines of test vs ≈156k of library) is mostly machine-generated cases from harnesses like TH3. Chasing that ratio by hand is neither achievable nor the lesson. What actually produces the reliability — and what Zajil copies — is the method:

SQLite practice	Zajil analogue
100% MC/DC branch coverage	100% branch coverage on the sans-io core
Three independent test harnesses	RFC known-answer vectors + property tests + simulation
Continuous fuzzing	cargo-fuzz on every decoder touching untrusted bytes
OOM / crash / power-loss injection	Deterministic network simulation: loss, reorder, delay, partition

The ratio is a consequence of these, not the goal. See the testing standard for the full picture.

Why this pace is the point

Code the author did not build line by line is code they have not mastered. Generating a large working system would produce something that runs and teach nothing — which, for this project, is the one true failure. Five to ten years is not a constraint to work around; it is the plan.