diff --git a/.llm/ROADMAP_TO_STABLE.md b/.llm/ROADMAP_TO_STABLE.md index dde53ed..9f2a233 100644 --- a/.llm/ROADMAP_TO_STABLE.md +++ b/.llm/ROADMAP_TO_STABLE.md @@ -13,11 +13,21 @@ Slovo reaches stable `1.0.0` only after: ## Recommended Sequence -1. Harden monorepo release tooling, clean docs, and public install/build flow. -2. Stabilize `lib/std` module boundaries and document beta-vs-stable APIs. -3. Broaden numeric completeness with explicit `f32` and additional integer - policy where needed. -4. Improve collection and string breadth without exposing unstable ABI details. +The detailed post-beta feature plan lives in +`docs/POST_BETA_ROADMAP.md`. Keep this file as the short stable-readiness +summary and use the public roadmap document when choosing the next connected +implementation scope. + +1. Harden monorepo release tooling, install flow, and common build/run loops. +2. Define runtime resource and host-error policy before broad IO and networking. +3. Stabilize `lib/std` module boundaries and document beta-vs-stable APIs. +4. Improve language usability around entry points, `match`, aliases, and + concrete numeric completeness. 5. Expand package/workspace discipline before remote registry work. -6. Add editor-facing diagnostics and generated documentation improvements. -7. Freeze migration/deprecation policy and cut stable only after beta feedback. +6. Add networking only after resource/error policy is coherent. +7. Add serialization/data-interchange helpers before richer network libraries. +8. Design generics and collection unification from real stdlib duplication + pressure. +9. Add editor-facing diagnostics, watch mode, and generated documentation + improvements. +10. Freeze migration/deprecation policy and cut stable only after beta feedback. diff --git a/README.md b/README.md index 606cecd..9c3e72b 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,7 @@ SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol build hello -o hell - [Language Manifest](docs/language/MANIFEST.md) - [Language Specification](docs/language/SPEC-v1.md) - [Compiler Manifest](docs/compiler/GLAGOL_COMPILER_MANIFEST.md) +- [Post-Beta Roadmap](docs/POST_BETA_ROADMAP.md) - [Slovo Whitepaper](docs/papers/SLOVO_WHITEPAPER.md) - [Glagol Whitepaper](docs/papers/GLAGOL_WHITEPAPER.md) diff --git a/docs/POST_BETA_ROADMAP.md b/docs/POST_BETA_ROADMAP.md new file mode 100644 index 0000000..c06778a --- /dev/null +++ b/docs/POST_BETA_ROADMAP.md @@ -0,0 +1,202 @@ +# Post-Beta Roadmap + +Slovo `1.0.0-beta` is the first usable general-purpose beta baseline. The next +work should broaden the language and toolchain in connected beta slices without +pretending that ABI, package, runtime, or standard-library contracts are stable +yet. + +## Direction + +The best continuation is not a single feature lane. Slovo needs alternating +language, compiler, runtime, stdlib, and tooling slices so each new capability +can be used in real programs and verified by the release gate. + +Each slice should ship only when it updates: + +- language and compiler docs +- source examples and standard-library modules when relevant +- formatter behavior +- diagnostics and negative tests +- hosted runtime behavior when relevant +- benchmarks or conformance tests when relevant +- release notes and the public roadmap + +## Immediate Sequence + +### 1. Tooling And Release Hardening + +Goal: make the public monorepo easy to build, test, install, and verify. + +Work: + +- add `glagol run` for the common build-and-execute loop +- add `glagol clean` for generated build artifacts +- improve `glagol new` templates for library, binary, and workspace projects +- document install paths for `glagol`, `runtime/`, and `lib/std` +- make release gates print a concise final summary +- keep PDF rendering explicit and non-mutating by default + +Why first: it reduces friction for every later feature and gives users a better +way to exercise the beta. + +### 2. Runtime And Resource Foundation + +Goal: create a safer foundation for host resources before adding networking or +larger IO APIs. + +Work: + +- define beta resource-handle policy for files, processes, sockets, and future + host objects +- make host errors consistently return concrete `result` values where possible +- audit allocation failure behavior for strings and vectors +- add runtime conformance tests for cleanup paths +- document that resource handles are beta values, not stable ABI promises + +Why second: networking, file IO, process IO, and HTTP all need a common story +for handles, errors, cleanup, and platform variance. + +### 3. Standard Library Stabilization Pass + +Goal: make existing `lib/std` modules feel coherent before adding many new +surface areas. + +Work: + +- mark each public helper as beta-supported, experimental, or internal +- normalize naming across `std.string`, `std.num`, `std.math`, `std.io`, + `std.fs`, `std.env`, `std.process`, `std.cli`, `std.time`, and `std.random` +- add examples that compose multiple modules in one realistic command-line + program +- add stdlib documentation generation coverage +- identify helpers that should wait for generics instead of being copied across + concrete type families + +Why third: stdlib growth is already broad enough that naming and stability tiers +matter more than adding another isolated helper group. + +### 4. Language Usability Slice + +Goal: reduce awkwardness in common programs without destabilizing the typed core. + +Candidate features: + +- `glagol run`-friendly `main` conventions and clearer entry-point diagnostics +- better `match` diagnostics and exhaustiveness checks where the current enum + model allows it +- type aliases for long concrete types such as vectors, options, and results +- destructuring for simple structs and enum payloads +- additional numeric completeness such as `f32`, only if it can be tested across + checker, formatter, runtime, and docs + +Why fourth: these features improve real Slovo code while keeping generics and +traits deferred until the core has more feedback. + +### 5. Package And Workspace Discipline + +Goal: make multi-package local development predictable before remote registry +work. + +Work: + +- document package identity, version, and local dependency rules +- decide whether a lockfile belongs in the beta package model +- add project-wide `fmt`, `check`, `test`, `doc`, `build`, and `run` behavior +- add diagnostics for ambiguous package roots and dependency cycles +- keep remote registry, semver solving, and publishing out of scope + +Why fifth: stable package rules are a prerequisite for a usable public language, +but remote publishing can wait. + +### 6. Networking Foundation + +Goal: add minimal blocking local networking after resource and error policy is +in place. + +Work: + +- add `std.net` with blocking TCP client/server primitives +- use loopback-only deterministic tests +- expose host failures through result values +- keep TLS, async, DNS policy, HTTP server frameworks, and event loops deferred +- add small examples such as echo client/server or local request/response + +Why sixth: networking is useful, but doing it before resources and host errors +would create unstable API debt. + +### 7. Serialization And Data Interchange + +Goal: make Slovo useful for command-line and network programs without requiring +maps/sets immediately. + +Work: + +- add string scanning/tokenizing helpers +- add simple JSON text construction helpers first +- defer full JSON object parsing until maps, richer strings, or generic + collections exist +- add benchmark cases for parsing and formatting + +Why seventh: networking and CLI tools need data interchange, but a complete JSON +library depends on collection work. + +### 8. Generics And Collection Unification + +Goal: stop duplicating every helper across concrete vector, option, and result +families. + +Work: + +- design generic function syntax and typed-core representation +- gate generic stdlib helpers behind conformance tests +- migrate repeated concrete helpers only after compatibility policy is written +- add generic arrays/vectors first, then maps and sets +- keep stable ABI/layout promises deferred until after real beta use + +Why eighth: generics are important, but they should be introduced after the +compiler, docs, tests, and stdlib have enough real pressure to validate the +design. + +### 9. Developer Experience + +Goal: make Slovo comfortable for repeated daily use. + +Work: + +- language-server diagnostics and document symbols +- project watch mode +- generated API documentation for local packages and `lib/std` +- clearer benchmark harness output +- machine-readable diagnostics stability policy + +Why ninth: editor support matters, but it should follow a stable enough syntax, +project model, and diagnostic model. + +## Stable `1.0.0` Gate + +Slovo should not become stable until all of these are true: + +- migration and deprecation policy is documented +- `lib/std` has explicit stable and experimental tiers +- package/workspace behavior is deterministic +- conformance tests cover user-shaped projects +- release gates are reproducible on a clean checkout +- diagnostics and formatter output are stable for promoted features +- performance publications are repeatable and labeled as local-machine evidence +- the language can build useful local CLI tools, libraries, file-processing + programs, and basic host-interaction programs without undocumented behavior + +## Explicitly Deferred + +These should not be early post-beta work unless a smaller prerequisite slice is +complete first: + +- full async runtime +- TLS and certificate policy +- remote package registry +- macro system +- stable C ABI/layout guarantees +- optimizing compiler claims +- web framework or HTTP server framework +- broad Unicode/string normalization policy + diff --git a/docs/compiler/ROADMAP.md b/docs/compiler/ROADMAP.md index 98470b2..acfb677 100644 --- a/docs/compiler/ROADMAP.md +++ b/docs/compiler/ROADMAP.md @@ -1,6 +1,7 @@ # Glagol Roadmap -Glagol is the first compiler for Slovo. Slovo language design lives in `../language`. +Glagol is the first compiler for Slovo. Slovo language design lives in +`docs/language/` inside the same monorepo. Compiler rule: make the tree visible. The pipeline should remain: diff --git a/docs/language/ROADMAP.md b/docs/language/ROADMAP.md index 8d49845..f5ec8aa 100644 --- a/docs/language/ROADMAP.md +++ b/docs/language/ROADMAP.md @@ -1,7 +1,7 @@ # Slovo Roadmap -This roadmap tracks the language contract. Glagol, in `../glagol`, tracks the -compiler implementation. +This roadmap tracks the language contract. Glagol, in `compiler/`, tracks the +compiler implementation inside the same monorepo. Guiding rule: the manifest wins. A feature is not accepted until it has surface syntax, typed-core meaning, lowering behavior, formatter behavior, diagnostics, and tests.