Parent: docs/README.md. Read top-down. Each level answers a
more specific question and links to detail instead of repeating it.
- Intent: mission explains what the user wants and refuses.
- Current truth:
docs/current-status.mdstates what exists, what is green, and what is not yet a win. - Contracts:
language-v0.1.md,configuration.md,modules-and-delivery.md, andweb-platform.mddefine public behavior. - Durable rationale: design decisions explain why the architecture chooses contracts, proofs, exact scoring, explicit ABI, and a narrow target representation.
- Implementation: current architecture and its topic pages describe the code that exists.
- Target and execution: planned architecture and planned migration.
- Proof of claims: verification defines valid evidence; evidence links results.
- Live work: ledger. Board notes and journals
are context, not architecture authority. The size workstream's contract,
standings and hypothesis log are in
finer/. - Research: research contains experiments and rejected ideas. Load it only when the canonical pages cite a specific finding.
| Question | Start here |
|---|---|
| Is a proposal consistent with product intent? | Mission |
| What does the language guarantee? | Language contract |
| What does a config key do? | Configuration contract |
| Why is a semantic rule not a codec choice? | Contracts before objectives |
| Why not add a library-specific fold? | Typed proofs, not glue |
| What pipeline exists now? | Current architecture |
| What is the smallest planned replacement? | Planned architecture |
| Is a choice mandatory, ABI-fixed, or scored? | Decision registry |
| How are raw/gzip/Brotli winners selected? | Objectives -> candidate search |
| Is a size number publishable? | Verification -> evidence |
| What should be implemented next? | Current status -> migration -> ledger |
- Intent: types are not glue, compressor surface
- Values and control: numerics, functions, control/errors, effects
- Data: aggregates, collections, async/generators/regex
- Boundaries: closed world, packages/ABI, escape/host, modules/lazy, JavaScript vs native
- Architecture: router, current, planned
- Policy: objectives, decision registry, global optima
- Frontend/IR: pipeline, linking/lowering, analyses, optimizer, DCE, inlining, aggregates, class identity
- Backend/search: emission, mangling/layout, search, peephole, chunks, native, fallbacks
- Config
- Delivery
- Verification
- Evidence, including the library proof matrix and Motion, Marked, MobX, jQuery
- Migration
- Research
| Concern | Primary source |
|---|---|
| Grammar and AST | src/lexer.rs, src/parser.rs, src/ast.rs |
| Semantics and effects | src/semantic.rs, src/interpreter.rs |
| Modules/packages | src/module.rs, src/package.rs |
| Typed IR and provenance | src/ir.rs, src/lower.rs |
| Compilation contract/objective/ABI | src/compilation_contract.rs, src/config.rs |
| IR optimization and proofs | src/optimizer.rs, src/compress_passes.rs, src/value_analysis.rs |
| Decision census and families | src/decision_registry.rs |
| Search and orchestration | src/compiler.rs |
| JavaScript emission | src/codegen_ir_js.rs, src/js_syntax_target.rs |
| Generated-JS migration layer | src/js_peephole/ |
| Native backend | src/codegen_native.rs |
| Exact codecs | src/bin/lilscript-codec.rs, benchmarks/codec-contract.mjs |
| Semantic verification | tests/cases/, src/bin/lilscript-differential.rs |
| Compression verification | comparison/cases/, comparison/algorithms/, comparison/large-libraries/ |
| Release gates | scripts/release-check.sh, comparison/run-all.sh |