Runtime library
Goalchemy programs import ordinary Go packages from two roots: github.com/eugenioenko/goalchemy/std and github.com/eugenioenko/goalchemy/lib. Both keep the Go standard library’s package names, so programs also build and run with the Go toolchain.
This file is generated from the Go sources under std/ and lib/, the contracts in specs/runtime, and the target mappings in targets/*/target.yaml. Edit those and run make spec-generate.
Three layers
Section titled “Three layers”| Layer | Location | Implemented | Use it for |
|---|---|---|---|
| Standard packages | std/ |
Once, in the Goalchemy subset. The compiler translates them with the program, like user code. | Pure logic over strings, bytes, and integers: parsing, formatting, sorting, encodings. |
| Capability packages | lib/ |
A thin Go wrapper for the Go toolchain, plus a hand-written native implementation per target, each checked against a contract. | Anything that reaches the host: crypto, HTTP, clocks, scheduling, callbacks. |
| Core runtime | targets/*/runtime |
Hand-written per target and checked against contracts in specs/runtime/core. |
Never imported. The compiler emits these operations for language features such as append, maps, and println. |
Why two importable roots:
- A
std/package behaves identically on every target and needs no native dependencies, because each target runs the same translated source. Go unit tests compare each package with the real standard library, and the language suite compares every target with native Go. - A
lib/package talks to the host, so it needs one native implementation per target. Availability and native dependencies can differ by target, and some calls may suspend the calling task. - Writing pure logic once avoids hand-written copies that could drift apart. Host access and security-sensitive code such as crypto must use vetted native implementations instead. A
std/function that proves too slow can later become a capability without changing its import path.
Packages
Section titled “Packages”| Package | Import path | Summary |
|---|---|---|
| bytes | github.com/eugenioenko/goalchemy/std/bytes |
Package bytes manipulates byte slices. |
| connect | github.com/eugenioenko/goalchemy/std/connect |
Package connect is a Connect protocol client for unary calls with the JSON codec, the transport behind services generated by protoc-gen-goalchemy. |
| encoding/binary | github.com/eugenioenko/goalchemy/std/encoding/binary |
Package binary translates between unsigned integers and byte sequences, and encodes varints. |
| encoding/hex | github.com/eugenioenko/goalchemy/std/encoding/hex |
Package hex encodes and decodes hexadecimal strings. |
| encoding/json | github.com/eugenioenko/goalchemy/std/encoding/json |
Package json encodes and decodes JSON with the semantics of Go’s encoding/json. |
| encoding/jsonvalue | github.com/eugenioenko/goalchemy/std/encoding/jsonvalue |
Package jsonvalue parses, inspects, builds and encodes JSON documents of any shape as a tree of Values, without declaring Go types. |
| encoding/protojson | github.com/eugenioenko/goalchemy/std/encoding/protojson |
Package protojson encodes and decodes proto3 JSON for messages generated by protoc-gen-goalchemy, matching google.golang.org/protobuf/encoding/protojson. |
| errors | github.com/eugenioenko/goalchemy/std/errors |
Package errors implements functions to manipulate errors: creation, wrapping inspection with Is and As, and joining. |
| fmt | github.com/eugenioenko/goalchemy/std/fmt |
Package fmt formats values into strings and errors with Go’s verbs, flags, widths, precisions and argument indexes. |
| http | github.com/eugenioenko/goalchemy/std/http |
Package http sends HTTP requests whose bodies stream through std/io: the request body is read from an io.Reader and the response body is an io.ReadCloser, so neither is held in memory whole. |
| io | github.com/eugenioenko/goalchemy/std/io |
Package io provides basic interfaces to I/O primitives and helpers that combine them, matching Go’s io package. |
| io/hostio | github.com/eugenioenko/goalchemy/std/io/hostio |
Package hostio adapts host streams passed to library exports as std/io interfaces. |
| log/slog | github.com/eugenioenko/goalchemy/std/log/slog |
Package slog provides structured logging with Go’s log/slog API. |
| net | github.com/eugenioenko/goalchemy/std/net |
Package net provides the host and port helpers of Go’s net package: JoinHostPort, SplitHostPort and AddrError. |
| net/url | github.com/eugenioenko/goalchemy/std/net/url |
Package url parses URLs and implements query escaping, following Go’s net/url: the same parsing rules, escaping and error messages. |
| os | github.com/eugenioenko/goalchemy/std/os |
Package os reads and writes whole files on the host file system. |
| sort | github.com/eugenioenko/goalchemy/std/sort |
Package sort sorts collections through the Len, Less, and Swap methods. |
| strconv | github.com/eugenioenko/goalchemy/std/strconv |
Package strconv converts between integers, Booleans, and their string forms, and formats floating-point numbers. |
| strings | github.com/eugenioenko/goalchemy/std/strings |
Package strings manipulates UTF-8 encoded strings. |
| time | github.com/eugenioenko/goalchemy/std/time |
Package time measures and displays time. |
| unicode | github.com/eugenioenko/goalchemy/std/unicode |
Package unicode classifies runes and maps their case using the Unicode tables of the reference Go toolchain. |
| unicode/utf8 | github.com/eugenioenko/goalchemy/std/unicode/utf8 |
Package utf8 encodes and decodes UTF-8 text. |
| lib/callback | github.com/eugenioenko/goalchemy/lib/callback |
Package callback declares a bounded asynchronous host callback capability. |
| lib/checksum | github.com/eugenioenko/goalchemy/lib/checksum |
Package checksum provides non-cryptographic checksums backed by host APIs where available. |
| lib/clock | github.com/eugenioenko/goalchemy/lib/clock |
Package clock provides wall time, independent of Goalchemy virtual time. |
| lib/context | github.com/eugenioenko/goalchemy/lib/context |
Package context provides Goalchemy’s cancellation contexts; deadlines use the virtual clock. |
| lib/crypto | github.com/eugenioenko/goalchemy/lib/crypto |
Package crypto provides bounded native cryptographic capabilities. |
| lib/encoding | github.com/eugenioenko/goalchemy/lib/encoding |
Package encoding provides canonical RFC 4648 base64 encodings. |
| lib/errors | github.com/eugenioenko/goalchemy/lib/errors |
Package errors provides Goalchemy’s error values. |
| lib/http | github.com/eugenioenko/goalchemy/lib/http |
Package http provides bounded HTTP exchanges, retaining TLS verification and returning redirect responses without following them. |
| lib/log | github.com/eugenioenko/goalchemy/lib/log |
Package log routes structured log records from Goalchemy programs to a sink the host application installs. |
| lib/os | github.com/eugenioenko/goalchemy/lib/os |
Package os reads and writes whole host files. |
| lib/runtime | github.com/eugenioenko/goalchemy/lib/runtime |
Package runtime provides Goalchemy’s scheduler controls. |
| lib/sync | github.com/eugenioenko/goalchemy/lib/sync |
Package sync provides Goalchemy’s synchronization primitives. |
| lib/task | github.com/eugenioenko/goalchemy/lib/task |
Package task provides structured waiting for Goalchemy programs. |
| lib/time | github.com/eugenioenko/goalchemy/lib/time |
Package time provides Goalchemy’s virtual clock: Sleep advances it deterministically. |
Capability packages
Section titled “Capability packages”Every entry lists:
- Gate:
sequentialmeans the function never suspends, so it suits sequential programs and synchronous exports.cooperativemeans the contract lets the call suspend the calling task (a scheduler pause point); write such code for the cooperative execution model, where other tasks run while it waits. - Bounds and Errors: the limits checked before work starts and what is returned when they or the operation fail.
- Contract: the contract ID and version under
specs/runtime.
Native dependencies
Section titled “Native dependencies”| Target | Status | Minimum | Native dependencies |
|---|---|---|---|
| c | experimental | A C17 compiler on a 64-bit platform; bdwgc 8.x built with POSIX threads | OpenSSL 3 (libcrypto) for crypto, libcurl and zlib for HTTP (gzip responses are decoded with zlib), and the Boehm-Demers-Weiser collector (bdwgc 8.x) built with POSIX threads. IEEE CRC32 uses a slicing-by-8 fallback because standard C provides no CRC API. |
| csharp | experimental | .NET 8 SDK (C# 12) | .NET 8 built-ins for crypto (System.Security.Cryptography) and HTTP (HttpClient); IEEE CRC32 uses the official Microsoft System.IO.Hashing 8.0.0 NuGet package with a content-hash lock, not the shared runtime. Host runtime controls acceleration. |
| go | experimental | go1.25 | Go standard library only: crypto/* for crypto, net/http for HTTP, and hash/crc32.ChecksumIEEE for IEEE CRC32; host runtime controls acceleration. |
| java | experimental | Java 21 | JDK 21 JCA providers plus the pinned Bouncy Castle 1.86 jar (bcprov-jdk18on, locked in targets/java/dependencies.lock.json) for HKDF and EC private key imports, which derive the public point; HTTP uses java.net.http; IEEE CRC32 uses standard java.util.zip.CRC32 and host-controlled acceleration. |
| python | experimental | Python 3.10 (the release baseline for now; it can be raised later) | The maintained cryptography package for crypto; HTTP uses the standard library (http.client); IEEE CRC32 uses standard zlib.crc32 and host-controlled acceleration. |
| rust | experimental | Rust 1.75 std-only; native package dependencies require Rust 1.88 | Pinned crates through Cargo: openssl (vendored) for crypto, reqwest with rustls and Tokio for HTTP (gzip responses decoded with pinned flate2 1.1.10), and base64. IEEE CRC32 uses pinned crc32fast 1.5.2 with its default std feature for runtime-selected CPU acceleration. |
| swift | experimental | Swift 6.4.0 on Linux x86_64 | OpenSSL 3 libcrypto, zlib CRC32, and libcurl HTTP via a C module. All current output packages include these native prerequisites. |
| typescript | experimental | Node.js 22.6 (ES2022) | No npm runtime dependencies: WebCrypto (crypto.subtle) for crypto and fetch for HTTP in Node.js or browsers; IEEE CRC32 uses node:zlib.crc32 in Node executable/package entries and a slicing-by-8 fallback in browsers and the portable main entry. Host runtime controls acceleration. |