140 lines
8.5 KiB
Markdown
140 lines
8.5 KiB
Markdown
# 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
|