Use this page to find the authoritative document for a topic. The public overview stays in the repository README; contributor policy and the complete command reference stay in AGENTS.md.
| Question | Read |
|---|---|
| What is Cynic and how do I run it? | README.md |
| What rules apply to a code change? | AGENTS.md |
| How do the major components fit together? | ARCHITECTURE.md |
| What has shipped and what remains? | ROADMAP.md |
| What engineering workflow should I follow? | Engineering handbook |
| What are the current conformance scores? | ECMAScript and WebAssembly results |
| What are the current cross-engine measurements? | bench-cross-results.md |
Documents use four roles:
- Reference describes current behavior or a current engineering contract.
- Design record preserves accepted decisions and their delivery history.
- Research note records a measured recommendation, including negative results. It is not an implementation requirement unless its status says so.
- Ledger is append-only evidence: scores, carve-outs, or upstream gaps.
For a long design record, read its opening status before the older phase text. Future-tense implementation plans are often retained to explain why the shipped shape exists.
| Document | Role |
|---|---|
| Tests first | Required TDD sequence |
| Prior art | Required survey protocol for non-trivial design |
| Compiler engineering | Parser, bytecode, VM, JIT, and GC vocabulary |
| Host-abort safety | Safety contract for untrusted input |
| Garbage collection | Current Metla design, roots, barriers, and HandleScope contract |
| Environment records | Current binding and global-environment model |
| Regression checks | Required focused and full verification postures |
| Zig idioms | Project-specific Zig 0.17 patterns |
| Document | Role and scope |
|---|---|
| SES alignment | Current hardened-default policy plus delivery record |
| Multi-realm | Shipped realm substrate; deferred Compartment design |
| Realm snapshots | Partial rollout: core fresh-realm capture/restore and remaining gates |
| Resource metering | Shipped fuel, memory, and interrupt API |
| Inline caches | Shipped shape/IC substrate and remaining IC work |
| Lazy property bag | Shipped phases and deferred property-storage work |
| SharedArrayBuffer and Atomics | Single-agent design and shipped surface |
| Multi-agent Atomics | Shipped threaded test262 host substrate and follow-ups |
| Playground | Browser-Wasm build and deployment reference |
| Document | Role and scope |
|---|---|
| JIT tiers | Shared Bistromath, Ohaimark, and Spasm architecture and rollout gates |
| Ohaimark | Optimizing-JIT accepted design, deoptimization contract, OSR, and delivery ledger |
| Sarcasm WebAssembly engine | Wasm decoder, validator, interpreter, JS API, and Spasm boundary |
| Document | Role and scope |
|---|---|
| Benchmarking | Local and cross-engine measurement protocol |
| Fuzzing | Fuzzilli setup, triage, and continuous-fuzzing gate |
| Differential fuzzing | Native and external-oracle differential strategy |
| Fuzz carve-outs | Machine-consumed ledger of intentional divergences |
| test262 gap audit | Classification of body-only, by-design failures |
| test262 upstream gaps | Fixture proposals for bugs not covered upstream |
| ECMA-262 upstream gaps | Specification clarification proposals |
These files preserve experiments so closed paths are not re-investigated without new evidence.
| Document | Recorded outcome |
|---|---|
| Incremental/concurrent marking | Incremental marking shipped; concurrent marker deferred |
| Generational aging | Card marking shipped; aging did not justify the proposed path |
| Generational major collection | Closed for a non-moving collector |
| Immix rearchitecture | Measurements did not support an Immix rewrite |
| Reference counting | Prototype measured as a no-go |
| Parallel GC | Design only; useful for large-heap trigger analysis |
| Property-key interning | Prototype measured as a no-go |
ctor_array_build gap |
Interpreter bottleneck diagnosis and ranked options |
| OSS-Fuzz assessment | Not currently a fit for Cynic's Fuzzilli pipeline |
When a subsystem document and a score ledger disagree, the ledger owns the number and the subsystem document owns the design. Fix the stale cross-link; do not duplicate a live score into another overview.