0.4.0: a platform question for a native build and an image alike; the platform modules in an image

can_run_on(p) and on<P>(f) beside is_<platform>; R5 revised: a platform module is defined where it
can be answered, a native build of its platform and an image that asks the system it runs upon
(translator, elevated, on_dev_drive, effective_user; translated is false). tests/facts_test runs the
questions on every row, natively and as images.

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>

Author: Sunrisepeak

.gitignore

@@ -4,3 +4,4 @@ compile_commands.json
 *.log
 mcpp.lock
 
+.mcpp/

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.4.0
+
+- **A platform question for a native build and an image alike.** `can_run_on(p)`
+  says whether this build can run on `p` (a native build on its own system, an
+  image on every system a loader runs upon), and `on<P>(f)` runs `f` when the
+  build runs on `P` now. `if constexpr (can_run_on(P))` keeps another system's
+  platform module out of a native build, as `if constexpr (is_<platform>)` does;
+  `host()` then decides in an image, where `is_<platform>` is false and a branch
+  under it never runs. `on<P>` takes the platform as an argument, so its body is
+  a template a build that cannot run on `P` never instantiates; a lambda without
+  the parameter is refused. `is_<platform>` keeps its meaning: a native build of
+  that platform (README, "A platform question").
+- **The platform modules in an image (R5 as revised).** A platform module is
+  defined where it can be answered: in a native build of its platform, and in an
+  image where the image can ask the system it runs upon. `linux::translator()`
+  reads /proc as on Linux; `windows::elevated()` reads the integrity level
+  `whoami /groups` lists, by SID; `windows::on_dev_drive()` asks `fsutil devdrv
+  query`; `posix::effective_user()` reads /proc on Linux and `/usr/bin/id -u` on
+  macOS; `macos::translated()` is `false`, since macOS runs images through an
+  aarch64 okrun only. The system's programs are started by absolute name with a
+  bound of ten seconds, and each answer is asked once. The code pages, long
+  names, the registry, the writable drives and the creation mask remain
+  undefined in an image: okrun carries an image's streams and names, and the
+  others belong to a native installation. Before 0.4.0 an image defined no
+  platform module, and a program shipped as an image that guarded them with
+  `if constexpr (is_<platform>)` lost them without a word (mcpp-community/mcpp
+  design 2026-11-08, S2 and S3).
+
 ## 0.3.1
 
 - **A name in the long spelling is the name it spells.** `fs::extended` writes

README.md

