Implement the five interfaces openkal 0.8 adds (#15)

* implement the five interfaces openkal 0.8 adds

openkal.terminal upon the kernel's terminal ioctls, openkal.net and
openkal.datagram upon its socket calls, openkal.space upon clone, and
openkal.timeout upon ppoll and a bounded wait for a child.

Each is written on the kernel's own calling convention and names no facility a
program above might also define, which is the property this implementation has
had since version 0.5 and which CI asserts by examining undefined symbols.

## What the implementation established about the interface

openkal.space is one operation because the kernel's primitive is one act. clone
copies the address space and begins execution in the copy; there is no form that
does the first without the second. The specification was changed rather than this
file, because an implementation asked to separate them would have to park a
started context and build a channel to tell it what to run.

openkal.net yields an owned connection and a borrowed stream, for the same
reason kal_file and kal_fs_stream are separate: the owned handle carries a
generation so that a released one stops being valid, and a stream handle is the
bare descriptor because that is what the transfer operations take.

## Details worth stating

The terminal mode is read, modified and written rather than written alone. The
kernel's structure carries input flags, output flags, a baud rate and the control
characters, none of which this interface names; composing one from the mode word
would discard all of them silently.

kal_terminal_props asks TIOCGWINSZ rather than deriving the answer from TCGETS. A
pseudo terminal answers both and a serial line answers only the first, so a word
derived from one would claim a facility the next call refuses.

The endpoint conversion is shared between net and datagram because the type is,
and either interface may be provided without the other.

An interrupted bounded wait is reported as an expiry rather than retried with the
whole bound again, which would make the bound restart at every signal and leave a
program waiting without end while appearing to be bounded.

kal_timeout_wait_process polls with WNOHANG because the kernel has no bounded
wait for a child. The alternative is a SIGCHLD handler, which is process-wide
state an implementation would be taking away from the program above it.

  tests/conformance_v08.cpp  the C++ half of clause 4.3 for the new interfaces
  mcpp test                  7 passed, 0 failed
  conformance suite          100 observations held, 0 did not hold
                             terminal's interactive path observed under a pty

* Provide the three operations openkal 0.8 adds to openkal.process

ADDING TO AN EXISTING INTERFACE OBLIGES EVERY IMPLEMENTATION OF IT, and adding a
new interface obliges none. Clause 6.1 makes an interface an implementation does
not provide absent at the link and not a deviation; it makes one provided IN PART
a deviation. The five interfaces version 0.8 adds are therefore free for a
backend to decline, and the three names added to openkal.process are not.

The specification's own surface checker is what said so, before anything else
noticed:

    openkal.process is provided in part: 3 of 8 names are not exported --
        kal_process_channel
        kal_process_channel_close
        kal_process_spawn_with

kal_process_channel is pipe2 with O_CLOEXEC on both ends. The far end is placed
deliberately by the spawn that receives it; an end that leaked into every other
started program would keep the channel open after the intended reader had closed
it, and the writer would never see the end of input.

The streams are bare descriptors rather than packed handles, because
openkal.stream's transfer operations take what the environment takes.
kal_fs_stream reports a file's stream the same way and for the same reason.

kal_process_channel_close refuses descriptors below three. They are the standard
streams, which are borrowed; closing one through this operation would take a
stream away from the whole program.

kal_process_spawn_with places the grants as descriptors three and upward, which
is where kal_fs_preopen reads them back from. The inverse relationship clause
7.11 describes is between those two operations, which is why they must agree
about the numbering rather than each choosing one.

⚠️ dup3 refuses a duplication onto itself, and the ordinary case reaches that
whenever a granted directory already occupies the number it is destined for.
Refusing is correct of dup3 --- the flags could not be applied --- and here it
means the descriptor is already in place, so it is left alone rather than treated
as a failure.

The grants are resolved before the fork. A failure after it would leave a child
to be reaped and a caller holding an error it cannot act upon.

  surface      exported surface is complete and conforms: 90 names
  mcpp test    7 passed, 0 failed
  observed     a channel carries bytes, and closing the far end is observed as
               end of input on the near one

* ci: assert the committed manifest names no local directory

Two scripts in the specification's repository rewrite this manifest to name a
working tree --- run-conformance.sh and run-kit-tests.sh --- and both restore it
through a trap. A trap does not fire when the process is killed, and a run by
hand followed by `git add -A` then publishes a path that exists on one machine:
a consumer resolving from the index is handed a manifest pointing at a directory
that exists nowhere.

⚠️ That has happened in this ecosystem, in openkal-musl, where it was published
and had to be reverted. The working tree here has carried the same rewrite more
than once since, and only an audit before committing kept it out.

The step runs first, so what it examines is what the commit contains rather than
what the job has since done to it. openkal-musl carries the same check for the
same reason.

* Name the released specification and the released engine

openkal 0.8.0 is published, so the manifest names it by version rather than by
branch. A branch is how a change spanning these repositories is developed and is
not a form a published package may carry: a consumer resolving from the index
would be handed a reference that moves.

The engine pin moves to mcpp 2026.8.27.1 and the repository variable
MCPP_SOURCE_REF is cleared, so what this repository tests is the engine a user
installs.

---------

Co-authored-by: speak-agent <x.d2learn.org@gmail.com>

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ on:
         default: ""
 env:
   MCPP_SOURCE_REF: ${{ github.event.inputs.mcpp_ref || vars.MCPP_SOURCE_REF }}
-  MCPP_VERSION: 2026.8.26.2
+  MCPP_VERSION: 2026.8.27.1
   XLINGS_VERSION: v2026.8.17.2
   XLINGS_NON_INTERACTIVE: '1'
 
@@ -49,6 +49,31 @@ jobs:
       # The specification is checked out at the branch under test where it has
       # one, so that this run asserts what it is for: that the specification as
       # written there and this implementation as written here agree today.
+      # THE COMMITTED MANIFEST NAMES NO DIRECTORY OF ANYBODY'S MACHINE.
+      #
+      # Two scripts in the specification's repository rewrite this manifest to
+      # name a working tree --- run-conformance.sh and run-kit-tests.sh --- and
+      # both restore it through a trap. A trap does not fire when the process is
+      # killed, and a run by hand followed by `git add -A` then publishes a path
+      # that exists on one machine: a consumer resolving from the index is handed
+      # a manifest pointing at a directory that exists nowhere.
+      #
+      # ⚠️ THAT HAS HAPPENED IN THIS ECOSYSTEM, in openkal-musl, and the working
+      # tree here has carried the same rewrite more than once since. This step
+      # runs first, so what it examines is what the commit contains.
+      - name: The committed manifest names no local directory
+        run: |
+          set -euo pipefail
+          bad=$(grep -nE '^[a-z-]+ = \{[^}]*path = "(/|[A-Za-z]:)' mcpp.toml || true)
+          if [ -n "$bad" ]; then
+            echo "::error::the committed manifest names an absolute path"
+            printf '%s\n' "$bad" | sed 's/^/        /'
+            echo "        run 'git checkout -- mcpp.toml' after using the"
+            echo "        specification's conformance or kit scripts by hand."
+            exit 1
+          fi
+          echo "  ok  every dependency is named by version, branch or a relative path"
+
       - name: The specification
         run: |
           git clone --quiet https://github.com/mcpplibs/openkal.git .spec

.gitignore

@@ -17,3 +17,6 @@ compile_commands.json
 # What a system leaves behind.
 .DS_Store
 Thumbs.db
+
+# The specification tree tools/run-conformance.sh clones beside the sources.
+.spec/

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-linux"
-version     = "0.5.4"
+version     = "0.6.0"
 description = "The reference implementation of openkal for Linux, written on the kernel's own system-call interface so that it can be placed beneath a C library as well as above one."
 license     = "Apache-2.0"
 
@@ -18,7 +18,7 @@ authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-linux"
 
 [dependencies]
-openkal = "0.7.0"
+openkal = "0.8.0"
 
 # The package contributes definitions and no modules. The interface it
 # implements is declared by the specification package, which this package

src/datagram.cpp

@@ -0,0 +1,151 @@
+#include "sys.h"
+#include "handle.h"
+#include "endpoint.h"
+#include <openkal/datagram.h>
+
+// openkal.datagram upon the kernel's socket calls.
+//
+// A DATAGRAM IS NOT PACKED AS A kal_stream, and the handle type is its own for
+// that reason: kal_stream_read reports a count and not a boundary, so reading a
+// datagram through it would lose the property that distinguishes this interface.
+// The packing is the same, the type is not, and the type is what prevents the
+// mistake.
+
+namespace {
+
+int fd_of(kal_datagram d) { return okl::unpack(d.h); }
+
+}  // namespace
+
+extern "C" {
+
+int kal_datagram_open(const kal_endpoint* local, kal_datagram* out) {
+    if (out == nullptr) return kal_err_invalid;
+
+    // A null local endpoint asks for one that may send and whose receiving
+    // address is unspecified. IPv4 is chosen for it, because a family must be
+    // named at the point the socket is made and this is the one every
+    // environment that has a network at all provides.
+    okl_long family = okl::af_inet;
+    if (local != nullptr) {
+        family = okl::family_of(*local);
+        if (family < 0) return kal_err_invalid;
+    }
+
+    const okl_long fd = okl::sys(okl::nr_socket, family,
+                                 okl::sock_dgram | okl::sock_cloexec,
+                                 okl::ipproto_udp);
+    if (okl::failed(fd)) return okl::translate(fd);
+
+    if (local != nullptr) {
+        okl::ksockaddr_storage ss{};
+        okl_long len = 0;
+        if (const int rc = okl::to_kernel(*local, ss, len); rc != kal_ok) {
+            okl::sys(okl::nr_close, fd);
+            return rc;
+        }
+        if (const okl_long r = okl::sys(okl::nr_bind, fd,
+                                        reinterpret_cast<okl_long>(&ss), len);
+            okl::failed(r)) {
+            okl::sys(okl::nr_close, fd);
+            return okl::translate(r);
+        }
+    }
+
+    out->h = okl::pack(static_cast<int>(fd));
+    if (out->h == 0) { okl::sys(okl::nr_close, fd); return kal_err_no_memory; }
+    return kal_ok;
+}
+
+int kal_datagram_local(kal_datagram d, kal_endpoint* out) {
+    if (out == nullptr) return kal_err_invalid;
+    const int fd = fd_of(d);
+    if (fd < 0) return kal_err_invalid;
+
+    okl::ksockaddr_storage ss{};
+    okl_long len = static_cast<okl_long>(sizeof ss);
+    const okl_long r = okl::sys(okl::nr_getsockname, fd,
+                                reinterpret_cast<okl_long>(&ss),
+                                reinterpret_cast<okl_long>(&len));
+    if (okl::failed(r)) return okl::translate(r);
+    return okl::from_kernel(ss, *out);
+}
+
+kal_io_result kal_datagram_send_to(kal_datagram d, const void* buf, kal_uintptr len,
+                                   const kal_endpoint* to) {
+    const int fd = fd_of(d);
+    if (fd < 0 || to == nullptr) return { 0, kal_err_invalid };
+
+    okl::ksockaddr_storage ss{};
+    okl_long addrlen = 0;
+    if (const int rc = okl::to_kernel(*to, ss, addrlen); rc != kal_ok)
+        return { 0, rc };
+
+    for (;;) {
+        const okl_long r = okl::sys(okl::nr_sendto, fd,
+                                    reinterpret_cast<okl_long>(buf),
+                                    static_cast<okl_long>(len), 0,
+                                    reinterpret_cast<okl_long>(&ss), addrlen);
+        if (okl::interrupted(r)) continue;
+        if (okl::failed(r)) return { 0, okl::translate(r) };
+
+        // A MESSAGE IS SENT WHOLE OR NOT AT ALL, which is what this interface
+        // states. The kernel reports a count anyway; a count short of the length
+        // would mean the medium had split the message, which for a datagram
+        // socket it does not do. Reporting the short count as success would give
+        // a caller a partial send this interface says cannot occur, so it is
+        // reported as a failure of the medium instead.
+        const kal_uintptr n = static_cast<kal_uintptr>(r);
+        return { n, n == len ? kal_ok : kal_err_io };
+    }
+}
+
+kal_io_result kal_datagram_recv_from(kal_datagram d, void* buf, kal_uintptr len,
+                                     kal_endpoint* from) {
+    const int fd = fd_of(d);
+    if (fd < 0) return { 0, kal_err_invalid };
+
+    okl::ksockaddr_storage ss{};
+    okl_long addrlen = static_cast<okl_long>(sizeof ss);
+
+    for (;;) {
+        const okl_long r = okl::sys(okl::nr_recvfrom, fd,
+                                    reinterpret_cast<okl_long>(buf),
+                                    static_cast<okl_long>(len), 0,
+                                    reinterpret_cast<okl_long>(&ss),
+                                    reinterpret_cast<okl_long>(&addrlen));
+        if (okl::interrupted(r)) continue;
+        if (okl::failed(r)) return { 0, okl::translate(r) };
+
+        // THE COUNT REPORTED IS WHAT WAS PLACED IN THE BUFFER, not what was
+        // sent. Without MSG_TRUNC the kernel already reports the former, which
+        // is what this interface requires: a caller that trusted the larger
+        // number would read beyond its own buffer.
+        if (from != nullptr) {
+            // A sender whose family this implementation does not know leaves the
+            // endpoint zeroed rather than partly filled. The transfer still
+            // happened and is reported; what is unknown is who sent it.
+            if (okl::from_kernel(ss, *from) != kal_ok) {
+                for (auto& b : from->addr) b = 0;
+                from->addr_len = 0;
+                from->port     = 0;
+            }
+        }
+        return { static_cast<kal_uintptr>(r), kal_ok };
+    }
+}
+
+void kal_datagram_close(kal_datagram d) {
+    const int fd = fd_of(d);
+    if (fd < 0) return;
+    okl::sys(okl::nr_close, fd);
+    okl::retire(d.h);
+}
+
+// Broadcast is not claimed. The kernel provides it only after SO_BROADCAST has
+// been set, and this interface has no operation that would set it; a word
+// claiming a facility no operation reaches is the disagreement clause 6.2 exists
+// to prevent.
+const kal_uintptr kal_datagram_props = KAL_DGRAM_PROP_IPV6;
+
+}  // extern "C"

src/endpoint.h

@@ -0,0 +1,112 @@
+// Conversion between kal_endpoint and the kernel's socket address structures.
+//
+// SHARED BY openkal.net AND openkal.datagram BECAUSE THE TYPE IS. Either
+// interface may be provided without the other, so the conversion belongs to
+// neither; writing it twice would be one decision stated in two places, and the
+// two would eventually disagree about which lengths are accepted.
+#pragma once
+#include "sys.h"
+#include <openkal/types.h>
+
+namespace okl {
+
+// The port is carried in host order by kal_endpoint and in network order by the
+// kernel. The conversion is written out rather than taken from a C library's
+// htons, for the reason the head of sys.h gives.
+inline unsigned short to_net_port(kal_u32 port) {
+    const unsigned short p = static_cast<unsigned short>(port & 0xffffu);
+    return static_cast<unsigned short>((p << 8) | (p >> 8));
+}
+inline kal_u32 from_net_port(unsigned short net) {
+    return static_cast<kal_u32>((net << 8) | (net >> 8)) & 0xffffu;
+}
+
+// Fills a kernel address from an endpoint, and reports its length.
+//
+// A LENGTH THIS IMPLEMENTATION DOES NOT KNOW IS REFUSED RATHER THAN READ AS ONE
+// IT DOES. The specification defines the set of lengths and allows it to grow;
+// an implementation that ignored the field would misread every address a later
+// revision defines, and would do so silently.
+inline int to_kernel(const kal_endpoint& ep, ksockaddr_storage& out, okl_long& len) {
+    for (auto& b : out.pad) b = 0;
+
+    if (ep.addr_len == 4) {
+        auto* v4 = reinterpret_cast<ksockaddr_in*>(&out);
+        v4->family = af_inet;
+        v4->port   = to_net_port(ep.port);
+        okl_u32 a = 0;
+        for (int i = 0; i < 4; ++i)
+            a |= static_cast<okl_u32>(ep.addr[i]) << (i * 8);   // already network order
+        v4->addr = a;
+        for (auto& z : v4->zero) z = 0;
+        len = static_cast<okl_long>(sizeof(ksockaddr_in));
+        return kal_ok;
+    }
+
+    // Sixteen bytes is an address; twenty is an address followed by a scope
+    // identifier, which is carried in the four bytes after it.
+    if (ep.addr_len == 16 || ep.addr_len == 20) {
+        auto* v6 = reinterpret_cast<ksockaddr_in6*>(&out);
+        v6->family   = af_inet6;
+        v6->port     = to_net_port(ep.port);
+        v6->flowinfo = 0;
+        for (int i = 0; i < 16; ++i) v6->addr[i] = ep.addr[i];
+        okl_u32 scope = 0;
+        if (ep.addr_len == 20)
+            for (int i = 0; i < 4; ++i)
+                scope |= static_cast<okl_u32>(ep.addr[16 + i]) << (i * 8);
+        v6->scope_id = scope;
+        len = static_cast<okl_long>(sizeof(ksockaddr_in6));
+        return kal_ok;
+    }
+
+    return kal_err_invalid;
+}
+
+// Fills an endpoint from a kernel address. A family this implementation does
+// not know leaves the endpoint zeroed and reports it, for the same reason.
+inline int from_kernel(const ksockaddr_storage& in, kal_endpoint& out) {
+    for (auto& b : out.addr) b = 0;
+    out.addr_len = 0;
+    out.port     = 0;
+
+    if (in.family == af_inet) {
+        const auto* v4 = reinterpret_cast<const ksockaddr_in*>(&in);
+        const okl_u32 a = v4->addr;
+        for (int i = 0; i < 4; ++i)
+            out.addr[i] = static_cast<kal_u8>((a >> (i * 8)) & 0xffu);
+        out.addr_len = 4;
+        out.port     = from_net_port(v4->port);
+        return kal_ok;
+    }
+
+    if (in.family == af_inet6) {
+        const auto* v6 = reinterpret_cast<const ksockaddr_in6*>(&in);
+        for (int i = 0; i < 16; ++i) out.addr[i] = v6->addr[i];
+        // A zero scope identifier is reported as the shorter form. The two
+        // lengths denote the same address when the scope is zero, and reporting
+        // the shorter one keeps an address that came in as sixteen bytes going
+        // back out as sixteen.
+        if (v6->scope_id == 0) {
+            out.addr_len = 16;
+        } else {
+            for (int i = 0; i < 4; ++i)
+                out.addr[16 + i] = static_cast<kal_u8>((v6->scope_id >> (i * 8)) & 0xffu);
+            out.addr_len = 20;
+        }
+        out.port = from_net_port(v6->port);
+        return kal_ok;
+    }
+
+    return kal_err_invalid;
+}
+
+// Which socket family an endpoint asks for, or -1 for a length that is not one
+// of the defined ones.
+inline okl_long family_of(const kal_endpoint& ep) {
+    if (ep.addr_len == 4) return af_inet;
+    if (ep.addr_len == 16 || ep.addr_len == 20) return af_inet6;
+    return -1;
+}
+
+}  // namespace okl