# Slovo Collection Ledger

Status: beta design ledger for `1.0.0-beta.15`.

This document inventories the current concrete collection and value-family
surface without redefining the generated public API catalog. Exact exported
helper signatures live in
[`STDLIB_API.md`](STDLIB_API.md), which is generated from `lib/std/*.slo`.
This ledger records design boundaries, pressure, and promotion prerequisites
for future generic collection work.

`1.0.0-beta.15` is documentation/design and compiler-boundary hardening. It
does not change the source language, typed core, runtime,
standard-library/API surface, diagnostic output shape, diagnostic codes,
diagnostic schema, benchmark metadata schema, ABI/layout behavior, or
performance claims. It does reword current reserved generic/map/set diagnostic
prose from beta.9-specific text to current-beta wording.

## Catalog Boundary

[`STDLIB_API.md`](STDLIB_API.md) remains the source of truth for current
exported standard-library helper signatures. It normalizes module-local
concrete aliases such as `VecI32`, `OptionString`, and `ResultU64` to concrete
public types, and omits non-exported helpers and `(type ...)` aliases.

This ledger intentionally does not duplicate generated module or helper
counts. If an exact signature or count is needed, use the generated catalog.
If this ledger and the catalog drift, the catalog describes the generated API
surface while this file describes the intended design boundary.

## Current Concrete Surface