@@ -6,7 +6,7 @@ with compile-time platform constants and a few platform modules.
 
 ```toml
 [dependencies]
-os = { namespace = "mcpplibs", version = "0.3.1" }
+mcpplibs.os = "0.4.0"
 ```
 
 ```cpp
@@ -106,7 +106,7 @@ dropped (0.2.8).
 
 | Module | Contents |
 |---|---|
-| `mcpplibs.os.platform` | `PLATFORM`, `ARCH`, `is_linux` / `is_macos` / `is_windows` / `is_posix` / `is_emscripten`, `exe_suffix`, `path_list_separator`; `host()`, a constant expression on a native target |
+| `mcpplibs.os.platform` | `PLATFORM`, `ARCH`, `is_linux` / `is_macos` / `is_windows` / `is_posix` / `is_emscripten`, `exe_suffix`, `path_list_separator`; `host()`, a constant expression on a native target; `can_run_on(p)` and `on<P>(f)`, a platform question that holds in a native build and an image alike |
 | `mcpplibs.os.error` | `errc` (openkal's closed set of conditions), `error`, `result<T>` |
 | `mcpplibs.os.env` | variables (names without case on Windows), `NAME=value` entries as overrides (`assignments`), arguments, the program's own image, lists of directories in the host's separator (`split_list`, `join_list`), PATH search with PATHEXT |
 | `mcpplibs.os.fs` | `write_atomic`, `publish` (no replace), `append`, `sync`, `caps`, `lock`, links, `set_executable`, `stamp_of`, `identity_of`, `owner_of`, `writable`, `locate`, `absolute`, `names_a_place`, `canonical`, a bounded `read`; what a volume does, measured (`measure`, `volume_type`), and the operations that follow it (`place`, `exchange`); names in the host's rules without the file system: `generic`, `native`, `extended`, `is_absolute`, `same`, `within` |
@@ -120,7 +120,7 @@ dropped (0.2.8).
 | `mcpplibs.os.machine` | the machine's architecture (through Rosetta and WoW64), memory and the memory available now, processors (logical, physical, of differing speed) |
 | `mcpplibs.os.random` | bytes from the system's source of unpredictable bytes; `hex` |
 | `mcpplibs.os.library` | shared libraries at run time: `open` (a path or a name the system searches for), `loaded` (one the process has, without loading it), a handle's `symbol` / `function<F>`, `process_symbol` (as the loader resolves one), `suffix` |
-| `mcpplibs.os.linux` / `.macos` / `.windows` / `.posix` | platform modules: declared on every target, defined only on their own |
+| `mcpplibs.os.linux` / `.macos` / `.windows` / `.posix` | platform modules: declared on every target, defined on their own and, where an image can answer, in an image |
 
 ## Rules
 
@@ -133,9 +133,10 @@ dropped (0.2.8).
   - in an image (`<arch>-openkal`) it is an ordinary function, and using it in a constant
     expression is a compile error.
 - **R4.** A native handle does not appear in a portable type.
-- **R5.** A platform module is declared on every target and defined only on its own. A call
-  outside `if constexpr` for that platform is a link error. The same call in a discarded branch
-  is not an odr-use, so it links. CI asserts both.
+- **R5.** A platform module is declared on every target and defined where it can be answered: in
+  a native build of its own platform, and in an image where the image can ask the system it runs
+  upon (0.4.0). Elsewhere a call outside `if constexpr` is a link error. The same call in a
+  discarded branch is not an odr-use, so it links. CI asserts both.
 - **R6.** Where openkal is not in its shared form, this package's resources do not cross a
   shared-object boundary.
 - **R7.** A name reaches the system as UTF-8 and comes back as UTF-8 on every host, never
@@ -145,11 +146,51 @@ dropped (0.2.8).
   nothing else. The tests write, read and rename names in four scripts.
 
 Interface units import `std` and contain no system header and no macro. Implementation units
-on openkal import only `openkal.*`. The Windows and macOS units declare the functions they
+on openkal import only `openkal.*` and this package's own modules. The Windows and macOS units declare the functions they
 call themselves (`src/windows/win32.h`, `src/macos/darwin.h`). Linux's and macOS's kernel
 calls are in `src/linux/arch/` and `src/macos/arch/`, which the manifest selects by
 architecture.
 
+## A platform question, in a native build and an image
+
+Two questions are asked of the platform, and each has its form:
+
+| Question | Form | Native build | Image |
+|---|---|---|---|
+| Is this a native build for the platform? | `if constexpr (os::is_windows)` | a constant | `false` |
+| Does this build run on the platform now? | `if constexpr (os::can_run_on(P))` with `if (os::host() == P)`, or `os::on<P>([&](auto) { ... })` | a constant; another system's branch is discarded | known when the image is loaded |
+
+The first is right for code that belongs to a native build alone: a console's code page set
+for the C library's narrow functions has no meaning in an image, whose streams okrun carries.
+The second is right for code that is to take effect wherever the program runs, which is what a
+program shipped as an image needs:
+
+```cpp
+if constexpr (os::can_run_on(os::platform::windows))
+    if (os::host() == os::platform::windows)
+        onDevDrive = os::windows::on_dev_drive(cache);
+
+os::on<os::platform::linux>([&](auto) { sandbox = os::linux::translator().value_or(""); });
+```
+
+`on<P>` takes the platform as a parameter, so the body is a template and a build that cannot
+run on `P` never instantiates it; a lambda without the parameter is refused, because its body
+would name another system's module on every build. The platform modules in an image:
+
+| Function | In an image |
+|---|---|
+| `linux::translator()` | `/proc/self/status`, the tracer's `comm` and the environment, as on Linux |
+| `windows::elevated()` | the integrity level `whoami /groups` lists (SID `S-1-16-12288` or `S-1-16-16384`) |
+| `windows::on_dev_drive()` | `fsutil devdrv query <volume>`; not known when the tool answers in another language or refuses |
+| `posix::effective_user()` | `/proc/self/status` on Linux, `/usr/bin/id -u` on macOS; the largest number when neither answers |
+| `macos::translated()` | `false`: macOS runs images through an aarch64 okrun only |
+| `windows::code_page()`, `console_output_code_page()`, `long_paths_enabled()`, `machine_registry_path()`, `writable_fixed_drive()`, `posix::set_creation_mask()` | not defined: okrun carries an image's streams and names, and the others belong to a native installation |
+
+The system's programs are started by absolute name (`%SystemRoot%\System32`, `/usr/bin`), with a
+bound of ten seconds, and each answer is asked once per process. `host()` decides which system's
+question applies, which is that system's convention; whether a program can be started is
+openkal's capability and is answered by the start itself (openkal SPEC clause 30).
+
 ## As an ok image
 
 Built for `<arch>-openkal` (openkal SPEC clause 12), a program over this library

checks/discarded/src/main.cpp

@@ -13,5 +13,10 @@ int main() {
     if constexpr (os::is_linux) n += static_cast<int>(os::linux::translator().has_value());
     if constexpr (os::is_macos) n += static_cast<int>(os::macos::translated());
     if constexpr (os::is_windows) n += static_cast<int>(os::windows::elevated());
+    // The same calls in the form that also holds in an image (0.4.0).
+    if constexpr (os::can_run_on(os::platform::linux))
+        if (os::host() == os::platform::linux) n += static_cast<int>(os::linux::translator().has_value());
+    os::on<os::platform::macos>([&](auto) { n += static_cast<int>(os::macos::translated()); });
+    os::on<os::platform::windows>([&](auto) { n += static_cast<int>(os::windows::elevated()); });
     return n >= 0 ? 0 : 1;
 }

checks/emscripten/tests/facts_test.cpp

@@ -0,0 +1,6 @@
+// facts_test.cpp of mcpplibs.os, compiled in this arrangement. The imports are restated
+// because the dependency scan reads this file and not the one it includes.
+#include "../../../tests/check.hpp"
+import std;
+import mcpplibs.os;
+#include "../../../tests/facts_test.cpp"

checks/hosted/tests/facts_test.cpp

@@ -0,0 +1,6 @@
+// facts_test.cpp of mcpplibs.os, compiled in this arrangement. The imports are restated
+// because the dependency scan reads this file and not the one it includes.
+#include "../../../tests/check.hpp"
+import std;
+import mcpplibs.os;
+#include "../../../tests/facts_test.cpp"

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "os"
-version     = "0.3.1"
+version     = "0.4.0"
 description = "mcpplibs.os: a C++ operating-system library over openkal --- processes, files, environment, terminals, directories and local IPC, with compile-time platform constants and a few platform modules."
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]
@@ -108,10 +108,13 @@ sources = ["src/windows/posix/stdio.cpp"]
 sources = ["src/targets/emscripten.cppm", "src/emscripten/*.cpp", "src/posix/fs.cpp"]
 
 # AN OK IMAGE (`<arch>-openkal', openkal SPEC clause 12): no implementation
