mcpplibs
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 56 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 56 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 75 additions & 11 deletions b/‎README.md‎
Lines changed: 75 additions & 11 deletions
diff --git a/‎board.ld‎
Lines changed: 145 additions & 0 deletions b/‎board.ld‎
Lines changed: 145 additions & 0 deletions
diff --git a/‎build.mcpp‎
Lines changed: 18 additions & 0 deletions b/‎build.mcpp‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎examples/hello/build.mcpp‎
Lines changed: 8 additions & 7 deletions b/‎examples/hello/build.mcpp‎
Lines changed: 8 additions & 7 deletions
diff --git a/‎examples/hello/link.ld‎
Lines changed: 0 additions & 12 deletions b/‎examples/hello/link.ld‎
Lines changed: 0 additions & 12 deletions
diff --git a/‎examples/hello/mcpp.toml‎
Lines changed: 1 addition & 1 deletion b/‎examples/hello/mcpp.toml‎
Lines changed: 1 addition & 1 deletion
@@ -15,6 +15,9 @@ jobs:
       MCPP_VERSION: 2026.8.20.2
       XLINGS_VERSION: v2026.8.17.2
       XLINGS_NON_INTERACTIVE: '1'
+      # The branch of the specification this backend is verified against. It
+      # moves with this one; when both are on `main` this becomes `main`.
+      OPENKAL_BRANCH: feat/openkal-closure
     steps:
       - uses: actions/checkout@v4
 
@@ -78,6 +81,59 @@ jobs:
           mcpp run 2>&1 | tee run.log
           grep -q "hello from openkal over SBI" run.log
           grep -q "heap ok" run.log
