Stable API Snapshot (1.2.0)
This is the authoritative 1.2.0 (Stable) API snapshot — the reference point for the release-readiness evaluation. A feature belongs to the snapshot only when a gate test exercises it through the real pipeline on both engines. Anything not listed here is not part of the stable surface.
Scope of the snapshot
The snapshot records five stable dimensions:
Stable syntax — the language surface.
Stable CLI — commands, options, exit codes.
Stable stdlib modules — importable
std.*modules and their backing builtins.Stable diagnostic expectations — error-code contract and runtime error model.
Stable target model — the closed set of
--targetvalues and the host matrix.
Stable syntax
Surface |
Items |
|---|---|
Declarations |
|
Control flow |
|
Values |
Integers, floats, booleans, strings, |
Runtime error model |
Checked division/modulo by zero and array/string indexing report
|
Entry point |
The top-level file scope is the entry point; a top-level
|
Full language guidance: Karkain Language Guide.
Stable CLI
Command |
Contract |
|---|---|
|
Validate syntax + semantics; exit 3 on failure. |
|
Compile to a native executable ( |
|
Compile and run in one step. |
|
Discover |
|
Formatter (idempotent, |
|
Profile a program (text/json/folded; Go engine). |
|
Multi-member workspace management using dependency order
( |
|
|
|
LSP over stdio; machine-readable IDE contract. |
Exit-code contract: 0 success, 1 program failure, 2 CLI usage error, 3 compile/type/semantic, 4 test failure, 5 package/dependency, 6 infrastructure (e.g. no usable C compiler), 7 lint findings.
Full CLI reference: Command-Line Interface.
Stable stdlib modules
Module |
Surface |
|---|---|
|
String operations on UTF-8 strings (27 functions). |
|
Collection helpers (list/map utilities, 24 functions). |
|
Input/output helpers (file read/write, line reading, 11 functions). |
|
Hex and Base64 encode/decode (RFC 4648 verified, 7 functions). |
|
|
|
|
|
Numerical/ML foundation (vector/matrix/tensor ops, 40 functions). |
|
TCP networking (Address/Endpoint/Connection/Listener, 10 functions). |
|
HTTP/1.1 client/server building blocks (Request/Response, 20 functions). |
|
Backend-neutral database layer (SQL subset, persistence, 20 functions). |
|
Persistent |
Full stdlib reference: Standard Library.
Stable diagnostic expectations
error[K...]numeric codes on the front end;karkain explain <code>documents each code (K001–K008, K100, K101–K116, K145, including K114 escape rejection, K115 generic-arity/misuse, and K116 engine-capability refusal).K116is a capability refusal, not a program defect: the self-hosted engine (kcc) has no machine-code backend, so a C-free native target (native-x86_64-linux/-windows/-macos) requested under kcc is refused loudly instead of being silently built by the Go engine. The three native targets are Go-owned; kcc owns C23. See Roadmap (increment 151A) anddocs/audit/PHASE-151-BASELINE.md.karkain check --format=jsonemits thekarkain-diagnostics-v1JSON contract.Runtime failure model:
runtime error: <kind> at <file>:<line>with astack:trace, byte-identical on both engines.Exit codes above always map to the documented contract, never ad-hoc values.
Full diagnostics reference: Diagnostics.
Stable target model
Item |
Contract |
|---|---|
Legacy aliases |
|
Conventional triples |
|
Host reporting |
|
Cross-compilation |
|
Full target reference: Targets.
Snapshot maintenance
The snapshot moves only with the Compatibility Policy policy: stable-core changes are documented, justified and migration-noted.
After a release-candidate is declared, the snapshot is re-verified and published as the RC reference point.
Every claim here is backed by the gate in
pkg/cli/phase118_rc_test.goand the regression baselines in Release-Candidate Checklist.
See also
Release-Candidate Scope — how each item in the snapshot is classified. Compatibility Policy — the guarantees attached to the snapshot. Beta 1 — the Beta 1 capability assessment. Release-Candidate Checklist — the readiness checklist that consumes this snapshot.