Release 1.0.0-beta.23 stdlib stability tier catalog
This commit is contained in:
sanjin
parent
7f71beac4c
commit
05ff5be5c5
@ -0,0 +1,73 @@
|
||||
# 1.0.0-beta.23 Standard Library Stability Tier Ledger And Catalog Alignment
|
||||
|
||||
## Scope
|
||||
|
||||
`1.0.0-beta.23` is a documentation/catalog clarity slice for the standard
|
||||
library. It adds a public stability-tier ledger and aligns the surrounding
|
||||
README, roadmap, release-note, and specification text with the generated API
|
||||
catalog boundary.
|
||||
|
||||
This release does not change the source language, typed core, runtime
|
||||
capabilities, standard-library helper surface, compiler-known runtime names,
|
||||
ABI/layout policy, or package behavior. It does change generated catalog
|
||||
output and release-gate checks so tier metadata is visible and enforced.
|
||||
|
||||
## Contract
|
||||
|
||||
The public standard-library docs use exactly these tier labels:
|
||||
|
||||
- `beta-supported`
|
||||
- `experimental`
|
||||
- `internal`
|
||||
|
||||
The generated `docs/language/STDLIB_API.md` catalog remains the exact exported
|
||||
signature inventory generated from `lib/std/*.slo`. The new
|
||||
`docs/language/STDLIB_TIERS.md` ledger records maturity and stability
|
||||
expectations for those helpers and surrounding standard-library domains.
|
||||
|
||||
Experimental domains in the beta23 ledger include JSON, loopback networking,
|
||||
random/time, and filesystem resource-handle helpers. Concrete vector modules
|
||||
remain beta-supported concrete lanes; they are not a generic collections
|
||||
freeze and do not imply executable generics, maps, sets, iterators, mutable
|
||||
vectors, slice/view APIs, runtime collection changes, or stable ABI/layout.
|
||||
|
||||
## Non-Scope
|
||||
|
||||
This scope does not add:
|
||||
|
||||
- source-language syntax
|
||||
- standard-library helpers
|
||||
- compiler-known `std.*` runtime names
|
||||
- runtime C capabilities
|
||||
- package, workspace, import, or registry behavior
|
||||
- stable standard-library/API compatibility freeze
|
||||
- stable manifest schema freeze
|
||||
- stable Markdown schema freeze
|
||||
- stable ABI/layout
|
||||
- performance claims
|
||||
- beta maturity beyond the existing `1.0.0-beta` line
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `docs/language/STDLIB_TIERS.md` defines the public tier labels and their
|
||||
current meaning.
|
||||
- The tier ledger marks JSON, loopback networking, random/time, and filesystem
|
||||
resource-handle helpers as experimental domains.
|
||||
- The tier ledger records concrete vector modules as beta-supported concrete
|
||||
lanes without claiming generic collection stability.
|
||||
- README, `lib/std/README.md`, language release notes, language roadmap,
|
||||
post-beta roadmap, and the v1 spec link or describe the tier ledger.
|
||||
- Documentation states beta23 is docs/catalog tooling clarity only and does
|
||||
not add language, stdlib, runtime, stable schema, or stable API behavior.
|
||||
- The generated API catalog emits tier metadata, and the release gate checks
|
||||
that experimental tiers remain represented.
|
||||
|
||||
## Suggested Gates
|
||||
|
||||
```bash
|
||||
node --check scripts/render-stdlib-api-doc.js
|
||||
node --check scripts/check-stdlib-api-tiers.js
|
||||
./scripts/render-stdlib-api-doc.sh
|
||||
./scripts/check-stdlib-api-tiers.js
|
||||
git diff --check
|
||||
```
|
||||
54
.llm/reviews/BETA_23_RELEASE_REVIEW.md
Normal file
54
.llm/reviews/BETA_23_RELEASE_REVIEW.md
Normal file
@ -0,0 +1,54 @@
|
||||
# Beta23 Release Review
|
||||
|
||||
Verdict: PASS with notes.
|
||||
|
||||
## Findings
|
||||
|
||||
No blocking or non-blocking findings in the reviewed scope.
|
||||
|
||||
## Scope Reviewed
|
||||
|
||||
- `scripts/render-stdlib-api-doc.js` tier rendering.
|
||||
- `scripts/check-stdlib-api-tiers.js` tier gate.
|
||||
- `scripts/release-gate.sh` integration.
|
||||
- Generated `docs/language/STDLIB_API.md`.
|
||||
- `docs/language/STDLIB_TIERS.md`, README, release notes, roadmaps, and spec updates.
|
||||
- Compiler package version bump and compiler release documentation.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
- PASS: `docs/language/STDLIB_TIERS.md` defines the public tier labels and explains the current beta meaning. See `docs/language/STDLIB_TIERS.md:21` through `docs/language/STDLIB_TIERS.md:25`.
|
||||
- PASS: The tier ledger marks JSON, loopback networking, random/time, and filesystem resource-handle helpers as experimental domains. See `docs/language/STDLIB_TIERS.md:46` through `docs/language/STDLIB_TIERS.md:49`.
|
||||
- PASS: The tier ledger records concrete vector modules as beta-supported concrete lanes without claiming generic collection stability. See `docs/language/STDLIB_TIERS.md:44`.
|
||||
- PASS: The generated API catalog emits tier metadata and summary counts. See `docs/language/STDLIB_API.md:6` through `docs/language/STDLIB_API.md:24`.
|
||||
- PASS: Generated catalog classification matches the beta23 contract: filesystem handle helpers are experimental in `docs/language/STDLIB_API.md:115` through `docs/language/STDLIB_API.md:119`; `std.json`, `std.net`, `std.random`, and `std.time` are experimental in `docs/language/STDLIB_API.md:195` through `docs/language/STDLIB_API.md:240`, `docs/language/STDLIB_API.md:294` through `docs/language/STDLIB_API.md:308`, `docs/language/STDLIB_API.md:425` through `docs/language/STDLIB_API.md:432`, and `docs/language/STDLIB_API.md:540` through `docs/language/STDLIB_API.md:547`.
|
||||
- PASS: Concrete vector modules retain explicit no-generic-collection-freeze notes in generated output. Representative coverage is `docs/language/STDLIB_API.md:549` through `docs/language/STDLIB_API.md:554`, with the same note repeated for the other concrete `std.vec_*` modules.
|
||||
- PASS: The renderer implements the tier map and emits per-module/per-helper tiers. See `scripts/render-stdlib-api-doc.js:12` through `scripts/render-stdlib-api-doc.js:46`, `scripts/render-stdlib-api-doc.js:245` through `scripts/render-stdlib-api-doc.js:263`, and `scripts/render-stdlib-api-doc.js:297` through `scripts/render-stdlib-api-doc.js:330`.
|
||||
- PASS: The tier gate checks stale wording, summary tier definitions, experimental module/helper coverage, and vector boundary notes. See `scripts/check-stdlib-api-tiers.js:47` through `scripts/check-stdlib-api-tiers.js:80`.
|
||||
- PASS: `scripts/release-gate.sh` runs syntax checks for both tier scripts and executes the tier checker after catalog rendering. See `scripts/release-gate.sh:12` through `scripts/release-gate.sh:16`.
|
||||
- PASS: README, `lib/std/README.md`, language release notes, language roadmap, post-beta roadmap, and v1 spec link or describe the tier ledger and non-scope. Representative references: `README.md:69` through `README.md:79`, `lib/std/README.md:174` through `lib/std/README.md:184`, `docs/language/RELEASE_NOTES.md:53` through `docs/language/RELEASE_NOTES.md:69`, `docs/language/ROADMAP.md:109` through `docs/language/ROADMAP.md:119`, `docs/POST_BETA_ROADMAP.md:121` through `docs/POST_BETA_ROADMAP.md:132`, and `docs/language/SPEC-v1.md:268` through `docs/language/SPEC-v1.md:279`.
|
||||
- PASS: Documentation states beta23 is documentation/catalog tooling clarity only and does not add language, stdlib, runtime, stable schema, ABI/layout, or stable API behavior. See `docs/language/STDLIB_TIERS.md:10` through `docs/language/STDLIB_TIERS.md:15` and `docs/language/STDLIB_TIERS.md:52` through `docs/language/STDLIB_TIERS.md:68`.
|
||||
- PASS: Compiler package version and compiler release docs are aligned to `1.0.0-beta.23`. See `compiler/Cargo.toml:3`, `compiler/Cargo.lock:7`, `docs/compiler/RELEASE_NOTES.md:15` through `docs/compiler/RELEASE_NOTES.md:43`, and `docs/compiler/ROADMAP.md:126` through `docs/compiler/ROADMAP.md:132`.
|
||||
|
||||
## Verification
|
||||
|
||||
Ran:
|
||||
|
||||
```bash
|
||||
node --check scripts/render-stdlib-api-doc.js
|
||||
node --check scripts/check-stdlib-api-tiers.js
|
||||
./scripts/check-stdlib-api-tiers.js
|
||||
git diff --check
|
||||
rg -n '^- `experimental`' docs/language/STDLIB_API.md
|
||||
```
|
||||
|
||||
Result: all focused checks passed. The `rg` inspection confirmed 58 experimental helper signatures across the expected filesystem-handle, JSON, loopback networking, random, and time surfaces.
|
||||
|
||||
Recommended before release tag:
|
||||
|
||||
```bash
|
||||
./scripts/render-stdlib-api-doc.sh
|
||||
./scripts/release-gate.sh
|
||||
```
|
||||
|
||||
Note: run the full release gate after the generated catalog changes are staged or committed; the gate intentionally fails if `docs/language/STDLIB_API.md` has unstaged generated-doc drift.
|
||||
25
README.md
25
README.md
@ -6,7 +6,7 @@ This repository is the canonical public monorepo for the language design,
|
||||
standard library source, compiler, runtime, examples, benchmarks, and technical
|
||||
documents.
|
||||
|
||||
Current release: `1.0.0-beta.22`.
|
||||
Current release: `1.0.0-beta.23`.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
@ -24,7 +24,7 @@ scripts/ local release and document tooling
|
||||
|
||||
## Beta Scope
|
||||
|
||||
`1.0.0-beta.22` keeps the `1.0.0-beta` language baseline, includes the
|
||||
`1.0.0-beta.23` keeps the `1.0.0-beta` language baseline, includes the
|
||||
`1.0.0-beta.1` tooling/install hardening slice, the `1.0.0-beta.2`
|
||||
runtime/resource foundation bundle, the `1.0.0-beta.3` standard-library
|
||||
stabilization bundle, the `1.0.0-beta.4` language-usability diagnostics
|
||||
@ -44,7 +44,9 @@ the `1.0.0-beta.17` JSON primitive scalar parsing foundation, the
|
||||
`1.0.0-beta.19` test discovery and user-project conformance foundation, the
|
||||
`1.0.0-beta.20` string search and ASCII trim foundation, and the
|
||||
`1.0.0-beta.21` JSON document scalar parsing foundation, plus the
|
||||
`1.0.0-beta.22` run manifest and execution report hardening slice.
|
||||
`1.0.0-beta.22` run manifest and execution report hardening slice, and the
|
||||
`1.0.0-beta.23` standard-library stability tier ledger and catalog alignment
|
||||
slice.
|
||||
The language baseline supports practical local command-line, file, and
|
||||
loopback-network programs with:
|
||||
|
||||
@ -68,6 +70,13 @@ The generated standard-library API catalog is a beta discovery aid: it lists
|
||||
exported helper signatures from `lib/std/*.slo`, normalizes module-local
|
||||
concrete aliases such as `VecI32` and `ResultU64` to their concrete public
|
||||
types, and omits non-exported helpers and `(type ...)` aliases.
|
||||
The companion
|
||||
[`docs/language/STDLIB_TIERS.md`](docs/language/STDLIB_TIERS.md) ledger
|
||||
defines the public tier labels `beta-supported`, `experimental`, and
|
||||
`internal`, marks JSON, loopback networking, random/time, and filesystem
|
||||
resource-handle helpers as experimental domains, and keeps concrete vector
|
||||
modules as beta-supported concrete lanes rather than a generic collections
|
||||
freeze.
|
||||
`glagol symbols <file.slo|project|workspace>` emits deterministic
|
||||
editor-facing S-expression metadata for modules, imports, exports, aliases,
|
||||
structs, enums, functions, tests, source spans, and workspace package names.
|
||||
@ -177,6 +186,16 @@ syntax, standard-library helpers, compiler-known runtime names, runtime
|
||||
capabilities, package behavior, stable artifact-manifest schema guarantees,
|
||||
stable ABI/layout, or a stable stdlib/API freeze.
|
||||
|
||||
The `1.0.0-beta.23` standard-library stability tier ledger and catalog
|
||||
alignment slice adds the public
|
||||
[`STDLIB_TIERS.md`](docs/language/STDLIB_TIERS.md) maturity ledger beside the
|
||||
generated [`STDLIB_API.md`](docs/language/STDLIB_API.md) signature catalog.
|
||||
It is documentation/catalog tooling clarity only: no source-language syntax,
|
||||
stdlib helpers, compiler-known runtime names, runtime behavior, stable manifest
|
||||
schema, stable Markdown schema, stable ABI/layout, or stable stdlib/API freeze
|
||||
changes. The generated catalog and release gate now expose and check tier
|
||||
metadata.
|
||||
|
||||
Still deferred before stable: executable generics, generic aliases, maps/sets,
|
||||
broad package registry semantics, stable artifact-manifest schema, stable
|
||||
Markdown schema, stable stdlib/API compatibility freeze, DNS/TLS/async
|
||||
|
||||
2
compiler/Cargo.lock
generated
2
compiler/Cargo.lock
generated
@ -4,4 +4,4 @@ version = 3
|
||||
|
||||
[[package]]
|
||||
name = "glagol"
|
||||
version = "1.0.0-beta.22"
|
||||
version = "1.0.0-beta.23"
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "glagol"
|
||||
version = "1.0.0-beta.22"
|
||||
version = "1.0.0-beta.23"
|
||||
edition = "2021"
|
||||
description = "Glagol, the first compiler for the Slovo language"
|
||||
license = "MIT OR Apache-2.0"
|
||||
|
||||
@ -118,6 +118,19 @@ bytes `9`, `10`, `11`, `12`, `13`, and `32`. Unicode/grapheme semantics,
|
||||
case folding, regexes, tokenizers, mutable strings, slice/view syntax, new
|
||||
runtime names, and stable stdlib/API promises remain deferred.
|
||||
|
||||
Released in `1.0.0-beta.23`: the public
|
||||
[`docs/language/STDLIB_TIERS.md`](language/STDLIB_TIERS.md) ledger defines the
|
||||
current standard-library tier labels `beta-supported`, `experimental`, and
|
||||
`internal`, and aligns the docs around the generated
|
||||
[`docs/language/STDLIB_API.md`](language/STDLIB_API.md) signature catalog.
|
||||
JSON, loopback networking, random/time, and filesystem resource-handle helpers
|
||||
are documented as experimental domains. Concrete vector modules remain
|
||||
beta-supported concrete lanes, not a generic collections freeze. The slice is
|
||||
documentation/catalog tooling clarity only: no syntax, helper, runtime,
|
||||
manifest-schema, Markdown-schema, ABI/layout, or stable stdlib/API behavior
|
||||
changes. It updates generated catalog output and the release gate so tier
|
||||
metadata is visible and checked.
|
||||
|
||||
Why third: stdlib growth is already broad enough that naming and stability tiers
|
||||
matter more than adding another isolated helper group.
|
||||
|
||||
@ -541,7 +554,8 @@ foundation before richer string or data-interchange APIs are credible.
|
||||
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
|
||||
- `lib/std` has explicit beta-supported, experimental, and internal tiers plus
|
||||
a later stable-tier/deprecation policy before `1.0.0`
|
||||
- package/workspace behavior is deterministic
|
||||
- conformance tests cover user-shaped projects
|
||||
- release gates are reproducible on a clean checkout
|
||||
|
||||
@ -12,6 +12,36 @@ integration/readiness release, not the first real beta.
|
||||
|
||||
No active unreleased compiler scope is documented here yet.
|
||||
|
||||
## 1.0.0-beta.23
|
||||
|
||||
Release label: `1.0.0-beta.23`
|
||||
|
||||
Release date: 2026-05-23
|
||||
|
||||
Release state: standard-library stability tier ledger and catalog alignment
|
||||
|
||||
### Summary
|
||||
|
||||
The beta.23 compiler/tooling slice aligns generated standard-library API
|
||||
catalog output with the public tier ledger:
|
||||
|
||||
- Bump the `glagol` compiler package version to `1.0.0-beta.23`.
|
||||
- Render per-module and per-helper `beta-supported` or `experimental` tier
|
||||
metadata in `docs/language/STDLIB_API.md`.
|
||||
- Add `scripts/check-stdlib-api-tiers.js` and wire it into the release gate.
|
||||
- Mark JSON, loopback networking, random/time, and filesystem resource-handle
|
||||
helpers as experimental in generated catalog output.
|
||||
- Keep concrete vector modules beta-supported concrete lanes with an explicit
|
||||
no-generic-collection-freeze note.
|
||||
|
||||
### Explicit Deferrals
|
||||
|
||||
This release does not implement source-language syntax, standard-library
|
||||
helpers, compiler-known `std.*` runtime names, runtime C capabilities, package
|
||||
or workspace behavior, stable artifact-manifest schema guarantees, stable
|
||||
Markdown schemas, LSP/watch/SARIF/daemon protocols, performance claims,
|
||||
stable ABI/layout, or a stable standard-library compatibility contract.
|
||||
|
||||
## 1.0.0-beta.22
|
||||
|
||||
Release label: `1.0.0-beta.22`
|
||||
|
||||
@ -21,8 +21,8 @@ general-purpose beta release.
|
||||
|
||||
A Glagol feature is done only when it has parser/lowerer support, checker behavior, diagnostics for invalid forms, backend behavior or explicit unsupported diagnostics, and tests.
|
||||
|
||||
Current stage: `1.0.0-beta.22`, released on 2026-05-23 as run manifest and
|
||||
execution report hardening. It keeps the
|
||||
Current stage: `1.0.0-beta.23`, released on 2026-05-23 as standard-library
|
||||
stability tier ledger and catalog alignment. It keeps the
|
||||
`1.0.0-beta` language/compiler support baseline and includes the
|
||||
`1.0.0-beta.1` tooling hardening release, the `1.0.0-beta.2` runtime/resource
|
||||
foundation release, the `1.0.0-beta.3` standard-library stabilization release,
|
||||
@ -123,6 +123,14 @@ CLI evidence metadata under the existing `slovo.artifact-manifest` version
|
||||
`1` contract, not a stable schema freeze, and it adds no source-language,
|
||||
runtime, package, or standard-library surface.
|
||||
|
||||
The beta.23 compiler/tooling slice bumps the package version and updates
|
||||
generated `docs/language/STDLIB_API.md` output with per-module and per-helper
|
||||
tier metadata. It adds a release-gate checker for the tier catalog, marks JSON,
|
||||
loopback networking, random/time, and filesystem resource-handle helpers as
|
||||
experimental, and keeps concrete vector modules beta-supported concrete lanes
|
||||
without claiming generic collection stability. It adds no source-language,
|
||||
runtime, package, or standard-library helper surface.
|
||||
|
||||
Generic vectors, generic collections, maps, sets, generic stdlib dispatch,
|
||||
runtime collection changes, collection unification, stable human diagnostic
|
||||
text, stable artifact-manifest or Markdown schema freezes, LSP/watch
|
||||
|
||||
@ -8,7 +8,7 @@ Historical `exp-*` releases listed here are experimental maturity milestones.
|
||||
The pushed tag `v2.0.0-beta.1` is historical. It is now documented as an
|
||||
experimental integration/readiness release, not as a beta maturity claim.
|
||||
|
||||
The current release is `1.0.0-beta.22`, published on 2026-05-23. It keeps the
|
||||
The current release is `1.0.0-beta.23`, published on 2026-05-23. It keeps the
|
||||
`1.0.0-beta` language surface, includes the first post-beta tooling/install
|
||||
hardening bundle from `1.0.0-beta.1`, and adds the first runtime/resource
|
||||
foundation bundle from `1.0.0-beta.2` plus the first standard-library
|
||||
@ -32,12 +32,42 @@ foundation from `1.0.0-beta.18`, the test discovery and user-project
|
||||
conformance foundation from `1.0.0-beta.19`, and the string search and ASCII
|
||||
trim foundation from `1.0.0-beta.20`, plus the JSON document scalar parsing
|
||||
foundation from `1.0.0-beta.21`, and the run manifest execution-report
|
||||
hardening slice from `1.0.0-beta.22`.
|
||||
hardening slice from `1.0.0-beta.22`, plus the standard-library stability tier
|
||||
ledger and catalog alignment slice from `1.0.0-beta.23`.
|
||||
|
||||
## Unreleased
|
||||
|
||||
No active unreleased language scope is documented here yet.
|
||||
|
||||
## 1.0.0-beta.23
|
||||
|
||||
Release label: `1.0.0-beta.23`
|
||||
|
||||
Release name: Standard Library Stability Tier Ledger And Catalog Alignment
|
||||
|
||||
Release date: 2026-05-23
|
||||
|
||||
Status: released beta documentation/catalog clarity on the `1.0.0-beta`
|
||||
language baseline.
|
||||
|
||||
This release adds [`STDLIB_TIERS.md`](STDLIB_TIERS.md) as the public maturity
|
||||
ledger for the generated [`STDLIB_API.md`](STDLIB_API.md) standard-library API
|
||||
catalog. The ledger defines the tier labels `beta-supported`, `experimental`,
|
||||
and `internal`.
|
||||
|
||||
The beta23 ledger classifies JSON, loopback networking, random/time, and
|
||||
filesystem resource-handle helpers as experimental domains. Concrete vector
|
||||
modules remain beta-supported concrete lanes; this is not a generic
|
||||
collections freeze and does not imply executable generics, maps, sets,
|
||||
iterators, mutable vectors, slice/view APIs, runtime collection changes, or
|
||||
stable ABI/layout.
|
||||
|
||||
This release adds no source-language syntax, standard-library helpers,
|
||||
compiler-known runtime names, runtime behavior, package behavior, stable
|
||||
artifact-manifest schema, stable Markdown schema, stable ABI/layout, or stable
|
||||
stdlib/API compatibility freeze. It does update generated catalog output and
|
||||
the release gate so tier metadata is visible and checked.
|
||||
|
||||
## 1.0.0-beta.22
|
||||
|
||||
Release label: `1.0.0-beta.22`
|
||||
|
||||
@ -8,8 +8,8 @@ Guiding rule: the manifest wins. A feature is not accepted until it has surface
|
||||
Long-horizon planning lives in `.llm/ROADMAP_TO_STABLE.md`. It defines the
|
||||
release train beyond the first real general-purpose beta Slovo contract.
|
||||
|
||||
Current stage: `1.0.0-beta.22`, released on 2026-05-23 as post-beta run
|
||||
manifest and execution-report hardening. It keeps the
|
||||
Current stage: `1.0.0-beta.23`, released on 2026-05-23 as post-beta
|
||||
standard-library stability tier ledger and catalog alignment. It keeps the
|
||||
`1.0.0-beta` language
|
||||
contract and includes the `1.0.0-beta.1` tooling hardening release, the
|
||||
`1.0.0-beta.2` runtime/resource foundation release, the `1.0.0-beta.3`
|
||||
@ -28,7 +28,8 @@ scalar token parsing, `1.0.0-beta.18` JSON string token parsing,
|
||||
`1.0.0-beta.19` test discovery and user-project conformance tooling, and
|
||||
`1.0.0-beta.20` string search and ASCII trim helpers, plus
|
||||
`1.0.0-beta.21` JSON document scalar parsing helpers, and
|
||||
`1.0.0-beta.22` run manifest execution-report hardening.
|
||||
`1.0.0-beta.22` run manifest execution-report hardening, plus
|
||||
`1.0.0-beta.23` standard-library stability tier documentation.
|
||||
|
||||
`1.0.0-beta.16` adds `std.string` source facades and examples for
|
||||
`byte_at_result`, `slice_result`, `starts_with`, and `ends_with`. These helpers
|
||||
@ -105,6 +106,18 @@ contract. It is not a stable schema freeze and adds no language syntax,
|
||||
standard-library helpers, runtime capabilities, package/import behavior,
|
||||
stable ABI/layout, or stable stdlib/API guarantees.
|
||||
|
||||
`1.0.0-beta.23` is documentation/catalog clarity, not a language or stdlib
|
||||
behavior feature. It adds [`STDLIB_TIERS.md`](STDLIB_TIERS.md) as the public
|
||||
stability-tier ledger beside the generated [`STDLIB_API.md`](STDLIB_API.md)
|
||||
signature catalog. The ledger defines `beta-supported`, `experimental`, and
|
||||
`internal`; marks JSON, loopback networking, random/time, and filesystem
|
||||
resource-handle helpers as experimental domains; and keeps concrete vector
|
||||
modules as beta-supported concrete lanes rather than a generic collections
|
||||
freeze. It adds no source-language syntax, helpers, runtime names, runtime
|
||||
behavior, stable manifest schema, stable Markdown schema, stable ABI/layout,
|
||||
or stable stdlib/API freeze. It does update generated catalog output and the
|
||||
release gate so tier metadata is visible and checked.
|
||||
|
||||
The final experimental precursor scope is `exp-125`, defined in
|
||||
`.llm/EXP_125_UNSIGNED_U32_U64_NUMERIC_AND_STDLIB_BREADTH_ALPHA.md`. Its
|
||||
unsigned direct-value flow, parse/format runtime lanes, and matching staged
|
||||
|
||||
@ -13,10 +13,10 @@ foundation, `1.0.0-beta.18` JSON string token parsing foundation,
|
||||
`1.0.0-beta.19` test discovery and user-project conformance tooling, and
|
||||
`1.0.0-beta.20` string search and ASCII trim foundation, and
|
||||
`1.0.0-beta.21` JSON document scalar parsing foundation, and
|
||||
`1.0.0-beta.22` run manifest and execution-report hardening. The
|
||||
language contract
|
||||
integrates
|
||||
promoted language slices through `exp-125` and the historical publication
|
||||
`1.0.0-beta.22` run manifest and execution-report hardening, and
|
||||
`1.0.0-beta.23` standard-library stability tier ledger and catalog alignment.
|
||||
The language contract integrates promoted language slices through `exp-125`
|
||||
and the historical publication
|
||||
baseline through `exp-123`. `1.0.0-beta` is the first real general-purpose
|
||||
beta release. `exp-125` completed the unsigned numeric and stdlib breadth
|
||||
precursor scope, `exp-124` is the last tagged experimental alpha language
|
||||
@ -265,6 +265,18 @@ Current v1 release surface and explicit experimental targets:
|
||||
add source-language syntax, stdlib helpers, compiler-known runtime names,
|
||||
runtime C capabilities, package/import behavior, stable artifact-manifest
|
||||
schema guarantees, stable ABI/layout, or stable stdlib/API freeze
|
||||
- `1.0.0-beta.23` standard-library stability tier ledger and catalog
|
||||
alignment:
|
||||
[`STDLIB_TIERS.md`](STDLIB_TIERS.md) defines the public tier labels
|
||||
`beta-supported`, `experimental`, and `internal` beside the generated
|
||||
[`STDLIB_API.md`](STDLIB_API.md) signature catalog. JSON, loopback
|
||||
networking, random/time, and filesystem resource-handle helpers are
|
||||
experimental domains. Concrete vector modules remain beta-supported concrete
|
||||
lanes, not a generic collections freeze. This target does not add
|
||||
source-language syntax, stdlib helpers, compiler-known runtime names,
|
||||
runtime behavior, stable artifact-manifest schema, stable Markdown schema,
|
||||
stable ABI/layout, or stable stdlib/API freeze. It does update generated
|
||||
catalog output and the release gate so tier metadata is visible and checked
|
||||
- `exp-1` owned runtime strings: compiler-known `std.string.concat` accepts two
|
||||
`string` values and returns an immutable runtime-owned `string`; existing
|
||||
string equality, length, printing, locals, parameters, returns, and calls work
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
68
docs/language/STDLIB_TIERS.md
Normal file
68
docs/language/STDLIB_TIERS.md
Normal file
@ -0,0 +1,68 @@
|
||||
# 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
|
||||
@ -47,7 +47,8 @@ whole-document scalar parse facades over `std.string.trim_ascii` and the
|
||||
existing exact value-token parsers; the
|
||||
`1.0.0-beta.8` concrete type alias target keeps that same helper surface while
|
||||
using local `JsonText` and `JsonField` aliases as transparent names for
|
||||
`string` JSON fragments.
|
||||
`string` JSON fragments; `1.0.0-beta.23` adds the public
|
||||
standard-library stability tier ledger without changing this helper surface.
|
||||
|
||||
This directory is the source home for staged standard library modules and
|
||||
examples. exp-44 lets project-mode source explicitly import `std/math.slo` as
|
||||
@ -170,6 +171,18 @@ make the standard library fully self-hosted, does not add automatic
|
||||
standard-library imports, and does not replace the compiler-known `std.*`
|
||||
standard-runtime calls cataloged in `../STANDARD_RUNTIME.md`.
|
||||
|
||||
`docs/language/STDLIB_API.md` remains the generated exact signature catalog
|
||||
for exported helpers in this directory. `docs/language/STDLIB_TIERS.md` is the
|
||||
beta23 public maturity ledger for that catalog. It defines the tier labels
|
||||
`beta-supported`, `experimental`, and `internal`; classifies JSON, loopback
|
||||
networking, random/time, and filesystem resource-handle helpers as
|
||||
experimental domains; and records the concrete vector modules as
|
||||
beta-supported concrete lanes, not a generic collections freeze. The tier
|
||||
ledger is documentation/catalog tooling clarity only and does not add helpers,
|
||||
syntax, runtime behavior, stable Markdown schema, or a stable stdlib/API
|
||||
freeze. The generated catalog and release gate now expose and check tier
|
||||
metadata.
|
||||
|
||||
The current `.slo` files use flat module declarations such as `(module math)`.
|
||||
For exp-44, exp-45, exp-47, exp-48, exp-49, exp-52, exp-53, exp-76, exp-94,
|
||||
exp-96, exp-97, exp-98, exp-99, exp-103, exp-104, exp-105, exp-107, exp-108,
|
||||
|
||||
80
scripts/check-stdlib-api-tiers.js
Executable file
80
scripts/check-stdlib-api-tiers.js
Executable file
@ -0,0 +1,80 @@
|
||||
#!/usr/bin/env node
|
||||
"use strict";
|
||||
|
||||
const fs = require("fs");
|
||||
const path = require("path");
|
||||
|
||||
const repoRoot = path.resolve(__dirname, "..");
|
||||
const catalogPath = path.join(repoRoot, "docs", "language", "STDLIB_API.md");
|
||||
const catalog = fs.readFileSync(catalogPath, "utf8");
|
||||
|
||||
function fail(message) {
|
||||
console.error(`stdlib API tier check failed: ${message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
function requireText(text, message) {
|
||||
if (!catalog.includes(text)) {
|
||||
fail(message);
|
||||
}
|
||||
}
|
||||
|
||||
function moduleSection(moduleName) {
|
||||
const marker = `### std.${moduleName}\n`;
|
||||
const start = catalog.indexOf(marker);
|
||||
if (start < 0) {
|
||||
fail(`missing std.${moduleName} module section`);
|
||||
}
|
||||
const next = catalog.indexOf("\n### std.", start + marker.length);
|
||||
return next < 0 ? catalog.slice(start) : catalog.slice(start, next);
|
||||
}
|
||||
|
||||
function requireModuleTier(moduleName, expectedTier) {
|
||||
const section = moduleSection(moduleName);
|
||||
if (!section.includes(`- Tiers: \`${expectedTier}\``)) {
|
||||
fail(`std.${moduleName} is not marked as ${expectedTier}`);
|
||||
}
|
||||
}
|
||||
|
||||
function requireHelperTier(moduleName, helperName, expectedTier) {
|
||||
const section = moduleSection(moduleName);
|
||||
const helperPattern = new RegExp(`^- \`${expectedTier}\` \`${helperName} `, "m");
|
||||
if (!helperPattern.test(section)) {
|
||||
fail(`std.${moduleName}.${helperName} is not marked as ${expectedTier}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (/experimental`: not used|experimental not used/i.test(catalog)) {
|
||||
fail("catalog still contains stale wording that says experimental is unused");
|
||||
}
|
||||
|
||||
requireText("- `beta-supported`:", "missing beta-supported tier definition");
|
||||
requireText("- `experimental`:", "missing experimental tier definition");
|
||||
requireText("- `internal`:", "missing internal tier definition");
|
||||
requireText("- `experimental` helper signatures:", "missing experimental summary count");
|
||||
requireText("Concrete `std.vec_*` modules are beta-supported as concrete helper families only; this does not freeze a generic collection API.", "missing concrete vector boundary");
|
||||
|
||||
if (!/^- `experimental` `[^`]+`/m.test(catalog)) {
|
||||
fail("catalog does not list any experimental helper signatures");
|
||||
}
|
||||
|
||||
for (const moduleName of ["json", "net", "random", "time"]) {
|
||||
requireModuleTier(moduleName, "experimental");
|
||||
}
|
||||
|
||||
for (const helperName of [
|
||||
"open_text_read_result",
|
||||
"read_open_text_result",
|
||||
"close_result",
|
||||
"read_text_via_handle_result",
|
||||
"close_ok",
|
||||
]) {
|
||||
requireHelperTier("fs", helperName, "experimental");
|
||||
}
|
||||
|
||||
for (const moduleName of ["vec_bool", "vec_f64", "vec_i32", "vec_i64", "vec_string"]) {
|
||||
const section = moduleSection(moduleName);
|
||||
if (!section.includes("- Note: concrete-only vector helper family; no generic collection freeze.")) {
|
||||
fail(`std.${moduleName} is missing the concrete vector boundary note`);
|
||||
}
|
||||
}
|
||||
@ -9,8 +9,11 @@ cd "${repo_root}"
|
||||
git diff --check
|
||||
bash -n scripts/install.sh
|
||||
bash -n scripts/render-stdlib-api-doc.sh
|
||||
node --check scripts/render-stdlib-api-doc.js
|
||||
node --check scripts/check-stdlib-api-tiers.js
|
||||
|
||||
"${repo_root}/scripts/render-stdlib-api-doc.sh"
|
||||
"${repo_root}/scripts/check-stdlib-api-tiers.js"
|
||||
git diff --check
|
||||
if ! git diff --quiet -- docs/language/STDLIB_API.md; then
|
||||
echo "standard library API catalog changed; review and commit generated docs before release" >&2
|
||||
|
||||
@ -9,6 +9,46 @@ const stdDir = path.join(repoRoot, "lib", "std");
|
||||
const outputPath = path.join(repoRoot, "docs", "language", "STDLIB_API.md");
|
||||
const readmePath = path.join(repoRoot, "README.md");
|
||||
|
||||
const TIERS = Object.freeze({
|
||||
BETA_SUPPORTED: "beta-supported",
|
||||
EXPERIMENTAL: "experimental",
|
||||
INTERNAL: "internal",
|
||||
});
|
||||
|
||||
const EXPERIMENTAL_MODULES = new Set(["json", "net", "random", "time"]);
|
||||
|
||||
const EXPERIMENTAL_HELPERS = new Map([
|
||||
[
|
||||
"fs",
|
||||
new Set([
|
||||
"open_text_read_result",
|
||||
"read_open_text_result",
|
||||
"close_result",
|
||||
"read_text_via_handle_result",
|
||||
"close_ok",
|
||||
]),
|
||||
],
|
||||
]);
|
||||
|
||||
const CONCRETE_VEC_MODULES = new Set(["vec_bool", "vec_f64", "vec_i32", "vec_i64", "vec_string"]);
|
||||
|
||||
function helperTier(moduleName, exportName) {
|
||||
if (EXPERIMENTAL_MODULES.has(moduleName)) {
|
||||
return TIERS.EXPERIMENTAL;
|
||||
}
|
||||
|
||||
const experimentalHelpers = EXPERIMENTAL_HELPERS.get(moduleName);
|
||||
if (experimentalHelpers && experimentalHelpers.has(exportName)) {
|
||||
return TIERS.EXPERIMENTAL;
|
||||
}
|
||||
|
||||
return TIERS.BETA_SUPPORTED;
|
||||
}
|
||||
|
||||
function uniqueSorted(values) {
|
||||
return Array.from(new Set(values)).sort();
|
||||
}
|
||||
|
||||
function tokenize(source) {
|
||||
const tokens = [];
|
||||
let index = 0;
|
||||
@ -204,7 +244,11 @@ function stdModules() {
|
||||
|
||||
for (const exported of module.exports) {
|
||||
if (functions.has(exported)) {
|
||||
signatures.push(functionSignature(functions.get(exported), aliases, relativePath));
|
||||
signatures.push({
|
||||
name: exported,
|
||||
signature: functionSignature(functions.get(exported), aliases, relativePath),
|
||||
tier: helperTier(module.name, exported),
|
||||
});
|
||||
} else if (aliases.has(exported)) {
|
||||
omittedAliasExports.push(exported);
|
||||
} else {
|
||||
@ -216,6 +260,7 @@ function stdModules() {
|
||||
fileName,
|
||||
relativePath,
|
||||
name: module.name,
|
||||
tiers: uniqueSorted(signatures.map((signature) => signature.tier)),
|
||||
signatures,
|
||||
omittedAliasExports,
|
||||
};
|
||||
@ -234,6 +279,15 @@ function releaseVersion() {
|
||||
function render(modules, version) {
|
||||
const totalExports = modules.reduce((count, module) => count + module.signatures.length, 0);
|
||||
const totalOmittedAliases = modules.reduce((count, module) => count + module.omittedAliasExports.length, 0);
|
||||
const tierCounts = new Map([
|
||||
[TIERS.BETA_SUPPORTED, 0],
|
||||
[TIERS.EXPERIMENTAL, 0],
|
||||
]);
|
||||
for (const module of modules) {
|
||||
for (const signature of module.signatures) {
|
||||
tierCounts.set(signature.tier, (tierCounts.get(signature.tier) || 0) + 1);
|
||||
}
|
||||
}
|
||||
const out = [];
|
||||
out.push("# Slovo Standard Library API Catalog");
|
||||
out.push("");
|
||||
@ -243,12 +297,13 @@ function render(modules, version) {
|
||||
out.push("## Stability Tiers");
|
||||
out.push("");
|
||||
out.push("- `beta-supported`: exported from `lib/std` and covered by source-search, promotion, or facade gates in the current beta line.");
|
||||
out.push(`- \`experimental\`: not used for exported \`lib/std\` helpers in \`${version}\`; future releases may mark new helpers this way before they graduate.`);
|
||||
out.push(`- \`experimental\`: exported from \`lib/std\` in \`${version}\`, but still has beta caveats around host behavior, resource handles, or API shape.`);
|
||||
out.push("- `internal`: helper names that are not exported from their module; they are intentionally omitted from this catalog.");
|
||||
out.push("");
|
||||
out.push("The catalog is a beta API discovery aid, not a stable `1.0.0` standard-library freeze.");
|
||||
out.push("Module-local concrete aliases are normalized in signatures so names such as `VecI32` and `ResultU64` do not leak into the public catalog.");
|
||||
out.push("Only exported `(fn ...)` helpers are listed; `(type ...)` aliases and non-exported helpers are omitted.");
|
||||
out.push("Concrete `std.vec_*` modules are beta-supported as concrete helper families only; this does not freeze a generic collection API.");
|
||||
out.push("");
|
||||
out.push("## Summary");
|
||||
out.push("");
|
||||
@ -256,6 +311,8 @@ function render(modules, version) {
|
||||
out.push(`- Exported helper signatures: ${totalExports}`);
|
||||
out.push(`- Exported type aliases omitted: ${totalOmittedAliases}`);
|
||||
out.push("- Default tier: `beta-supported`");
|
||||
out.push(`- \`${TIERS.BETA_SUPPORTED}\` helper signatures: ${tierCounts.get(TIERS.BETA_SUPPORTED) || 0}`);
|
||||
out.push(`- \`${TIERS.EXPERIMENTAL}\` helper signatures: ${tierCounts.get(TIERS.EXPERIMENTAL) || 0}`);
|
||||
out.push("");
|
||||
out.push("## Modules");
|
||||
out.push("");
|
||||
@ -263,11 +320,14 @@ function render(modules, version) {
|
||||
out.push(`### std.${module.name}`);
|
||||
out.push("");
|
||||
out.push(`- Path: \`${module.relativePath}\``);
|
||||
out.push("- Tier: `beta-supported`");
|
||||
out.push(`- Tiers: ${module.tiers.map((tier) => `\`${tier}\``).join(", ")}`);
|
||||
out.push(`- Exported helper signatures: ${module.signatures.length}`);
|
||||
if (CONCRETE_VEC_MODULES.has(module.name)) {
|
||||
out.push("- Note: concrete-only vector helper family; no generic collection freeze.");
|
||||
}
|
||||
out.push("");
|
||||
for (const signature of module.signatures) {
|
||||
out.push(`- \`${signature}\``);
|
||||
for (const { signature, tier } of module.signatures) {
|
||||
out.push(`- \`${tier}\` \`${signature}\``);
|
||||
}
|
||||
out.push("");
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user