0.6.0 — adopt openkal 0.9, and ask this machine what its page is (#14)

* 0.6.0 --- adopt openkal 0.9, and ask this machine what its page is

⚠️⚠️ THE ALLOCATOR ASSUMED A FOUR-KILOBYTE PAGE ON A SYSTEM WITH TWO.

`kPage' was the constant 4096, and this system's own hardware pages are four
kilobytes on one architecture and SIXTEEN on the other. Allocation appeared to
work, because a mapping rounded to four kilobytes is rounded up again by the
kernel --- while `kal_free' unmapped a range SHORTER than the one mapped, and
the remainder was never returned. The page is now asked for once, through
`hw.pagesize', and `kal_memory_granularity' reports it.

The rest follows the specification:

  * `kal_fs_props' takes the directory and consults the format the volume is,
    which this kernel names in words. A word per implementation could state
    none of its positions honestly here: the volume this system is ordinarily
    installed on compares names without regard to case and a volume attached to
    the same machine may not, and both are reachable through the preopen this
    implementation supplies;
  * asking now resolves a link, because opening always did;
  * transfers return one signed word; the parameters and names are copied into
    the caller's buffer and the length reported is the value's own;
  * `kal_node_info' carries its own size, reports what was filled, and carries
    the device and inode as an opaque identity;
  * `kal_fs_link_create' and `kal_fs_link_read' over symlinkat and readlinkat;
  * `kal_fs_max_name'; typed stream handles; `kal_version' and
    `kal_interfaces'.

Ninety-five names are exported and none other, checked against SURFACE.txt.

* README: the versions it names are the versions that exist

Every README here opens by showing what a program writes in its manifest, which
is the first thing a reader copies and the last thing anyone edits. These lines
had drifted --- the specification's own README asked for a version four minor
releases old --- and nothing checked them.

`openkal/tools/check-readme-versions.sh` now does.

* fix: measure whether this system grants executable memory

src/exec.cpp carried both answers. One comment reasoned that the
write-then-publish order is the case an entitlement is not needed for and
concluded the interface is provided unconditionally; another, thirty lines
below, reasoned that executable memory is granted only to an artifact produced
with one and returned zero from kal_exec_props. The operations behaved as the
first said and the capability word said the second.

The disagreement was invisible while every consumer was statically linked --
such a consumer never asks, it links the operations and uses them. It became
load-bearing when an implementation's own account of itself became part of the
ABI, and the conformance suite then reported what had been true all along:
"an implementation that does not claim availability reserves nothing" did not
hold, because this one claimed nothing and reserved anyway.

Neither comment is the party that knows. Whether this system grants executable
memory depends on how the artifact was signed, which is settled after this code
is compiled. So the enquiry performs the thing it is asked about -- one
reservation, one publish, one release -- and reports what the kernel said;
kal_exec_alloc declines when it reports no. The two can no longer disagree.

kPage = 4096 is also gone. The argument for it held for the reservation and
failed for the release: munmap with a length shorter than the mapping unmaps
less than was mapped, which is the defect src/memory.cpp records having
measured on this same system one file away.

* ci: substitute the specification per step, not per job

Measured 2026-08-28 across the eight repositories of this ecosystem while one
change spanned all of them: eight jobs in four of them called `mcpp build' at a
point where the manifest still named openkal BY VERSION, so a version under
review -- which by definition is not published -- failed them with E_NOT_FOUND.

The mechanism is not a missing substitution. run-conformance.sh substitutes the
manifest and RESTORES IT ON EXIT, correctly; every step after it is back to
naming a version. So an audit asking "does this job substitute?" passes the job
and misses the steps, which is how the first pass at this found three
repositories and not four.

These steps are green on main and can only be green there, because there the
published version is the one under test. It is not a check that fails, it is a
check that cannot run at the only time it would have something to say.

The substitution is also portable now: the opensbi and uefi portability jobs run
on macOS and Windows, where BSD sed requires an argument to -i that GNU sed
refuses.

---------

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

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -182,6 +182,39 @@ jobs:
         run: |
           bash .spec/tools/run-conformance.sh openkal-macos . full,optional
 
+      # ⚠️⚠️ CLONING THE SPECIFICATION IS NOT THE SAME AS BUILDING AGAINST IT.
+      #
+      # `.spec` is cloned at the top of this job and consumed by the script
+      # above, which substitutes this manifest itself and RESTORES IT ON EXIT
+      # --- correctly, since a script that rewrote a checked-in file and walked
+      # away would leave the tree holding a path. But every step BELOW calls
+      # `mcpp build` directly, and by then the manifest names `openkal` by
+      # version again, so they resolved the PUBLISHED specification:
+      #
+      #     E_NOT_FOUND: package 'compat.openkal@0.9.0' not found in the synced
+      #     index ... the index is current, so this name is either wrong or not
+      #     published yet
+      #
+      # ⭐⭐ THE UNIT IS THE STEP, NOT THE JOB, AND NOT THE REPOSITORY. Measured
+      # 2026-08-28 across the eight repositories of this ecosystem: eight jobs
+      # in four of them had this shape. An audit that asked "does this job
+      # substitute?" passed this one, because it does --- and then gives it
+      # back. These steps are green on `main` and can only be green there,
+      # because there the published version IS the one under test.
+      - name: Point at the specification's working tree
+        run: |
+          set -euo pipefail
+          # ⚠️ NOT `sed -i'. This step runs on macOS and on Windows too, and
+          # BSD sed requires an argument to -i that GNU sed refuses. A temporary
+          # file is the spelling that holds on all three.
+          subst() {   # subst <file> <relative-path-to-the-specification>
+            sed "s|^openkal = .*$|openkal = { path = \"$2\" }|" "$1" > "$1.next"
+            mv "$1.next" "$1"
+            grep -q "path = \"$2\"" "$1" \
+              || { echo "::error::$1 was not substituted"; exit 1; }
+          }
+          subst mcpp.toml .spec
+
       # The other architecture, as far as this system allows it to be reached.
       #
       # The system-call numbers agree between the two --- measured, in the

README.md

@@ -5,10 +5,10 @@ written on the kernel's own calls.
 
 ```toml
 [dependencies]
-openkal = "0.8.0"
+openkal = "0.9.0"
 
 [target.'cfg(os = "macos")'.dependencies]
-openkal-macos = "0.5.0"
+openkal-macos = "0.6.0"
 ```
 
 Its purpose is as much to test the specification as to be used. A specification

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-macos"
-version     = "0.5.0"
+version     = "0.6.0"
 description = "An implementation of openkal for macOS, written on the kernel's own calls. Its purpose is as much to test the specification as to be used."
 license     = "Apache-2.0"
 
@@ -18,7 +18,7 @@ authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-macos"
 
 [dependencies]
-openkal = "0.8.0"
+openkal = "0.9.0"
 
 [build]
 # The flags are attached to this package's own sources rather than to the whole

src/datagram.cpp

@@ -72,15 +72,15 @@ int kal_datagram_local(kal_datagram d, kal_endpoint* out) {
     return okm::from_kernel(ss, *out);
 }
 
-kal_io_result kal_datagram_send_to(kal_datagram d, const void* buf, kal_uintptr len,
-                                   const kal_endpoint* to) {
+kal_intptr 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 };
+    if (fd < 0 || to == nullptr) return -kal_err_invalid;
 
     okm::ksockaddr_storage ss{};
     okm_u32 addrlen = 0;
     if (const int rc = okm::to_kernel(*to, ss, addrlen); rc != kal_ok)
-        return { 0, rc };
+        return -rc;
 
     for (;;) {
         const okm_long r = okm::sys(okm::nr_sendto, fd,
@@ -89,7 +89,7 @@ kal_io_result kal_datagram_send_to(kal_datagram d, const void* buf, kal_uintptr
                                     reinterpret_cast<okm_long>(&ss),
                                     static_cast<okm_long>(addrlen));
         if (okm::interrupted(r)) continue;
-        if (okm::failed(r)) return { 0, okm::translate(r) };
+        if (okm::failed(r)) return -okm::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
@@ -98,14 +98,14 @@ kal_io_result kal_datagram_send_to(kal_datagram d, const void* buf, kal_uintptr
         // 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 };
+        return n == len ? static_cast<kal_intptr>(n) : -kal_err_io;
     }
 }
 
-kal_io_result kal_datagram_recv_from(kal_datagram d, void* buf, kal_uintptr len,
-                                     kal_endpoint* from) {
+kal_intptr 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 };
+    if (fd < 0) return -kal_err_invalid;
 
     okm::ksockaddr_storage ss{};
     okm_u32 addrlen = static_cast<okm_u32>(sizeof ss);
@@ -117,7 +117,7 @@ kal_io_result kal_datagram_recv_from(kal_datagram d, void* buf, kal_uintptr len,
                                     reinterpret_cast<okm_long>(&ss),
                                     reinterpret_cast<okm_long>(&addrlen));
         if (okm::interrupted(r)) continue;
-        if (okm::failed(r)) return { 0, okm::translate(r) };
+        if (okm::failed(r)) return -okm::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
@@ -133,7 +133,7 @@ kal_io_result kal_datagram_recv_from(kal_datagram d, void* buf, kal_uintptr len,
                 from->port     = 0;
             }
         }
-        return { static_cast<kal_uintptr>(r), kal_ok };
+        return static_cast<kal_intptr>(r);
     }
 }
 
