# Slovo Standard Library Stability Tiers

Status: beta public ledger for `1.0.0-beta.23`.

This document records the current maturity labels for the source-authored
standard-library facade surface. Exact exported helper signatures remain in
[`STDLIB_API.md`](STDLIB_API.md), which is generated from `lib/std/*.slo`.
This ledger explains how to read that catalog during the beta line.

`1.0.0-beta.23` is documentation and catalog-tooling alignment only. It adds no
source syntax, standard-library helpers, compiler-known runtime names, runtime
behavior, package behavior, manifest schema guarantee, Markdown schema
guarantee, ABI/layout guarantee, or stable standard-library/API compatibility
freeze. It does make the generated API catalog emit tier metadata and makes the
release gate check that experimental tier metadata is present.

## Tier Labels

Slovo uses these public standard-library tier labels:

| Tier | Meaning |
| --- | --- |
| `beta-supported` | Exported from `lib/std`, covered by current beta source-search, promotion, facade, or composition gates, and suitable for beta programs. Names and behavior are still beta contracts, not a stable `1.0.0` freeze. |
| `experimental` | Exported or documented in the beta line, but intentionally fluid because the domain still depends on deferred language, runtime, resource, platform, or schema policy. Use for feedback and narrow programs, not compatibility promises. |
| `internal` | Not public standard-library API. This includes non-exported helper names, module-local concrete aliases, implementation details, generated-document internals, and private runtime symbols. Internal names may be omitted from public catalogs or changed without migration promises. |

## Catalog Boundary

[`STDLIB_API.md`](STDLIB_API.md) is the generated signature inventory: it lists
exported `(fn ...)` helpers from `lib/std/*.slo`, normalizes module-local
concrete aliases to public concrete types, and omits non-exported helpers and
`(type ...)` aliases.

This ledger is the public maturity companion to that generated catalog. If the
catalog lists a signature, read the tier marker beside that signature as the
generated summary of this ledger. The generated catalog is a beta discovery
aid, not a stable Markdown schema or stable API freeze.

## Current Tier Ledger

| Surface | Current tier | Notes |
| --- | --- | --- |
| `std.cli`, `std.env`, `std.io`, `std.math`, `std.num`, `std.option`, `std.process`, `std.result`, and byte-oriented `std.string` helpers | `beta-supported` | Current source facade helpers over promoted concrete runtime/value families. The beta label still allows additive changes and scoped migrations before `1.0.0`. |
| Concrete vector modules: `std.vec_i32`, `std.vec_i64`, `std.vec_f64`, `std.vec_bool`, and `std.vec_string` | `beta-supported` | These are concrete immutable vector lanes over existing concrete runtime families. This is not a generic collections freeze and does not imply executable generics, generic aliases, maps, sets, iterators, mutable vectors, slice/view APIs, runtime collection changes, or stable ABI/layout. |
| Basic filesystem text/status helpers such as `read_text`, `write_text_result`, `exists`, `is_file`, `is_dir`, `remove_file_result`, and `create_dir_result` | `beta-supported` | Current concrete file helpers remain beta contracts over host filesystem behavior. Platform-specific errors and richer host-error ADTs remain deferred. |
| Filesystem resource-handle helpers such as `open_text_read_result`, `read_open_text_result`, `close_result`, `read_text_via_handle_result`, and `close_ok` | `experimental` | Handles are beta-scoped opaque `i32` values. Writable handles, directory handles/enumeration, stable handle ABI/layout, and richer platform error policy remain deferred. |
| `std.json` | `experimental` | Includes compact JSON text construction, exact primitive scalar token parsing, ASCII string-token parsing, and scalar document parsing. Object/array parsing, recursive `JsonValue`, parser/tokenizer objects, maps/sets, streaming, broad Unicode escape policy, embedded NUL policy, stable text encoding policy, and stable JSON API compatibility remain deferred. |
| `std.net` | `experimental` | Current blocking loopback TCP facade only. DNS, TLS, UDP, async IO, non-loopback binding, HTTP frameworks, stable socket ABI/layout, and rich host-error ADTs remain deferred. |
| `std.random` and `std.time` | `experimental` | Available as narrow beta host facades, but deterministic testing policy, seeding/time-source contracts, monotonic/wall-clock distinctions, reproducibility guarantees, and stable platform behavior remain deferred. |
| Non-exported helper names, module-local aliases, private runtime symbols, generated catalog internals, and release-tool implementation details | `internal` | Not part of the public standard-library compatibility surface. |

## Explicit Non-Changes

This ledger does not promote:

- source-language syntax
- standard-library helper additions, removals, or renames
- compiler-known runtime names
- runtime behavior changes
- executable generics or generic aliases
- generic stdlib dispatch
- maps, sets, iterators, mutable vectors, or slice/view APIs
- object/array JSON parsing or stable JSON schemas
- DNS, TLS, UDP, async networking, or non-loopback binding
- stable resource-handle ABI/layout
- stable artifact-manifest schema
- stable generated Markdown schema
- stable `1.0.0` standard-library/API compatibility freeze