-# beneath --- the loader binds the image's `kal_*' --- and no platform module
-# defined. `host()' and the conventions are answered when the image is loaded.
+# beneath --- the loader binds the image's `kal_*' --- and the platform modules
+# defined where an image can answer them (R5 as revised in 0.4.0): Linux's
+# translator from /proc, Windows' token and developer volume and the POSIX
+# effective user from the system's own programs, macOS' translation as never.
+# `host()' and the conventions are answered when the image is loaded.
 [target.'cfg(os = "openkal")'.build]
-sources = ["src/targets/openkal.cppm", "src/openkal/*.cpp"]
+sources = ["src/targets/openkal.cppm", "src/openkal/*.cpp", "src/linux/linux.cpp"]
 
 # The C library, the C++ run-time and the loader of an image are its
 # platform's: mcpp 2026.10.27.1 and later select openkal-platform for

src/openkal/macos.cpp

@@ -0,0 +1,15 @@
+// mcpplibs.os.macos in an ok image (0.4.0): never translated. macOS runs
+// images through an okrun of its own architecture only (aarch64; there is no
+// x86-64 okrun for macOS), so an image there is never run by Rosetta. When an
+// x86-64 okrun exists, the answer is "an x86-64 image on a machine with
+// `hw.optional.arm64'"; `sysctl.proc_translated' would answer for the sysctl
+// program asked, not for the image.
+module mcpplibs.os.macos;
+
+import std;
+
+namespace mcpplibs::os::macos {
+
+bool translated() { return false; }
+
+}  // namespace mcpplibs::os::macos

src/openkal/posix.cpp