+          # ⚠️ `clock ok` is the line that distinguishes a counter that reads
+          # from a counter that MOVES. The example takes two readings with a
+          # sleep between them; a stuck clock reads fine and prints
+          # `clock stuck`. Verified to print it, by returning a constant from
+          # `kal_time_monotonic` and rerunning.
+          grep -q "clock ok" run.log
+          grep -q "env empty" run.log
+
+      # ⭐⭐ THE HALF OF CLAUSE 9 THIS BACKEND WAS NOT PERFORMING.
+      #
+      # The specification makes behavioural conformance a property of every
+      # implementation, and three of the four in this ecosystem ran the suite
+      # while this one did not. The difficulty was real and it was not that the
+      # suite needs an operating system: the suite depends on openkal and the
+      # language, does not import std, and states in its own manifest that it is
+      # written to run in a program that carries no other runtime.
+      #
+      # ⚠️ What it needed was three things this environment supplies and a
+      # hosted one does not have to, and each was found by trying:
+      #
+      #   the memory map        — now `openkal-opensbi/board.ld`, reaching the
+      #                           suite through this package's build program,
+      #                           because where firmware hands control over is a
+      #                           fact about this environment and not about any
+      #                           program that runs on it;
+      #   the hand-over         — `--features standalone`, which is how every
+      #                           implementation here performs it when no C
+      #                           library is beneath the program;
+      #   an entry symbol       — the suite's `main` is `extern "C"`, because
+      #                           `-ffreestanding` makes `main` an ordinary
+      #                           function and the startup object refers to it
+      #                           by name.
+      #
+      # ⚠️ THE ASSERTION IS ON THE OUTPUT AND ON THE EXIT STATUS BOTH. The suite
+      # exits 2 when it observed nothing, which is the outcome a selection that
+      # matched no interface would otherwise pass silently — and `core` on a
+      # machine with no operating system is exactly the selection where that
+      # could happen.
+      - name: The conformance suite runs on the machine with no operating system
+        run: |
+          set -euo pipefail
+          git clone --quiet --depth 1 -b "$OPENKAL_BRANCH" \
+            https://github.com/mcpplibs/openkal "$RUNNER_TEMP/spec"
+          Q=$(ls -d "$HOME"/.mcpp/registry/data/xpkgs/xim-x-qemu-riscv/*/bin/qemu-system-riscv64 | head -1)
+          export OPENKAL_CONFORMANCE_RUNNER="$Q -machine virt -nographic -no-reboot -bios default -kernel"
+          export OPENKAL_CONFORMANCE_IMPL_FEATURES=standalone
+          cd "$RUNNER_TEMP/spec"
+          bash tools/run-conformance.sh openkal-opensbi "$GITHUB_WORKSPACE" core \
+            --target riscv64-none-elf 2>&1 | tee conf.log
+          grep -q "the implementation conforms in every observation made" conf.log
+          # ⚠️ And that something WAS observed. "0 did not hold" is also what a
+          # run that examined nothing reports.
+          grep -qE "observations: [1-9][0-9]* held" conf.log
 
   # ---------------------------------------------------------------------------
   # The cross-compilation is performed FROM three systems, not only from Linux.
 
@@ -23,16 +23,45 @@ requires firmware beneath it, a board backend does not.
 
 ## What is implemented
 
-`abort`, `stream` and `memory` — openkal's core set. An implementation provides
-an interface in whole or not at all, so the absence of `fs`, `process`, `task`,
-`env` and `time` is not a deviation; `import openkal.task;` simply does not
-resolve.
+`abort`, `stream` and `memory` — openkal's core set — plus `time` and `env`. An
+implementation provides an interface in whole or not at all, so the absence of
+`fs`, `process` and `task` is not a deviation; `import openkal.task;` simply
+does not resolve. This machine has no storage, no second image to start and no
+scheduler, and clause 6.2 says the remedy for an operation that cannot be
+provided is that its absence be expressed by its absence rather than by a
+run-time refusal.
+
+⚠️ **`time` used to be on that list, with a reason, and the reason was wrong.**
+
+It read: SBI can arm a timer interrupt, which is a mechanism for a kernel rather
+than a clock a program can read. The first half is true. The second does not
+follow from it — this architecture also exposes `rdtime` directly to the
+program, through the `time` CSR, independently of SBI's timer extension. Two
+different facilities, and the absence of the first says nothing about the
+second.
+
+Measured 2026-08-23 under OpenSBI on QEMU's `virt`, from supervisor mode with no
+kernel beneath:
 
-⚠️ **`time` is absent deliberately, and SBI does have a timer.** SBI can arm a
-timer interrupt, which is a mechanism for a kernel rather than a clock a program
-can read. Reporting a clock that does not advance would make every timed wait
-silently wrong — the specification's own example of a simulation that
-disqualifies an interface from being provided at all.
+```
+t0=333572 t1=381292  ADVANCES
+```
+
+⭐ The conclusion got rechecked and the reason beside it did not. The two
+minutes that refuted it had been available for as long as the file existed.
+
+`time` is therefore provided: a monotonic count, an exact granularity, and a
+sleep that spins on the same counter — which on a machine with one execution
+context and nothing to yield to is what sleeping *is*, so
+`KAL_TIME_PROP_SLEEP_PRECISE` is set truthfully. **Not** a wall clock: SBI
+defines no facility for one, `KAL_TIME_PROP_WALL_AVAILABLE` is clear, and clause
+6.2 makes that a property rather than a missing interface.
+
+`env` is provided and every answer is empty. That is an implementation, not a
+stub: firmware enters the image with a hart identifier and a device tree, and
+neither is a command line, so this environment *has* an environment and it has
+nothing in it. A caller enumerating zero things needs no special case, which is
+exactly what distinguishes this from the run-time refusal clause 6.2 forbids.
 
 ## The heap is a bump allocator, and that is a bound rather than an omission
 
@@ -47,6 +76,36 @@ The region is 64 KiB by default. A project that needs another figure overrides
 allocation pattern needs reuse should place a real allocator above this one;
 that is policy, and openkal carries mechanism.
 
+## The memory map is this package's, because it is a fact about this machine
+
+`board.ld` states where the firmware hands control over (`0x80200000`, since
+OpenSBI itself occupies the start of RAM), what the layout has to contain for a
+C++ program to work — the initialiser arrays, the unwind tables and their bounds,
+the thread-local segment — and how much stack and heap the image reserves. It
+reaches a consumer's link line through this package's build program, in the same
+way its `kal_*` definitions reach the consumer's objects.
+
+A program therefore states nothing. Until 2026-08-23 every program that wanted to
+run here carried a copy: `examples/hello` had one, the C++ runtime's
+`same-source` example had a second, and the specification's conformance suite
+would have needed a third. None of those is a property of a program.
+
+⚠️ **A program that states one as well states it twice.** The fact reaches
+consumers transitively, and two linker scripts are both applied — which fails as
+overlapping output sections and says nothing about there being two:
+
+```
+ld.lld: error: section .eh_frame file range overlaps with .debug_str_offsets
+```
+
+The sizes — 256 KiB of stack, 16 MiB of heap — are generous rather than minimal,
+and that is the one judgement in the file. A C program printing a string needs
+neither; a program carrying a C library and a C++ standard library does, and it
+exhausts smaller figures during its own initialisation, before `main`, so what it
+looks like is a program that starts and prints nothing. Both regions lie past the
+end of the image and cost nothing in it. A board with far less memory states its
+own map instead of taking this one.
+
 ## Two details that were measured rather than assumed
 
 **DBCN is probed, not assumed.** The Debug Console extension arrived in SBI
@@ -70,7 +129,12 @@ heap ok
 ```
 
 The image carries no C library (`[target.<triple>].sysroot = ""`) and no board
-package. It is loaded at `0x80200000`, because OpenSBI itself occupies the start
-of RAM.
+package, and it states no memory map of its own: `board.ld` above is this
+package's.
+
+The specification's conformance suite also runs here, under the same firmware,
+selected to the `core` set — twelve observations held, none failed. Clause 9
+makes the behavioural half a property of every implementation, and an
+implementation of a machine with no operating system is not exempt from it.
 
 [kal]: https://github.com/mcpplibs/openkal
@@ -0,0 +1,145 @@
+/* The memory map of a program this implementation starts, and the symbols its
+ * startup object reads.
+ *
+ * ⭐⭐ THIS FILE IS A BOARD FACT AND THEREFORE BELONGS TO THIS PACKAGE.
+ *
+ * Until now every program that wanted to run over OpenSBI carried its own copy:
+ * `examples/hello` had one, `openkal-llvm-runtime/examples/same-source` had a
+ * second, and the specification's conformance suite would have needed a third.
+ * The load address is not a property of any of them — it is where this firmware
+ * hands control over, which is precisely what this package exists to know.
+ *
+ * ⚠️ Measured 2026-08-23: the conformance suite BUILDS for `riscv64-none-elf`
+ * against this implementation and then produces an image whose entry point is
+ * 0x0, because nothing placed it. The suite is written to run in a program that
+ * carries no other runtime, and asking it to carry a board's memory map would
+ * contradict that — clause 9 makes behavioural conformance a property of every
+ * implementation, including one of a machine with no operating system.
+ *
+ * ⇒ Supplied through `build.mcpp`, which reaches the CONSUMER's link line. A
+ * program adds nothing and gets a layout that works.
+ *
+ * ⚠️ THE SIZES ARE GENEROUS RATHER THAN MINIMAL, and that is the one judgement
+ * in this file. A C program printing a string needs neither 256 KiB of stack
+ * nor 16 MiB of heap; a program carrying a C library and a C++ standard library
+ * does, and it exhausts the smaller figures during its own initialisation —
+ * before `main`, so what it looks like is a program that starts and prints
+ * nothing. Both are past the end of the image and cost nothing in it, and
+ * QEMU's `virt` has 128 MiB. A board with far less can state its own.
+ *
+ * What follows is what a C++ program needs the layout to contain.
+ *
+ * OpenSBI occupies 0x80000000 upward and hands control to the next stage at
+ * 0x80200000, which is why this address and not the start of RAM.
+ *
+ * ⚠️ FIRMWARE JUMPS TO THE LOWEST LOADED ADDRESS AND NOT TO THE ENTRY THE IMAGE
+ * RECORDS. Measured 2026-08-23, after an attempt to put the ELF header inside
+ * the first loaded segment so that `__ehdr_start` would be usable: the entry
+ * moved to 0x80200270, OpenSBI still announced `Next Address 0x80200000`, and
+ * the machine hung executing the header as instructions. So the first thing at
+ * the load address has to be the first instruction, and everything that would
+ * otherwise be read out of the program headers is named here instead.
+ *
+ * ⚠️ FOUR THINGS BEYOND THE MINIMUM, AND EACH IS SOMETHING A C++ PROGRAM HAS
+ * THAT A C ONE DOES NOT.
+ *
+ *   The initialiser arrays. Every static object with a constructor puts a
+ *   pointer in .init_array, and the C library walks it between symbols the
+ *   LINKER normally provides. A script that does not name them gets an empty
+ *   range and every such object stays unconstructed --- which does not fail,
+ *   it MISBEHAVES, and that is worse.
+ *
+ *   The unwind tables, and the two symbols that bound them. libunwind built
+ *   with _LIBUNWIND_IS_BAREMETAL looks them up by name instead of walking
+ *   program headers; the fragment below is the one its AddressSpace.hpp
+ *   documents, reproduced rather than invented.
+ *
+ *   The thread-local segment, and three symbols describing it. The startup
+ *   object in openkal-opensbi builds one context's storage from them. Without
+ *   it the register that names thread-local storage holds whatever reset left,
+ *   and the first `throw` faults inside `__cxa_get_globals` --- a message that
+ *   names an exception function and says nothing about a thread pointer.
+ *
+ *   A stack big enough for the standard library. 16 KiB is enough for a program
+ *   that prints a string; formatting through <format> and sorting a vector is
+ *   not that program.
+ */
+ENTRY(_start)
+SECTIONS {
+    . = 0x80200000;
+
+    .text : { *(.text.entry) *(.text .text.*) }
+
+    .rodata : { *(.rodata .rodata.*) *(.srodata .srodata.*) }
+
+    /* Verbatim from libunwind's AddressSpace.hpp, which is where the names come
+     * from. `--eh-frame-hdr` on the link line is what makes the index exist at
+     * all; without it the section is empty and the two `_hdr_` symbols are the
+     * zero the conditional below produces, which libunwind reads as "no index"
+     * and falls back to scanning. */
+    .eh_frame : {
+        __eh_frame_start = .;
+        KEEP(*(.eh_frame))
+        __eh_frame_end = .;
+    }
+    .eh_frame_hdr : { KEEP(*(.eh_frame_hdr)) }
+    __eh_frame_hdr_start = SIZEOF(.eh_frame_hdr) > 0 ? ADDR(.eh_frame_hdr) : 0;
+    __eh_frame_hdr_end   = SIZEOF(.eh_frame_hdr) > 0 ? . : 0;
+
+    .preinit_array : {
+        PROVIDE_HIDDEN(__preinit_array_start = .);
+        KEEP(*(.preinit_array))
+        PROVIDE_HIDDEN(__preinit_array_end = .);
+    }
+    .init_array : {
+        PROVIDE_HIDDEN(__init_array_start = .);
+        KEEP(*(SORT_BY_INIT_PRIORITY(.init_array.*)))
+        KEEP(*(.init_array))
+        PROVIDE_HIDDEN(__init_array_end = .);
+    }
+    .fini_array : {
+        PROVIDE_HIDDEN(__fini_array_start = .);
+        KEEP(*(SORT_BY_INIT_PRIORITY(.fini_array.*)))
+        KEEP(*(.fini_array))
+        PROVIDE_HIDDEN(__fini_array_end = .);
+    }
+
+    /* The thread-local segment, and its three measurements.
+     *
+     * They are named here rather than read from PT_TLS for the reason at the
+     * top of this file: the program headers are not reachable at run time on
+     * this target. The startup object takes the initialised bytes from
+     * `__tls_start`, copies `__tls_filesz` of them, and zeroes out to
+     * `__tls_memsz` — which is what a loader does. */
+    .tdata : { __tls_start = .; *(.tdata .tdata.*) }
+    .tbss  : { *(.tbss .tbss.*) *(.tcommon) }
+    __tls_filesz = SIZEOF(.tdata);
+    __tls_memsz  = SIZEOF(.tdata) + SIZEOF(.tbss);
+
+    .data : { *(.data .data.*) *(.sdata .sdata.*) }
+
+    .bss : {
+        __bss_start = .;
+        *(.sbss .sbss.*) *(.bss .bss.*) *(COMMON)
+        __bss_end = .;
+    }
+
+    /* 256 KiB of stack. See the note above. */
+    . = ALIGN(16); . = . + 0x40000; __stack_top = .;
+
+    /* ⭐ AND THE HEAP, WHICH FOR THIS PROGRAM CANNOT BE THE IMPLEMENTATION'S
+     * DEFAULT.
+     *
+     * openkal-opensbi carries a 64 KiB static region for a program that
+     * allocates a little. A program carrying a C library and a C++ standard
+     * library allocates during its own initialisation, before `main`, and does
+     * not survive that figure — measured, and what it looks like is a program
+     * that starts and prints nothing, because the allocator runs out before
+     * there is a stream to report it on.
+     *
+     * So the region is stated here, where the stack's size already is, and it
+     * costs nothing in the image: it is past the end and QEMU's `virt` has
+     * 128 MiB. 16 MiB is comfortably more than this program needs and small
+     * enough to fit a machine with far less. */
+    . = ALIGN(16); __heap_start = .; . = . + 0x1000000; __heap_end = .;
+}
@@ -0,0 +1,18 @@
+import mcpp;
+
+// ⭐ THE BOARD'S MEMORY MAP, PUT ON THE CONSUMER'S LINK LINE.
+//
+// `board.ld` records where this firmware hands control over and what a program
+// started that way needs its layout to contain. Both are facts about this
+// environment rather than about any program, which is why they are here and not
+// copied into each one — see the head of that file for what the copies were.
+//
+// ⚠️ `link_script` reaches the CONSUMER's link line, and a relative path in
+// `ldflags` would resolve against the build directory instead of against this
+// package. That is the same reason `openkal-macos` supplies its stub through a
+// `link_search` rather than a path in a flag.
+int main() {
+    mcpp::link_script("board.ld");
+    mcpp::rerun_if_changed("board.ld");
+    return 0;
+}
@@ -1,8 +1,9 @@
 import mcpp;
-int main() {
-    // A relative path in `ldflags` would resolve against the build directory;
-    // `link-script` resolves against the package root.
-    mcpp::link_script("link.ld");
-    mcpp::rerun_if_changed("link.ld");
-    return 0;
-}
+
+// Nothing to state. The memory map comes from `openkal-opensbi`, which is the
+// package that knows where this firmware hands control over; this example
+// carried a copy of it until 2026-08-23.
+//
+// The file remains because a build program is how this example would say
+// anything at all, and its absence would read as "this was never considered".
+int main() { return 0; }
@@ -13,5 +13,5 @@ runner  = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
            "-no-reboot", "-bios", "default", "-kernel"]
 
 [dependencies]
-openkal         = "0.5.1"
+openkal         = { git = "https://github.com/mcpplibs/openkal", branch = "feat/openkal-closure" }
 openkal-opensbi = { path = "../.." }