slovo/docs/POST_BETA_ROADMAP.md

# 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

Released in `1.0.0-beta.1`: `glagol run`, `glagol clean`,
`glagol new --template binary|library|workspace`, `scripts/install.sh`,
installed std/runtime discovery, README coverage, focused DX tests, and a
concise release-gate success line.

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

Released in `1.0.0-beta.2`: read-only text file resource handles are
implemented with `std.fs.open_text_read_result`,
`std.fs.read_open_text_result`, and `std.fs.close_result`. The same release
also includes narrow filesystem status and mutation calls:
`std.fs.exists`, `std.fs.is_file`, `std.fs.is_dir`,
`std.fs.remove_file_result`, and `std.fs.create_dir_result`. Matching
`lib/std/fs.slo` facades and focused runtime tests are in place. Writable
handles, directory handles/enumeration, process handles, sockets, platform
error codes, and async resources remain deferred.

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

Released in `1.0.0-beta.3`: `docs/language/STDLIB_API.md` is
generated from `lib/std/*.slo` and guarded by `scripts/release-gate.sh`.
`examples/projects/stdlib-composition` adds a realistic command-line project
that composes `std.fs`, `std.string`, `std.math`, and `std.io` through explicit
standard imports, with focused check/test/doc/run coverage.

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
- concrete 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.

Released in `1.0.0-beta.4`: project/workspace build and run entry
diagnostics now use entry-specific codes and explicitly show the required
`(fn main () -> i32 ...)` contract. Non-exhaustive `match` diagnostics now use
clearer missing-arm wording and deterministic found-arm output.
Concrete aliases were split into the follow-up `1.0.0-beta.8` language slice so
the syntax, formatter, diagnostics, and source fixtures could be gated directly.

### 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

Released in `1.0.0-beta.5`: local workspaces can declare `default_package` to
select the build/run entry package when multiple packages have entry modules.
Duplicate normalized member paths and missing default-package references are
dedicated diagnostics. Workspace documentation now includes package and local
dependency summaries, generated workspace templates declare
`default_package = "app"`, and `docs/language/PACKAGES.md` records the beta
local-package rules. Lockfiles, remote registries, semver solving, publishing,
optional/dev/target dependencies, and stable package ABI/layout remain 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

Released in `1.0.0-beta.6`: `lib/std/net.slo` now provides explicit wrappers
for loopback TCP connect, listen, bound-port lookup, accept, read-all,
write-text, and close result calls. The source fixtures use invalid port/handle
checks for deterministic result-shape coverage, and the compiler/runtime tests
cover lowering plus hosted loopback client/server smoke when the local sandbox
allows loopback sockets. DNS, TLS, UDP, async IO, non-loopback binding, HTTP
frameworks, rich host-error ADTs, and stable socket ABI/layout remain deferred.

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

Released in `1.0.0-beta.7`: `lib/std/json.slo` now provides explicit helpers
for compact JSON text construction over strings, booleans, numbers, null,
fields, small arrays, and small objects. `std.json.quote_string` is a
compiler-known runtime helper so JSON string escaping is correct before Slovo
has source-level byte/character scanning and slicing. Matching explicit
std/local source fixtures and a `json-quote-loop` benchmark scaffold are in
place. JSON parsing, recursive JSON values, maps/sets, generic collections,
streaming encoders, schema validation, Unicode normalization, and stable text
encoding policy beyond the current runtime string ABI remain deferred.

Why seventh: networking and CLI tools need data interchange, but a complete JSON
library depends on collection work.

### 8. Concrete Type Alias Foundation

Goal: reduce concrete type repetition without introducing generics or changing
runtime representation.

Work:

- add top-level `(type Alias TargetType)` declarations for aliases whose targets
  are already supported concrete Slovo types
- resolve aliases before typed-core lowering, checked import signatures, backend
  layout, ABI decisions, and runtime behavior
- keep aliases module-local: no alias exports, imports, re-exports, or
  cross-module alias visibility
- update formatter and diagnostics for malformed, duplicate, unsupported,
  cyclic, exported, or imported aliases
- exercise aliases sparingly in JSON source facades and explicit source
  fixtures without adding compiler-known runtime names

Released in `1.0.0-beta.8`: concrete aliases such as `(type JsonText string)`
are transparent names for existing concrete types. The compiler parses,
formats, checks, lowers, and erases aliases before backend behavior, while
project imports of functions that used local aliases see concrete target
types. Alias export/import attempts and unsupported targets are diagnostics.
Generic aliases, parameterized aliases, aliasing maps/sets, stable ABI/layout
names, and runtime changes remain deferred.

Why eighth: concrete aliases remove real noise from current stdlib and fixture
code while deliberately postponing generic type parameters until the compiler
and standard library have stronger design pressure.

### 9. Collection Alias Unification And Generic Reservation

Goal: apply concrete aliases to the existing collection/value facades and
reserve the generic/map/set direction without changing executable semantics.

Work:

- use beta.8 concrete aliases sparingly inside current vector, option, and
  result source facades to reduce repeated long concrete types
- preserve all public helper names, exports, imports, runtime calls, and
  concrete cross-module signatures
