slovo/README.md

# Slovo

Slovo (ⰔⰎⰑⰂⰑ) is a typed structural programming language and toolchain.

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.11`.

## Repository Layout

```text
compiler/       Glagol, the first Slovo compiler
runtime/        C runtime used by hosted native builds
lib/std/        source-authored Slovo standard-library facades
examples/       compiler-supported Slovo examples and projects
benchmarks/     local benchmark comparison harnesses
docs/language/  language manifest, specs, roadmap, and release notes
docs/compiler/  compiler manifest, roadmap, and release notes
docs/papers/    whitepapers and generated publication PDFs
scripts/        local release and document tooling
```

## Beta Scope

`1.0.0-beta.11` 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
bundle, the `1.0.0-beta.5` local package/workspace discipline bundle, and the
`1.0.0-beta.6` loopback networking foundation, plus the `1.0.0-beta.7`
serialization/data-interchange foundation and the `1.0.0-beta.8` concrete type
alias foundation, the `1.0.0-beta.9` collection alias unification and
generic reservation slice, the `1.0.0-beta.10` developer-experience API
discovery slice, and the `1.0.0-beta.11` local package API documentation
slice. The language baseline supports practical local
command-line, file, and loopback-network programs with:

- modules, explicit imports, packages, and local workspaces
- `new`, `check`, `fmt`, `test`, `doc`, `symbols`, `build`, `run`, and
  `clean`
- `i32`, `i64`, `u32`, `u64`, `f64`, `bool`, `string`, and internal `unit`
- structs, enums, fixed arrays, concrete vectors, option/result families, and
  current `match`
- module-local transparent concrete type aliases
- explicit `std/*.slo` imports from `lib/std`, installed `share/slovo/std`, or
  `SLOVO_STD_PATH`
- beta-scoped loopback TCP handles through `std.net`
- JSON string quoting and compact JSON text construction through `std.json`
- hosted native builds through LLVM IR, Clang, and `runtime/runtime.c`

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.
`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.
`glagol doc <file|project|workspace> -o <dir>` now includes deterministic public
API sections for local package and module documentation: exact exported
function signatures, exported struct fields, exported enum variants and payload
types, non-export filtering, and module-local alias normalization.

Still deferred before stable: executable generics, maps/sets, broad package
registry semantics, stable Markdown schema, stable stdlib/API compatibility
freeze, DNS/TLS/async networking, LSP/watch guarantees, SARIF and daemon
protocols, diagnostics schema policy, re-exports/globs/hierarchical modules,
stable ABI and layout, and runtime changes for generic collections.

The next likely language slice after `1.0.0-beta.11` should continue from the
developer-experience, diagnostics, and reserved generic/collection lanes
without claiming executable generics, maps, sets, traits, inference,
monomorphization, iterators, ABI stability, runtime changes, LSP/watch
protocols, registry semantics, stable Markdown schema, or a
standard-library/API compatibility freeze until the contract and gates are
explicit.

## Build And Test

```bash
cargo test --manifest-path compiler/Cargo.toml
```

Run the full local release gate:

```bash
./scripts/release-gate.sh
```

Build the compiler binary:

```bash
cargo build --manifest-path compiler/Cargo.toml
./compiler/target/debug/glagol --version
```

Create and check a project:

```bash
./compiler/target/debug/glagol new hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol check hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol test hello
```

Build a native executable when Clang is available:

```bash
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol build hello -o hello/bin
```

## 1.0.0-beta.1 Tooling Additions

The `1.0.0-beta.1` release improves the common local development and install
loop without adding new source-language syntax.

Build and execute in one step:

```bash
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol run hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol clean hello
```

Create alternate project shapes:

```bash
./compiler/target/debug/glagol new numbers --template library
./compiler/target/debug/glagol new workspace-demo --template workspace
```

Install the current checkout:

```bash
PREFIX="$HOME/.local" ./scripts/install.sh
```

The installed layout is:

```text
<prefix>/bin/glagol
<prefix>/share/slovo/std/*.slo
<prefix>/share/slovo/runtime/runtime.c
```

Installed `glagol` discovers `share/slovo/std` and
`share/slovo/runtime/runtime.c` relative to its executable. `SLOVO_STD_PATH`
can still override standard-library search, `SLOVO_RUNTIME_C` or
`GLAGOL_RUNTIME_C` can override the runtime C input, and `GLAGOL_CLANG` can
select the Clang-compatible compiler.

## 1.0.0-beta.2 Runtime Resource Foundation

The `1.0.0-beta.2` release adds beta-scoped runtime/resource foundation work:

- `std.fs.open_text_read_result`
- `std.fs.read_open_text_result`
- `std.fs.close_result`
- `std.fs.exists`
- `std.fs.is_file`
- `std.fs.is_dir`
- `std.fs.remove_file_result`
- `std.fs.create_dir_result`
- matching explicit `lib/std/fs.slo` facades

These APIs use beta-scoped opaque `i32` file handles. They do not claim stable
file descriptors, writable streams, binary IO, directory handles, sockets,
async IO, platform error codes, or stable handle ABI/layout. Directory creation
is intentionally narrow and does not imply directory enumeration or recursive
filesystem APIs.

## 1.0.0-beta.3 Standard Library Stabilization

The `1.0.0-beta.3` release starts the standard-library stabilization slice. It
adds a generated standard-library API catalog and
`examples/projects/stdlib-composition`, a checked/tested/run-capable program
that composes `std.fs`, `std.string`, `std.math`, and `std.io`.

## 1.0.0-beta.4 Language Usability Diagnostics

The `1.0.0-beta.4` release improves diagnostics without changing the source
language surface. Project/workspace build and run entry failures now use
entry-specific diagnostic codes, and non-exhaustive `match` diagnostics have
clearer wording with deterministic found-arm output.

## 1.0.0-beta.5 Package And Workspace Discipline

The `1.0.0-beta.5` release tightens local package/workspace behavior. Local
workspaces may declare `[workspace] default_package = "name"` to select the
build/run entry package when multiple packages have entry modules. Duplicate
normalized workspace members and missing default-package references are now
dedicated diagnostics. `glagol doc <workspace> -o <dir>` includes a workspace
package/dependency summary, new workspace templates declare
`default_package = "app"`, and `docs/language/PACKAGES.md` documents the beta
local-package rules. Remote registries, lockfiles, semantic-version solving,
package publishing, and stable package ABI/layout remain deferred.

## 1.0.0-beta.6 Networking Foundation

The `1.0.0-beta.6` release adds a narrow blocking loopback TCP foundation:

- compiler-known `std.net.tcp_*_result` calls for connect, listen,
  bound-port lookup, accept, read-all, write-text, and close
- `lib/std/net.slo` source facades and explicit std/local example projects
- opaque beta-scoped `i32` socket handles with concrete `result` values

This is not a general networking stack. DNS, TLS, UDP, non-loopback binding,
async IO, HTTP frameworks, rich host-error ADTs, stable socket ABI/layout, and
automatic resource ownership remain deferred.

## 1.0.0-beta.7 Serialization And Data Interchange

The `1.0.0-beta.7` release adds a narrow JSON text-construction foundation:

- compiler-known `std.json.quote_string` for deterministic compact JSON string
  quoting
- `lib/std/json.slo` source helpers for scalar values, fields, small arrays,
  and small objects
- explicit std/local JSON example projects and a `json-quote-loop` benchmark
  scaffold

This is not a complete JSON library. Full parsing, recursive JSON values,
maps/sets, streaming encoders, schema validation, Unicode normalization, and a
stable data-interchange API freeze remain deferred.

## 1.0.0-beta.8 Concrete Type Alias Foundation

The `1.0.0-beta.8` release adds transparent concrete type aliases:

```slo
(type JsonText string)
```

Aliases are module-local names for already supported concrete target types.
They may appear in local signatures and annotations, but they do not create new
runtime representations or stable ABI names. Project imports of functions that
use aliases see the resolved concrete target type. Alias exports, imports,
re-exports, generic aliases, parameterized aliases, maps/sets, and new
compiler-known runtime names remain out of scope.

## 1.0.0-beta.9 Collection Alias Unification And Generic Reservation

The `1.0.0-beta.9` release applies beta.8 concrete aliases inside the current
source-authored collection/value-family facades. The public helper names and
runtime behavior remain concrete: current vectors, options, and results are
still concrete families, and the local aliases are erased before lowering.

This release also reserves the generic/map/set direction through diagnostics
and documentation only. It does not implement executable generics, maps, sets,
traits, inference, monomorphization, iterators, stable ABI/layout promises, or
a stable standard-library API freeze.

## 1.0.0-beta.10 Developer Experience API Discovery

The `1.0.0-beta.10` release upgrades the generated standard-library API
catalog from exported helper names to exact exported helper signatures. The
renderer verifies that every exported helper has a matching `(fn ...)` form,
normalizes module-local concrete aliases from the public signatures, omits
non-exported helpers and `(type ...)` aliases, and keeps the catalog generated
from `lib/std/*.slo`.

It also adds `glagol symbols <file.slo|project|workspace>` as an
editor-facing metadata command. The output is deterministic S-expression text
using `slovo.symbols` schema version `1.0.0-beta.10`; it includes module paths,
source spans/ranges, imports, exports, aliases, structs, enums, functions,
tests, and workspace package labels.

This release is tooling, documentation, and API-discovery work. It does not
add executable generics, maps, sets, new runtime helpers, new compiler-known
runtime names, ABI/layout guarantees, an LSP server, watch mode, or a stable
standard-library API freeze.

## 1.0.0-beta.11 Local Package API Documentation

The `1.0.0-beta.11` release extends the beta.10 API discovery lane to local
package and module documentation. `glagol doc <file|project|workspace> -o <dir>`
includes deterministic exported/public API sections for local modules and
workspace packages.

Those sections list exact exported function signatures, exported struct fields,
and exported enum variants with payload types. They omit non-exported
functions, structs, enums, tests, and aliases from the public API surface, and
they normalize module-local concrete aliases before rendering public types.

This remains beta API discovery. It does not freeze the Markdown schema, create
a stable stdlib/API compatibility freeze, add LSP/watch behavior, define
SARIF or daemon protocols, set diagnostics schema policy, implement executable
generics, maps, or sets, add re-exports, globs, or hierarchical modules, or
define package registry semantics.

## Documentation

- [Language Manifest](docs/language/MANIFEST.md)
- [Language Specification](docs/language/SPEC-v1.md)
- [Local Package And Workspace Guide](docs/language/PACKAGES.md)
- [Standard Library API Catalog](docs/language/STDLIB_API.md)
- [Compiler Manifest](docs/compiler/GLAGOL_COMPILER_MANIFEST.md)
- [Post-Beta Roadmap](docs/POST_BETA_ROADMAP.md)
- [Slovo Whitepaper](docs/papers/SLOVO_WHITEPAPER.md)
- [Glagol Whitepaper](docs/papers/GLAGOL_WHITEPAPER.md)

Generated PDFs live beside their Markdown sources in `docs/papers/`.
Regenerate them with `./scripts/render-doc-pdfs.sh` before documentation
releases.

## License

Slovo is licensed under either the MIT License or the Apache License, Version
2.0, at your option.