slovo/docs/language/STDLIB_TIERS.md

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