@@ -148,6 +148,6 @@ void kal_datagram_close(kal_datagram d) {
 // 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;
+kal_uintptr kal_datagram_props(void) { return KAL_DGRAM_PROP_IPV6; }
 
 }  // extern "C"

src/env.cpp

@@ -27,46 +27,56 @@ extern "C" {
 
 kal_uintptr kal_env_arg_count(void) { return static_cast<kal_uintptr>(okm::g_argc); }
 
-const char* kal_env_arg(kal_uintptr index, kal_uintptr* len) {
-    if (index >= static_cast<kal_uintptr>(okm::g_argc)) { if (len) *len = 0; return nullptr; }
+// EVERY VALUE IS COPIED INTO THE CALLER'S BUFFER. These answered with a pointer
+// into this implementation's own storage, which is meaningful only while the
+// implementation shares the caller's address space. Each reports the length the
+// value HAS, so a caller with a large enough buffer is done in one call and one
+// that wants to size first passes a capacity of zero.
+namespace {
+kal_intptr give(const char* v, kal_uintptr n, char* out, kal_uintptr cap) {
+    if (out != nullptr && cap != 0) okm::copy(out, v, n < cap ? n : cap);
+    return static_cast<kal_intptr>(n);
+}
+}  // namespace
+
+kal_intptr kal_env_arg(kal_uintptr index, char* out, kal_uintptr cap) {
+    if (index >= static_cast<kal_uintptr>(okm::g_argc)) return -kal_err_not_found;
     const char* s = okm::g_argv[index];
-    if (len) *len = okm::length(s);
-    return s;
+    return give(s, okm::length(s), out, cap);
 }
 
-const char* kal_env_var(const char* name, kal_uintptr name_len, kal_uintptr* value_len) {
+kal_intptr kal_env_var(const char* name, kal_uintptr name_len,
+                       char* out, kal_uintptr cap) {
+    if (name == nullptr) return -kal_err_invalid;
     for (char** e = okm::g_envp; e && *e; ++e) {
         const char* entry = *e;
         kal_uintptr i = 0;
         while (i < name_len && entry[i] != '\0' && entry[i] == name[i]) ++i;
         if (i == name_len && entry[i] == '=') {
             const char* v = entry + name_len + 1;
-            if (value_len) *value_len = okm::length(v);
-            return v;
+            return give(v, okm::length(v), out, cap);
         }
     }
-    if (value_len) *value_len = 0;
-    return nullptr;
+    // A name that is not there is distinct from one whose value is empty.
+    return -kal_err_not_found;
 }
 
 kal_uintptr kal_env_var_count(void) {
     kal_uintptr n = 0; for (char** e = okm::g_envp; e && *e; ++e) ++n; return n;
 }
 
-const char* kal_env_var_at(kal_uintptr index, kal_uintptr* name_len,
-                           const char** value, kal_uintptr* value_len) {
+// The NAME at a position. The value is then obtained by kal_env_var: an
+// operation answering both needs two buffers, two capacities and two lengths,
+// and its second half is kal_env_var written again.
+kal_intptr kal_env_var_at(kal_uintptr index, char* out, kal_uintptr cap) {
     kal_uintptr n = 0;
     for (char** e = okm::g_envp; e && *e; ++e, ++n) {
         if (n != index) continue;
         const char* entry = *e;
         kal_uintptr i = 0; while (entry[i] != '\0' && entry[i] != '=') ++i;
-        if (name_len) *name_len = i;
-        const char* v = entry[i] == '=' ? entry + i + 1 : entry + i;
-        if (value)     *value = v;
-        if (value_len) *value_len = okm::length(v);
-        return entry;
+        return give(entry, i, out, cap);
     }
-    return nullptr;
+    return -kal_err_not_found;
 }
 
 }

src/exec.cpp

@@ -1,5 +1,6 @@
 #include "sys.h"
 #include <openkal/exec.h>
+#include <openkal/memory.h>
 
 // openkal.exec on this system.
 //
@@ -74,22 +75,83 @@
 
 namespace {
 
-constexpr okm_uptr kPage = 4096;
-
-// ⚠️ THE PAGE IS 16384 BYTES ON ONE OF THIS SYSTEM'S TWO ARCHITECTURES. Rounding
-// to the smaller number is still correct --- the kernel rounds up to its own
-// granularity, and a region reserved as 4096 occupies a whole page of whatever
-// size --- but a caller freeing with the size it reserved must reach the same
-// number, which it does because both go through the same rounding.
+// ⚠️ THE GRANULARITY IS ASKED FOR RATHER THAN ASSUMED. This file held
+// `constexpr okm_uptr kPage = 4096' and a comment arguing that rounding to the
+// smaller of this system's two page sizes was still correct because the kernel
+// rounds up. The argument holds for the reservation and fails for the release:
+// `munmap' with a length shorter than the mapping unmaps less than was mapped.
+// It is the same defect `src/memory.cpp' records having measured, in the same
+// system, one file away --- so the number now comes from the one operation
+// that answers it.
 okm_uptr round_up(okm_uptr n, okm_uptr to) { return (n + to - 1) & ~(to - 1); }
 
+okm_uptr granularity() {
+    return static_cast<okm_uptr>(kal_memory_granularity());
+}
+
+// ⭐⭐ WHETHER THIS SYSTEM GRANTS EXECUTABLE MEMORY IS MEASURED, NOT ARGUED.
+//
+// This file previously carried both answers. One comment reasoned that the
+// write-then-publish order is the case an entitlement is NOT needed for and
+// concluded the interface is provided unconditionally; another, thirty lines
+// below it, reasoned that executable memory is granted only to an artifact
+// produced with an entitlement and returned zero. The operations behaved as
+// the first said and the capability word said the second.
+//
+// ⚠️ AND THE DISAGREEMENT WAS INVISIBLE UNTIL A CONSUMER COULD READ THE WORD.
+// A statically-linked caller never asked: it linked the operations and used
+// them. The word became load-bearing when the specification made an
+// implementation's own account of itself part of the ABI, and the conformance
+// suite then reported what had been true all along --- `an implementation that
+// does not claim availability reserves nothing' DID NOT HOLD, because this one
+// claimed nothing and reserved anyway.
+//
+// The remedy is not to pick the more likely of the two readings. It is that
+// neither this file nor any comment in it is the party that knows: the answer
+// depends on how the artifact was signed, which is settled after this code is
+// compiled and can differ between two runs of the same binary. So the enquiry
+// performs the thing it is being asked about --- one reservation, one publish,
+// one release --- and reports what the kernel said.
+//
+// The probe is the operation's own path, so an environment where publishing
+// fails is one where this reports unavailable and `kal_exec_alloc' declines,
+// and the two can no longer disagree.
+int probe() {
+    const okm_uptr bytes = granularity();
+    const okm_long m = okm::sys(okm::nr_mmap, 0, static_cast<okm_long>(bytes),
+                                okm::prot_read | okm::prot_write,
+                                okm::map_private | okm::map_anon, -1, 0);
+    if (okm::failed(m)) return 2;
+    const okm_long p = okm::sys(okm::nr_mprotect, m,
+                                static_cast<okm_long>(bytes),
+                                okm::prot_read | okm::prot_exec);
+    okm::sys(okm::nr_munmap, m, static_cast<okm_long>(bytes));
+    return okm::failed(p) ? 2 : 1;
+}
+
+// Asked once. Constant-initialised, so no guard variable is emitted and this
+// file acquires no dependency upon the runtime --- the property the
+// independence check in this package exists to hold. Two contexts racing here
+// perform the probe twice and store the same answer.
+bool available() {
+    static int cached = 0;
+    int v = __atomic_load_n(&cached, __ATOMIC_RELAXED);
+    if (v == 0) { v = probe(); __atomic_store_n(&cached, v, __ATOMIC_RELAXED); }
+    return v == 1;
+}
+
 }  // namespace
 
 extern "C" {
 
 void* kal_exec_alloc(kal_uintptr size) {
     if (size == 0) return nullptr;
-    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), kPage);
+    // An implementation that does not claim availability reserves nothing.
+    // Otherwise the word is advice a caller cannot act upon: it would report
+    // unavailable and then hand back memory, and a caller that believed the
+    // word would have declined memory it could have had.
+    if (!available()) return nullptr;
+    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), granularity());
     const okm_long r = okm::sys(okm::nr_mmap, 0, static_cast<okm_long>(bytes),
                                 okm::prot_read | okm::prot_write,
                                 okm::map_private | okm::map_anon, -1, 0);
@@ -99,7 +161,7 @@ void* kal_exec_alloc(kal_uintptr size) {
 
 int kal_exec_publish(void* p, kal_uintptr size) {
     if (p == nullptr || size == 0) return kal_err_invalid;
-    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), kPage);
+    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), granularity());
     const okm_long r = okm::sys(okm::nr_mprotect, reinterpret_cast<okm_long>(p),
                                 static_cast<okm_long>(bytes),
                                 okm::prot_read | okm::prot_exec);
@@ -109,17 +171,19 @@ int kal_exec_publish(void* p, kal_uintptr size) {
 
 void kal_exec_free(void* p, kal_uintptr size) {
     if (p == nullptr || size == 0) return;
-    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), kPage);
+    const okm_uptr bytes = round_up(static_cast<okm_uptr>(size), granularity());
     okm::sys(okm::nr_munmap, reinterpret_cast<okm_long>(p),
              static_cast<okm_long>(bytes));
 }
 
 // A published region may NOT be reserved for writing again on this system, and
-// the position is withheld accordingly. Asking this kernel to make an executable
-// mapping writable is the case it refuses, which is the whole reason the
-// interface separates the two states; a caller that must change published bytes
-// reserves a second region and abandons the first, which is what the header
-// says a zero here means.
-const kal_uintptr kal_exec_props = 0;
+// the position is withheld accordingly. Asking this kernel to make an
+// executable mapping writable is the case it refuses, which is the whole reason
+// the interface separates the two states; a caller that must change published
+// bytes reserves a second region and abandons the first, which is what the
+// header says a zero in that position means.
+kal_uintptr kal_exec_props(void) {
+    return available() ? KAL_EXEC_PROP_AVAILABLE : 0;
+}
 
 }  // extern "C"