The Karkain Runtime =================== Karkain programs ship with an embedded C runtime that provides the value model, memory management, I/O, concurrency, profiling, and error reporting. All runtime C is embedded into the generated translation unit via the codegen preamble — no external ``.c`` files are needed for standard builds. Runtime layers -------------- Phase 101: freestanding layer (``runtime/freestanding/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A libc-free/libm-free foundation that establishes the Karkain-owned platform boundary: - **Arena allocator** — ``karkain_memory.c`` implements a linked-segment arena; ``karkain_arena_reset`` tears it down, ``karkain_mem_reset`` clears heap bookkeeping after teardown. - **Raw OS abstraction** — ``karkain_platform.c`` / ``karkain_platform.h`` define the only OS boundary the runtime may touch: - **Windows**: ``kernel32`` boundary (``VirtualAlloc``, ``WriteFile``, ``ExitProcess``). - **Linux/POSIX**: raw ``syscall`` instruction via inline assembly. No libc. Surface: ``karkain_pages_alloc``/``free``, ``karkain_write_out``, ``karkain_open_read``/``read``/``write``/ ``close``, ``karkain_exit``. - **I/O, string, and math primitives** that compile and link without libc. The gate ``pkg/runtime/phase101_freestanding_test.go`` compiles and runs a hello program with ``-ffreestanding -nostdlib``. Phase 102: core layer (``runtime/core/``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The libc-free runtime core stacked directly on the freestanding layer: - **Heap** — ``karkain_mem.c`` implements a real heap with ``alloc``/``calloc``/``realloc``/``free`` on an address-sorted coalescing free list. - **Tagged Value** — ``karkain_value.c`` / ``karkain_value.h`` define the ``Value`` type (``TYPE_INT``, ``TYPE_FLOAT64``, ``TYPE_STRING``, ``TYPE_ARRAY``, ``TYPE_BOOL``) with codegen-parity naming and layout: ``make_int``, ``make_float``, ``make_bool``, ``make_nil``, ``make_string``, ``make_string_n``, ``make_array``, ``values_equal`` (deep equality), ``value_truthy``, ``value_class``, ``value_type_name``, ``value_type_tag``, ``value_as_int``, ``value_as_float``. - **NativeString** — length-prefixed strings (concat/slice/compare/startswith/Value round-trip). - **NativeArray** — ``Value** items`` element storage with push/pop/get/set/clear. - **Value-level I/O** on the freestanding write primitives. The gate ``pkg/runtime/phase102_core_test.go`` compiles core+freestanding with ``-ffreestanding -nostdlib`` and asserts exact output. Embedded runtime in generated C ------------------------------- The Go codegen emits a runtime preamble (a large C string literal) at the top of every generated C23 translation unit. It is emitted from ``pkg/codegen/codegen.go`` and includes: - The ``Value`` type and `make_*` constructors (``make_int``, ``make_float``, ``make_string``, ``make_bool``, ``make_array``, ``make_nil``). - ``values_equal`` and ``value_truthy`` for semantics parity. - ``karkain_runtime_error(kind, file, line)`` — the Phase 100 runtime failure model: reports ``runtime error: at :`` on stderr and terminates with exit code 1. Checked helpers (``karkain_checked_div``/``karkain_checked_mod``/``get``/``set``) enforce division/modulo by zero and array/string index bounds. - ``karkain_frame_enter``/``karkain_frame_leave``/``karkain_set_line`` — the Phase 101 stack-trace machinery. Every generated function pushes a named frame (function name + file); a runtime error then dumps the Karkain call chain (``KARKAIN_MAX_FRAMES`` 128) with source file and line per frame. - Phase 109 encoding/crypto builtins: ``hex_encode_bytes``, ``hex_decode_bytes``, ``base64_encode_bytes``, ``base64_decode_bytes``, ``utf8_valid_bytes``, ``sha256_hex``, ``sha512_hex``, ``map_keys_of``. - Phase 106 SIMD helpers (``karkain_simd_*``) using GNU vector operators; Phase 70 SSE fallback for scalar operands. - Phase 107 concurrency runtime (see below). - Phase 110 profiling instrumentation (see below). Deterministic namespace ~~~~~~~~~~~~~~~~~~~~~~~ Every helper uses the ``karkain_*`` prefix and user functions live in the ``karkain_user_*`` namespace, so generated code never collides with C standard library symbols. Concurrency runtime ------------------- Phase 107 implements a work-stealing task scheduler with channels and actors, embedded as C in ``runtime/concurrency/c/``: - ``karkain_conc.h`` — runtime contract and types. - ``karkain_sched_impl.h`` / ``karkain_scheduler.c`` — worker threads with a bounded grab queue, per-worker wake condvar, shared pending drain, and no busy-spin stop; ``karkain_task_t`` heap cells with a function pointer and heap-owned context. - ``karkain_channel.c`` — bounded/unbounded blocking channels with deterministic close-drain. - ``karkain_actor.c`` — actors as serialized dispatcher jobs over a mailbox with a state-cell box. - ``concurrency_main.c`` — standalone scenario driver used by the ``pkg/runtime`` gate. These sources are embedded byte-for-byte via ``runtime/concurrency/embed.go`` (``//go:embed c/...``) and appended to the generated C when ``usesConcurrency`` is detected by the codegen pre-scan. Atomic helpers (``karkain_conc_atomic_*``) use GNU atomics in the runtime only. Language surface: ``spawn``/``join``/``wait_all``, ``channel``/ ``chanSend``/``chanClose``/``receive``, ``actor``/``actorSend``/ ``actorState``/``setActorState``/``actorStop``. Profiling hooks --------------- Phase 110 (``karkain prof ``) adds opt-in, aggregation-based instrumentation. When ``Config.Profiling`` is set the codegen: - Emits a source-order function-id table (``profNameTableC``) and the bounded profiling C runtime (``profRuntimeC``) right after the concurrency runtime glue. - Injects enter/leave probes into every function body (after ``frame_enter``/``set_line``; on ``OpRet``/fallthrough before ``frame_leave``). - Emits an ``atexit`` flush that writes a deterministic dump (call counts, inclusive/exclusive/min/max/avg ns, call graph, folded stacks, allocation metrics) to ``$KARKAIN_PROF_OUT``. Default builds carry no hook sites (opt-in only). Trace hooks ----------- Phase 112 trace instrumentation is gated by the ``KARKAIN_TRACE`` preprocessor define. When ``karkain debug`` (``Config.Trace``) is used, the generator emits ``#define KARKAIN_TRACE 1`` at the top of the C output, activating the ``#ifdef KARKAIN_TRACE`` blocks inside ``karkain_frame_enter``/``karkain_frame_leave``. Those blocks print ``karkain::enter `` / ``karkain::leave `` lines to stderr, producing a deterministic execution trace. Default builds never define ``KARKAIN_TRACE``. WASM runtime ------------ ``pkg/wasm/runtime.go`` implements the Karkain value model inside WASM linear memory: - **Values** are ``i64``: bit 0 == 0 means an unboxed integer (``v >> 1``, matching ``make_int`` semantics); bit 0 == 1 means a boxed heap cell pointer. - **Heap cells** (8-byte aligned): i32 type tag (same order as the C runtime: ``TYPE_INT=0`` … ``TYPE_BOOL=5``), i32 length, then data (string bytes or array element slots). - **WASI boundary** (Phase 123): four imports are fixed at the head of the function index space — ``fd_write`` (0), ``args_sizes_get`` (1), ``args_get`` (2) and ``proc_exit`` (3). Output uses a fixed scratch region (``iovs`` at offset 8, decimal digits at 16); runtime-error paths write to fd 2 and terminate with ``proc_exit(1)``. - **Runtime functions**: the module-defined helpers start at index 4 (``rt_Alloc``) up to ``UserBase=30``; ``rt_GetArgs`` (28) and the ``_start`` bootstrap (29) are part of this range. 25 runtime bodies implement ``rt_Write``, ``rt_PrintValue``, ``rt_Box``, ``rt_SetTag``, ``rt_MkArray``, ``rt_MkString``, ``rt_Eq``, ``rt_Ne``, ``rt_Error``, ``rt_GetArgs``, arithmetic helpers and more. - **``_start``**: zero the argc/argv-length scratch cells, call ``args_sizes_get``, allocate the argument buffer and pointer array via ``rt_Alloc``, call ``args_get``, store the argument count and pointer array into globals 1 and 2, call ``main``, derive the process exit code from the returned ``Value`` (``int(v>>1)`` when unboxed, else 0) and terminate with ``proc_exit``. - **Heap** begins at ``0x10000`` (heap base tracked in global 0). The emitters ``module.go``/``emit.go`` produce a dependency-free WASM binary v1 module that ``wasmtime run --dir . `` executes with stdio passthrough and argument forwarding. Host platform boundary ---------------------- The freestanding platform layer is the authority on host-specific behavior. QPC (QueryPerformanceCounter) timing on Windows reuses the preamble's already-included ``windows.h`` prototypes; other platforms use ``clock_gettime(CLOCK_MONOTONIC)``. GCC can also be configured to inject reproducible link values (``SOURCE_DATE_EPOCH``) so bootstrap binaries are bit-identical. Consumption paths ~~~~~~~~~~~~~~~~~ - **Generated C** — the preamble inlines the runtime that the program actually needs. - **Standalone gates** — ``pkg/runtime`` tests compile the same ``runtime/`` sources from disk with ``-ffreestanding -nostdlib``, proving the two consumption paths share one source of truth. - **kcc** — the self-hosted compiler emits its own equivalent helpers into its C output (mirroring the Go preamble), keeping both engines behaviorally identical (e.g. identical ``runtime error`` messages and stack frames).