| @@ -0,0 +1,72 @@ |
| 1 | +# tilcayo v1 — Roadmap |
| 2 | + |
| 3 | +> **Status: Proposed, 2026-10-09.** It gathers everything v0 deferred, from the [v0 plan](roadmap.md), the [v0 release notes](release-notes-v0.md), the ADRs and the follow-up issues. The definition of done and the milestone order are proposals for the project owner. Per Innoptech policy, each milestone's runtime, type-system and architecture decisions get an ADR and engineering review before they are built. |
| 4 | +> |
| 5 | +> Tracked in issue #52 (the v1 epic); milestones #44–#51. |
| 6 | + |
| 7 | +## Where v0 ended |
| 8 | +v0 met its definition of done (issue #13): a supervised HTTP server with SSR HTML, argon2 over C FFI, effect handlers for logging and a mockable DB, and an LSP. |
| 9 | + |
| 10 | +These v0 limitations have been addressed since the v0 release notes (M6, PRs #37–#42): |
| 11 | +- a scheduler thread per core; |
| 12 | +- move/share/copy sending; |
| 13 | +- the `Send` check; |
| 14 | +- `Selector`; |
| 15 | +- rest_for_one; |
| 16 | +- `spawn_link` and `spawn_monitor` as single operations. |
| 17 | + |
| 18 | +Since then, the first v1 work has merged (PRs #54–#59): |
| 19 | +- the benchmark suite; |
| 20 | +- the runtime's own context switch; |
| 21 | +- per-thread run queues with work stealing; |
| 22 | +- `Bytes` and HTTP keep-alive; |
| 23 | +- the Perceus optimisations; |
| 24 | +- mimalloc and `#line` directives. |
| 25 | + |
| 26 | +The milestone issues track what is left. |
| 27 | + |
| 28 | +## v1 definition of done (proposed) |
| 29 | +**The v0 demo, made production-shaped.** It runs on all cores with work stealing, is measurably fast on a benchmark suite, speaks binary HTTP/1.1 with keep-alive, and has an interactive page rendered on the client from the same HTML literals. It installs its dependencies from a registry. |
| 30 | + |
| 31 | +Concretely: |
| 32 | +- [ ] Every accepted v1 ADR is implemented, and every proposed v0 ADR has been reviewed. |
| 33 | +- [ ] `tests/bench` exists. Each performance milestone states its target on it, and meets it. |
| 34 | +- [ ] The demo serves keep-alive HTTP with `Bytes` bodies, on several threads, under a load test, with the leak oracle at 0. |
| 35 | +- [ ] One page of the demo runs client-side (wasm or JS), typed with the same `Element<msg>`. |
| 36 | +- [ ] `tilc` resolves dependencies from a registry (or git) with a lockfile. |
| 37 | + |
| 38 | +## Milestones |
| 39 | + |
| 40 | +| # | Milestone | Contents (deferred from) | Issues | |
| 41 | +|---|---|---|---| |
| 42 | +| M0 | Review gate | Engineering review of the still-proposed ADRs: 0010 (lexical handlers), 0003 Rev. 2 (unwinding in C), 0005 Rev. 1 (extern convention), 0002 Rev. 1 (regions, move/share/copy), 0004 Rev. 1 and its implementation notes (threads, `Send` check). | #44 | |
| 43 | +| M1 | Runtime foundations | The runtime's own context switch (x86_64, aarch64; macOS if cheap), replacing corosensei and its `Send` wrapper. mimalloc behind `tl_alloc`. Scheduler step 2: per-thread queues with work stealing, lock-free mailboxes, an atomic actor state, loom models, per-thread timer wheels, ThreadSanitizer. | #45 (#35, #43) | |
| 44 | +| M2 | Fast code | A benchmark suite first. Perceus: borrow inference, reuse (FBIP), drop specialisation. Static dictionaries, then specialisation of known trait evidence. A decision (ADR) on monomorphisation versus uniform boxed values for numeric code. A "never unwinds" analysis that drops yield checks after leaf calls. | #46 (#34) | |
| 45 | +| M3 | Data and IO | `Bytes` with a builder, shared when large. `std/net` on `Bytes`, with UTF-8 validation for strings. HTTP keep-alive, chunked bodies and binary responses. Arrays (`TL_SCAN_LARGE`, reserved in the ABI). Bigint promotion on `Int` overflow (an ABI change). | #47 (#36) | |
| 46 | +| M4 | FFI and the C boundary | Callbacks from C into tilcayo. A binding generator for simple C signatures (bindgen-style). `#line` directives in generated C, which need spans in Core, so that C compiler and sanitizer errors point at `.til` lines. | #48 (#35) | |
| 47 | +| M5 | Language | Multi-shot resumptions (v0 resumptions are one-shot). Traits with several parameters, higher-kinded types, user-defined derives (ADR 0007). User-level `finally` (ADR 0003: unwinding runs drops only). The interpreter matching native on escaped continuations (a `resume` after its handler finished panics in both). | #49 | |
| 48 | +| M6 | Client HTML target | Compile to wasm or JS. `ctl` without fibers, by Koka-style continuation capture on top of yield-bubbling (ADR 0003's planned path). Typed `on*` event attributes and `msg` dispatch (ADR 0009). A client runtime for `Element<msg>`. | #50 | |
| 49 | +| M7 | Packages and tooling | A package registry, or git dependencies with a lockfile first. Incremental analysis on salsa if the LSP needs it (ADR 0006's criteria). | #51 | |
| 50 | + |
| 51 | +Suggested order: M0 first, then M1 and M2 in parallel (M2's benchmarks first), then M3. M4–M7 can start whenever their ADRs are accepted. M6 depends on M5's decision on multi-shot resumptions, because it changes how continuations are captured. |
| 52 | + |
| 53 | +## Research, not committed to v1 |
| 54 | +- **Optional `borrow` annotations or explicit lifetimes**, as a performance tool (ADR 0002). Combining them with effect handlers is research-level. |
| 55 | +- **An LLVM backend** with zero-overhead, table-driven unwinding, where landing pads and guaranteed tail calls coexist (ADR 0003 Rev. 2). |
| 56 | +- **A sound `Send` trait** (`where Send<m>`), if the concrete-type check (E0704) and the runtime check prove insufficient (ADR 0004 implementation notes). |
| 57 | + |
| 58 | +## Dropped |
| 59 | +- **`mask`**: lexically scoped handlers make it unnecessary (ADR 0010). |
| 60 | +- **A cycle collector**: `Ref`s live in regions, which break cycles when they end (ADR 0002 Rev. 1). |
| 61 | +- **Thread pinning of actors**: replaced by migration (ADR 0004 Rev. 1). |
| 62 | + |
| 63 | +## Verification, as in v0 |
| 64 | +Every milestone keeps the v0 gates: |
| 65 | +- the differential interpreter/native tests (one thread exact, four threads by exit status and leaks); |
| 66 | +- ASan and UBSan; |
| 67 | +- the leak oracle at 0; |
| 68 | +- `scripts/stress.sh`; |
| 69 | +- the demo's end-to-end test; |
| 70 | +- `scripts/ci.sh` green. |
| 71 | + |
| 72 | +Performance milestones add benchmark targets, and concurrency milestones add loom models. |