| Surface | Current concrete families | Public catalog reference | Boundary |
| --- | --- | --- | --- |
| Concrete vectors | `(vec i32)`, `(vec i64)`, `(vec f64)`, `(vec bool)`, `(vec string)` | [`std.vec_i32`](STDLIB_API.md#stdvec_i32), [`std.vec_i64`](STDLIB_API.md#stdvec_i64), [`std.vec_f64`](STDLIB_API.md#stdvec_f64), [`std.vec_bool`](STDLIB_API.md#stdvec_bool), [`std.vec_string`](STDLIB_API.md#stdvec_string) | Concrete immutable value-family helpers over the existing vector runtime names. No generic vector dispatch, element-level mutation, slice/view API, iterator API, nested vector family, new runtime helper name, stable helper-symbol contract, or ABI/layout promise is implied. |
| Option value families | `(option i32)`, `(option u32)`, `(option i64)`, `(option u64)`, `(option f64)`, `(option bool)`, `(option string)` | [`std.option`](STDLIB_API.md#stdoption) | Concrete constructors, observers, unwrap/fallback helpers, and option-to-result bridges. No generic option helper, mapping/chaining API, transpose/flatten family, stable API freeze, or payload-family expansion is implied. |
| Result value families | `(result i32 i32)`, `(result u32 i32)`, `(result i64 i32)`, `(result u64 i32)`, `(result f64 i32)`, `(result bool i32)`, `(result string i32)` | [`std.result`](STDLIB_API.md#stdresult) | Concrete `i32` error-code result helpers. No generic result helper, rich error ADT, mapping/chaining API, transpose/flatten family, stable API freeze, or alternate error payload family is implied. |
| Host and parsing result/option flows | Concrete option/result values returned by current host, CLI, file, network, parse, and numeric helpers | [`std.cli`](STDLIB_API.md#stdcli), [`std.env`](STDLIB_API.md#stdenv), [`std.fs`](STDLIB_API.md#stdfs), [`std.io`](STDLIB_API.md#stdio), [`std.net`](STDLIB_API.md#stdnet), [`std.num`](STDLIB_API.md#stdnum), [`std.string`](STDLIB_API.md#stdstring) | These helpers expose the same concrete value families through ordinary source facades. They do not create generic payload types, generic host errors, stable ABI names, or a stable compatibility freeze. |

Fixed arrays are part of the current language surface, but they are not a
standard-library helper family in the generated API catalog. Future work that
connects arrays to slices, views, iterators, maps, sets, or generic collection
helpers must define its own language, runtime, diagnostic, and documentation
contract.

## Design Pressure

The current surface deliberately repeats concrete helper families. That
duplication has been useful because each family could be promoted with narrow
tests and without a generic type system, but it now creates clear pressure:

- Vector helpers repeat construction, indexing, fallback, search, query,
  concatenation, slicing-by-copy, replacement, and removal names across five
  concrete element families.
- `std.option` and `std.result` repeat constructor, observer, unwrap,
  fallback, and bridge helpers across concrete payload families, including the
  unsigned payloads added before beta.
- Helper parity can drift between concrete modules, as shown by the beta12
  vector query and prefix parity release.
- Module-local concrete aliases reduce source repetition inside facades, and
  the generated catalog hides those aliases from public signatures, but aliases
  do not define generic API compatibility or migration behavior.
- Host and parsing facades spread concrete option/result values through the
  broader API surface, so future generic work must account for both dedicated
  `std.option`/`std.result` modules and callers that already depend on
  concrete return types.

This pressure is a reason to design generics carefully, not a license to infer
generic behavior from existing concrete helpers.

## Promotion Prerequisites

Before any executable generic collection feature is promoted, a release must
define and gate the full contract for that feature. At minimum:

- Executable generics need source syntax, type-parameter rules, explicit
  inference policy, type-checking behavior, formatter layout, typed-core
  representation, lowering/monomorphization or dispatch strategy, diagnostic
  coverage, public documentation, examples, and migration rules for existing
  concrete helpers.
- Generic aliases need a separate alias contract, including parameter syntax,
  allowed targets, cycle checks, export/import visibility, formatter behavior,
  diagnostics, and the relationship to runtime layout and public API docs.
- Maps and sets need key/value constraints, equality and hashing or ordering
  policy, construction and update semantics, iteration order or non-order
  policy, error behavior, runtime/resource ownership, diagnostics, and public
  API stability rules.
- Iterators need an ownership and lifetime model, exhaustion semantics,
  composition rules, interaction with `match` and future loops, diagnostics,
  and guarantees about whether iteration is copying, borrowing, or consuming.
- Mutable vectors need element-mutation syntax, aliasing and ownership rules,
  capacity/reallocation behavior, interaction with whole-value `var` / `set`,
  runtime helper names, trap/error behavior, diagnostics, and layout/ABI
  boundaries.
- Slice/view APIs need borrowing or ownership rules, bounds behavior,
  invalidation rules when mutation exists, array/vector/string applicability,
  formatter behavior, diagnostics, and runtime representation boundaries.
- Any stable stdlib/API claim needs explicit stable and experimental tiers,
  compatibility and deprecation policy, migration tests, generated API-doc
  behavior, and release-gate coverage.

Until those prerequisites are satisfied by a specific release, the current
concrete families remain the entire supported collection/value-family surface.

## Unsupported Boundaries

Current diagnostics that reject generic aliases, unsupported alias targets,
unsupported collection forms, unsupported vector element types, maps, sets,
iterators, slice/view APIs, mutable element operations, or broader
option/result payload shapes are boundary diagnostics. They document where the
current beta stops.

`1.0.0-beta.15` does not add, remove, rename, or reclassify diagnostic codes.
It does not change the `slovo.diagnostic` schema, JSON/S-expression output
shape, spans, expected/found values, hints, or human-readable diagnostic prose
policy. The only diagnostic-fixture change in this release is reserved-boundary
message text that no longer names beta.9 as the unsupported stage. Future
releases that change diagnostics for collection boundaries must do so through
the diagnostic policy in [`DIAGNOSTICS.md`](DIAGNOSTICS.md) and their own
release gates.

## Explicit Non-Changes

This ledger does not promote:

- executable generics
- generic aliases or parameterized aliases
- generic stdlib dispatch
- maps or sets
- iterator APIs
- mutable vector APIs
- slice/view APIs
- new runtime names or helper symbols
- stdlib/API additions, removals, or renames
- diagnostic output shape, code, schema, span, expected/found, or hint changes
- benchmark metadata schema changes
- ABI/layout guarantees
- performance claims or thresholds
- a stable `1.0.0` stdlib/API freeze