- document that current vectors/options/results are still concrete families
  and that local aliases erase before lowering
- reserve executable generics, maps, sets, traits, inference,
  monomorphization, iterators, and ABI stability for later gated releases

Released in `1.0.0-beta.9`: the concrete `std.vec_i32`, `std.vec_i64`,
`std.vec_f64`, `std.vec_bool`, `std.vec_string`, `std.option`, and
`std.result` facades now use module-local transparent aliases internally.
The exported helper surface remains concrete after alias normalization.
The release does not implement executable generics, maps, sets, traits,
inference, monomorphization, iterators, or stable ABI/layout promises.

Why ninth: generics are important, but they should be introduced after the
compiler, docs, tests, and stdlib have enough real pressure to validate the
design.

### 10. Developer Experience API Discovery

Goal: make Slovo comfortable for repeated daily use by making the current
standard-library API surface easier to inspect before deeper editor work.

Work:

- upgrade the generated `lib/std` API catalog from exported names to exact
  exported helper signatures
- normalize module-local beta.8/beta.9 concrete aliases in public signatures
  so local aliases do not leak into docs
- validate that exported helpers have matching `(fn ...)` forms
- keep non-exported helpers and `(type ...)` aliases out of the public catalog
- language-server diagnostics and document symbols
- editor-facing symbol metadata for files, projects, and workspaces
- project watch mode
- clearer benchmark harness output
- machine-readable diagnostics stability policy

Released in `1.0.0-beta.10`: `docs/language/STDLIB_API.md` now lists exact
exported helper signatures from `lib/std/*.slo`, and the renderer validates
exported helper forms while normalizing module-local aliases to concrete
public types. `glagol symbols <file.slo|project|workspace>` now emits
deterministic `slovo.symbols` metadata for editor integrations without
starting an LSP server. This is beta API discovery only; it does not add
executable generics, maps, sets, runtime changes, or a stable standard-library
API freeze. LSP, watch mode, benchmark-output work, stable Markdown schema,
stable stdlib/API compatibility freeze, SARIF/daemon protocols, and a
machine-readable diagnostics stability policy remain deferred.

Why tenth: editor support matters, but it should follow a stable enough syntax,
project model, and diagnostic model.

### 11. Local Package API Documentation

Goal: extend beta API discovery from `lib/std` and symbol metadata to the
local packages and modules users document with `glagol doc`.

Work:

- make `glagol doc <file|project|workspace> -o <dir>` include deterministic
  exported/public API sections for local packages and modules
- list exact exported function signatures
- list exported struct fields
- list exported enum variants and payload types
- keep non-exported functions, structs, enums, tests, and aliases out of the
  public API sections
- normalize module-local concrete aliases in public docs so local alias names
  do not leak across module/package boundaries
- keep Markdown layout and generated file names beta-scoped rather than stable

Released in `1.0.0-beta.11`: local file, project, package, and workspace docs
generated by `glagol doc <file|project|workspace> -o <dir>` include
deterministic public API sections with exact exported function signatures,
exported struct fields, exported enum variants/payload types, non-export
filtering, and module-local alias normalization. This extends beta10 API
discovery only; it does not freeze the Markdown schema, create a stable
stdlib/API compatibility freeze, add LSP/watch, define SARIF/daemon protocols,
set a diagnostics schema policy, implement executable generics/maps/sets, add
re-exports/globs/hierarchical modules, or define registry semantics.

Why eleventh: local packages are useful only if their public surface can be
reviewed without reading every source file, but the documentation format
should remain flexible until the package and editor stories are stronger.

### 12. Concrete Vector Query And Prefix Parity

Goal: close small source-authored helper gaps in the current concrete vector
facades before returning to larger language and tooling slices.

Work:

- add `count_of`, `starts_with`, `without_prefix`, `ends_with`, and
  `without_suffix` to `std.vec_i64`
- add `count_of` to `std.vec_f64`
- keep all helpers source-authored over the already promoted concrete vector
  runtime names, equality, `len`, `at`, `take`, `drop`, and recursive helper
  style
- add explicit local helper project coverage for repeated count results and
  prefix/suffix empty, mismatch, exact, and longer-than-input cases where
  applicable
- document the slice as helper parity only, not a language/runtime change

Released in `1.0.0-beta.12`: `std.vec_i64` gains `count_of`, `starts_with`,
`without_prefix`, `ends_with`, and `without_suffix`; `std.vec_f64` gains
`count_of`; and focused Glagol fixture tests require the corresponding explicit
source-helper coverage. The release does not add generics, maps/sets,
iterators, mutable vectors, slice/view APIs, new runtime names, ABI/layout
stability, performance claims, or a stable stdlib/API freeze.

Why twelfth: concrete vectors are already broad enough that parity gaps create
surprising differences, and source-authored helpers can close those gaps
without committing to generic collection design.

## 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
- mutable vectors, slice/view APIs, iterators, maps, sets, and executable
  generics
- new runtime helper names or generic stdlib dispatch before an explicit
  runtime/language slice
- web framework or HTTP server framework
- broad Unicode/string normalization policy