@@ -0,0 +1,57 @@
+// mcpplibs.os.posix in an ok image (0.4.0): the effective user, asked of the
+// system the image runs upon. The creation mask is a state of the process that
+// openkal does not expose, and remains undefined in an image.
+module mcpplibs.os.posix;
+
+import std;
+import mcpplibs.os.platform;
+import mcpplibs.os.process;
+
+namespace mcpplibs::os::posix {
+
+namespace {
+
+// The second number of the `Uid:' line of /proc/self/status, the effective one.
+std::optional<std::uint32_t> from_status() {
+    std::ifstream in("/proc/self/status", std::ios::binary);
+    for (std::string line; std::getline(in, line);) {
+        if (!line.starts_with("Uid:")) continue;
+        std::istringstream fields(line.substr(4));
+        std::uint32_t real = 0, effective = 0;
+        if (fields >> real >> effective) return effective;
+    }
+    return std::nullopt;
+}
+
+std::optional<std::uint32_t> from_id() {
+    process::spawn_options o;
+    o.program = "/usr/bin/id";
+    o.args = {"-u"};
+    o.in = process::stdio::null;
+    o.err = process::stdio::null;
+    process::bounds limits;
+    limits.hard = std::chrono::seconds{10};
+    auto r = process::run(std::move(o), limits);
+    if (!r || !r->status.success()) return std::nullopt;
+    std::uint32_t v = 0;
+    const auto& s = r->out;
+    const auto [end, ec] = std::from_chars(s.data(), s.data() + s.size(), v);
+    if (ec != std::errc{} || end == s.data()) return std::nullopt;
+    return v;
+}
+
+}  // namespace
+
+// Not known -- not a POSIX system, or neither source answered -- is the largest
+// number, which names no user.
+std::uint32_t effective_user() {
+    static const std::uint32_t answer = [] {
+        std::optional<std::uint32_t> v;
+        if (host() == platform::linux) v = from_status();
+        if (!v && (host() == platform::linux || host() == platform::macos)) v = from_id();
+        return v.value_or(std::numeric_limits<std::uint32_t>::max());
+    }();
+    return answer;
+}
+
+}  // namespace mcpplibs::os::posix

src/openkal/windows.cpp

@@ -0,0 +1,77 @@
+// mcpplibs.os.windows in an ok image (0.4.0, R5 as revised): an image reaches
+// no Win32 function (it loads no library of the system, openkal SPEC clause
+// 12), so what it answers it asks a program of the system for. Only the facts
+// a program of Windows reports are defined here; the code pages, long names,
+// the registry and the drives a user writes to are okrun's affair or the
+// native build's, and remain undefined in an image (a use is a link error).
+//
+// `host()' decides which system's question applies, which is a convention of
+// that system and not a capability of openkal's implementation (SPEC clause
+// 30); whether a program can be started at all is openkal's capability, and a
+// refusal is answered as "not known".
+module mcpplibs.os.windows;
+
+import std;
+import mcpplibs.os.platform;
+import mcpplibs.os.env;
+import mcpplibs.os.process;
+
+namespace mcpplibs::os::windows {
+
+namespace {
+
+// `%SystemRoot%\System32\<tool>.exe', never a name looked for on PATH.
+std::optional<std::filesystem::path> system_tool(std::string_view tool) {
+    auto root = env::get("SystemRoot");
+    if (!root || root->empty()) return std::nullopt;
+    std::string name(tool);
+    name += ".exe";
+    return std::filesystem::path(*root) / "System32" / name;
+}
+
+// What the tool printed, when it ran to an end with status 0.
+std::optional<std::string> printed(std::string_view tool, std::vector<std::string> args) {
+    auto program = system_tool(tool);
+    if (!program) return std::nullopt;
+    process::spawn_options o;
+    o.program = *program;
+    o.args = std::move(args);
+    o.in = process::stdio::null;
+    o.err = process::stdio::null;
+    process::bounds limits;
+    limits.hard = std::chrono::seconds{10};
+    auto r = process::run(std::move(o), limits);
+    if (!r || r->timed_out || !r->status.success()) return std::nullopt;
+    return std::move(r->out);
+}
+
+}  // namespace
+
+// The token's integrity level as `whoami /groups' lists it: High (S-1-16-12288)
+// or System (S-1-16-16384) is the administrator's token. A SID, not a group's
+// name, so the answer does not depend on the system's language.
+bool elevated() {
+    if (host() != platform::windows) return false;
+    static const bool answer = [] {
+        const auto text = printed("whoami", {"/groups"});
+        return text && (text->find("S-1-16-12288") != std::string::npos
+                        || text->find("S-1-16-16384") != std::string::npos);
+    }();
+    return answer;
+}
+
+// `fsutil devdrv query <volume>' names a developer volume as one; its answer is
+// read only when the tool states one of its two sentences, and is otherwise
+// not known (a system in another language, or a user the tool refuses).
+std::optional<bool> on_dev_drive(const std::filesystem::path& directory) {
+    if (host() != platform::windows) return std::nullopt;
+    const auto text = directory.generic_string();
+    if (text.size() < 2 || text[1] != ':') return std::nullopt;
+    const auto said = printed("fsutil", {"devdrv", "query", text.substr(0, 2)});
+    if (!said) return std::nullopt;
+    if (said->find("not a developer volume") != std::string::npos) return false;
+    if (said->find("developer volume") != std::string::npos) return true;
+    return std::nullopt;
+}
+
+}  // namespace mcpplibs::os::windows