docs: openkal design — a two-sided kernel ABI specification

Written from the discussion that followed the #455-#459 review, and grounded in
what is measurable today rather than sketched: every claim marked with a source
was verified against the shipped payloads (llvm 22.1.8, gcc 16.1.0, picolibc
1.8.12) while writing.

The load-bearing decisions:

  * Partitioning by RESOURCE KIND, not by which standard-library facility it
    lights up. The latter couples a kernel ABI to C++ and to today's library,
    and inverts the dependency — it is the same mistake POSIX made for C and
    WASIp1 made for POSIX, one generation further on. 'Lights up std::X' is
    demoted to the upward admission criterion, which is where it belongs.

  * An opaque one-word handle, because that is what makes openkal indifferent
    to sitting above or below libc. An int fd forces it below (Windows needs a
    table); a FILE* forces it above. Measured: four backends store their native
    thing with zero bridging.

  * fs and net dissolve. Naming goes to openkal.namespace, and what it hands
    back is the same stream resource a file, a socket or a UART gives you.
    Cleaner than 'everything is a file', because naming failure and I/O failure
    end up in different interfaces.

  * core is abort + stream + memory. Memory is core because a bump allocator
    over a static arena is an IMPLEMENTATION, not an emulation — the test being
    whether a fake would make callers silently wrong, which is true of a clock
    that does not advance but not of an allocator that can fail.

Also records the caps-can-lie problem with four defences ordered by strength,
led by making unsupported operations unrepresentable in the type system rather
than false in a bool — the same conclusion K1/K2 reached for the MMU.

Author: speak-agent