0.23.0 --- an image placed at its base (kal_exec_alloc_at, KAL_EXEC_PROP_PLACE, the placement note, clause 12.4 version 1.1); a name with every link followed (kal_fs_resolved_name, KAL_FS_PROP_RESOLVED_NAME)

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

Author: Sunrisepeak

.agents/docs/2026-11-03-openkal-0.23-design.md

@@ -0,0 +1,81 @@
+# openkal 0.23：映像在其基址上放置
+
+2026-11-03。状态：**实施所依据的方案**。规范对照基于 `SPEC.md` 0.22，结果为 0.23.0。
+来源：mcpp 生态设计 2026-11-02 part 3 §16.8、§17.6；mcppls-clangd #16 的 warm-prime（Linux x64、macOS arm64）。
+
+---
+
+## 1. 要解决的问题
+
+warm-prime 的冷阶段启动 176 个 worker。CI 的 Linux x64 上映像的处理器时间为原生的 1.27 倍、缺页为 1.42 倍，macOS arm64
+的缺页为 2.32 倍；本机（Linux x64）为 1.09 倍。差距按 worker 平均分摊，与模块大小无关：
+
+| # | 测量 | 结果 |
+| --- | --- | --- |
+| P1 | 一次启动（`--version`）的缺页 | 原生 297（非 PIE，固定地址），映像 1285 |
+| P2 | 映像的重定位 | `.rela.dyn` 3.9 MB，约 164 000 条相对重定位，落在 2 MB 的 `.data.rel.ro` 上 |
+| P3 | 打包的相对重定位（`-z pack-relative-relocs`） | 表缩为 32 KiB，缺页 1285 → 1160；可写段仍被整体复制并逐项改写 |
+| P4 | 每次多出的缺页的代价 | 本机每个 worker 约 3.5 ms，CI 的 x64 虚拟机约 24 ms |
+
+映像是位置无关的（12.2），加载器每次启动都要写入相对重定位算出的每个地址；为一个地址链接的原生程序不写这些地址，其只读
+数据是文件的页，按需缺页并预读相邻页。
+
+## 2. 增补
+
+| 接口 | 增补 | 层级 | 条文 |
+| --- | --- | --- | --- |
+| `openkal.exec` | `kal_exec_alloc_at(at, size)`、属性 `KAL_EXEC_PROP_PLACE` | 属性位 | 11 条 48、12.3 |
+| 映像格式 | 第 3 类 note（placement）：基址与各个在文件中有字节的可写段（按地址升序）按该基址算好的字节在文件中的位置；本条文版本 1.1 | 可选 note | 12.4 |
+| 加载器 | 得到基址时，只读部分（`PT_GNU_RELRO`）中没有符号重定位的粒度直接映射文件的字节，其余复制，只做引用符号的重定位 | 陈述 | 12.3 |
+| `openkal.fs` | `kal_fs_resolved_name(base, name, len, out, cap)`、属性 `KAL_FS_PROP_RESOLVED_NAME` | 卷的属性位 | 11 条 49 |
+
+`kal_exec_alloc_at` 在 `at` 处预留区域，该处已有内容或环境不允许程序选择地址时返回空指针、不预留任何东西；`at` 是
+`kal_memory_granularity` 的倍数。
+
+同一次测量（warm-prime 的已有缓存阶段，`strace -c`）中，映像发出 87 万次 `newfstatat`，原生为 35 万次 `stat` 与 10 万次
+`readlink`：映像的 `realpath` 逐个组成部分询问是否为链接（`usr`、`usr/lib`、`usr/lib/gcc`……），原生程序对打开的每个文件只问
+环境一次（Linux 的 `/proc/self/fd`，macOS 的 `F_GETPATH`）。CI 的 x64 上映像的内核态时间因此多 20%。`kal_fs_resolved_name`
+回答名字跟随全部链接后的绝对名字：Linux 以 `O_PATH` 打开后读 `/proc/self/fd/N`，macOS 以 `O_EVTONLY` 打开后取 `F_GETPATH`，
+Windows 以 `GetFinalPathNameByHandleW`；openkal-musl 的 `realpath` 先用它，卷不声明时照旧逐个询问。
+
+## 3. 方案中的决定
+
+1. **一个操作，而不是 `kal_exec_alloc` 的提示。** 加载器在写入任何东西之前就要知道是否拿到了基址：拿到时取存储的字节，拿不到
+   时按文件重定位。提示得到的地址需要再比较，比较之后的回退正是这个操作的语义，所以由操作陈述。
+2. **属性位，而不是必需。** 有的环境替程序决定每块内存的位置。Linux 用 `MAP_FIXED_NOREPLACE`（4.17 之前的内核把它当作
+   提示，结果不同则释放并拒绝），macOS 用提示并比较（`MAP_FIXED` 会替换已有内容），Windows 用 `VirtualAlloc` 在该地址预留；
+   三个实现都声明该位。Windows 不声明 `KAL_EXEC_PROP_FILE`，得到基址时复制存储的字节，省去重定位但不省去复制。
+3. **基址由映像决定，在封装时选定。** 同一映像的所有进程放在同一地址，重定位后的只读数据在各进程中相同，可以是同一文件的页。
+   基址取自映像内容的摘要，落在用户地址空间的中段（16 TiB 起，4 GiB 一档），与系统分配器自上而下的放置相距很远；一个进程中
+   多个映像各有其基址，冲突时后者照常重定位。
+4. **只存可写段，只跳过相对重定位。** 指令与只读数据本来就是文件的字节（0.21）；引用符号的重定位指向加载器绑定的实现入口，
+   因加载器而异，仍在加载时完成。只读部分（`PT_GNU_RELRO`）中没有这类重定位的粒度不再被写，可以映射文件；其余粒度复制后
+   改写。
+5. **格式版本 1.1。** 新 note 是可选的；1.0 的加载器不读它，照常重定位，行为不变。一个要求新加载器才能运行的映像不由此产生。
+6. **先放置，后签名。** 签名覆盖整个文件（12.4 第 2 类），存储的段也在其中；`okld place` 拒绝已签名的映像。基址取自 ELF
+   所描述的字节（placement 描述符读作零），同一映像无论放置几次都得到同一基址与同一字节。
+
+## 4. 版本组
+
+| 包 | 版本 | 内容 |
+| --- | --- | --- |
+| openkal | 0.23.0 | 本文 |
+| openkal-linux | 0.24.0 | `kal_exec_alloc_at` |
+| openkal-macos | 0.21.0 | `kal_exec_alloc_at` |
+| openkal-windows | 0.19.0 | `kal_exec_alloc_at` |
+| openkal-emscripten | 0.12.0 | 依 0.23 编写，无其他改动 |
+| openkal-image | 0.4.0 | `okld place`（封装步骤）、placement note、加载器按 12.3 放置 |
+| openkal-musl | 0.27.0 | 加载器为 openkal-ld 0.4.0（另含 0.22 的 `/dev/null`） |
+| openkal-llvm-runtime | 0.18.0 | 建在 openkal-musl 0.27.0 上 |
+| openkal-platform | 0.23.0 | 版本组；封装步骤增加 `okld place`，链接打包相对重定位 |
+| mcpplibs.os | 0.2.8 | openkal 0.23 的实现 |
+
+## 5. 验证
+
+- 一致性套件：未对齐的地址被拒绝；已有区域的地址被拒绝且原区域不变；刚释放的地址被重新预留并可写；未声明该位的实现拒绝
+  所有请求。openkal-linux 0.24 的本地一致性：328 项全部成立。
+- openkal-image：同一映像在基址上、在任意地址上（`OKRUN_PLACE=0`）与未放置时观察到的内存相同；在基址上不做相对重定位；
+  封装后的映像通过 `okld check`，存储段的一个字节被改动时被拒绝；重复放置不改变字节；openkal-image 0.3.1 的 okrun 照常运行
+  0.4.0 封装的映像。本机（Linux x64）clangd 映像一次启动（`--version`）的缺页：在基址上 606，在任意地址上 1 047；
+  `PT_GNU_RELRO` 的 2 MB 中除首尾两个 64 KiB 外都是文件的页。
+- warm-prime：CI 的 Linux x64、arm64、macOS arm64 上映像对原生的冷阶段处理器时间与缺页。

README.md

@@ -77,16 +77,16 @@ conditional on the target.
 
 ```toml
 [dependencies]
-openkal = "0.22.0"
+openkal = "0.23.0"
 
 [target.'cfg(os = "linux")'.dependencies]
-openkal-linux = "0.23.0"
+openkal-linux = "0.24.0"
 
 [target.'cfg(os = "macos")'.dependencies]
-openkal-macos = "0.20.0"
+openkal-macos = "0.21.0"
 
 [target.'cfg(windows)'.dependencies]
-openkal-windows = "0.18.0"
+openkal-windows = "0.19.0"
 ```
 
 The program imports the interface and names no implementation.

SPEC.md

@@ -1,4 +1,4 @@
-# openkal Specification, version 0.22
+# openkal Specification, version 0.23
 
 ## 1. Scope
 
@@ -92,7 +92,7 @@ provides an interface in whole or not at all.
 
 Version 0.15 specifies the core and optional interfaces, version 0.18 adds
 `openkal.map` (clause 11, entry 40), and version 0.20 adds `openkal.region`,
-`openkal.prof` and `openkal.debug` (entries 44 and 45); versions 0.21 and 0.22 add no interface. The reserved row is not specified, and its
+`openkal.prof` and `openkal.debug` (entries 44 and 45); versions 0.21 to 0.23 add no interface. The reserved row is not specified, and its
 name shall not be used for other purposes.
 
 The S, L and X columns state which boundaries an interface's declarations can
@@ -1920,6 +1920,35 @@ The following are recorded so that they are not mistaken for oversights.
     writes the device itself is served by its C library without the
     environment. It is a position and not required, because an environment
     that starts no programs has nothing to give it to.
+48. **An image placed at its base.** **Specified in 0.23**, as
+    `kal_exec_alloc_at` and `KAL_EXEC_PROP_PLACE` in `openkal.exec`
+    (`exec.h`), with the placement note (clause 12.4, version 1.1) and its use
+    by a loader (clause 12.3). An image is position-independent (12.2), so a
+    loader wrote, on every start, each address its relative relocations
+    compute: measured for a language server's image, 164 000 relocations over
+    two mebibytes of read-only-after-relocation data, made resident in each of
+    the 176 programs a build of its modules starts --- about 900 page faults a
+    program more than the same server built for its environment at one
+    address, which on a virtual machine of a continuous-integration service
+    cost a fifth of the build's processor time. An image computed once for one
+    base and placed there is the file's pages, as such a program is. The
+    reservation at an address is an operation and not a hint to
+    `kal_exec_alloc`, because a loader that is refused must know it before it
+    writes anything; it is a position, because an environment may decide where
+    every program's memory lies; and the address is the image's, chosen when it
+    is sealed, not the environment's.
+49. **A name with every link followed.** **Specified in 0.23**, as
+    `kal_fs_resolved_name` and `KAL_FS_PROP_RESOLVED_NAME` in `openkal.fs`
+    (`fs.h`). A C library's `realpath` asked about each component of a name in
+    turn whether it is a link: measured in a language server's session run as
+    an image, half a million enquiries, where the program of its environment
+    asked the environment once for each file it opened (`/proc/self/fd` on one
+    system, `F_GETPATH` on another). Every environment that keeps links answers
+    the question for a name it has resolved, and nothing above it can compose
+    the enquiries into one. The name is absolute and in the environment's
+    spelling, as `kal_env_image` states one: a C library maps it onto its own
+    names as it maps that one. It is a position of the volume, as the other
+    operations of names are.
 
 ## 12. Images
 
@@ -2000,6 +2029,19 @@ zero, where the image's bytes are not a file's at a multiple of
 `KAL_MAP_ALIGNMENT` (an image a program carries in its own bytes), and where a
 relocation writes the segment.
 
+Where the implementation sets `KAL_EXEC_PROP_PLACE` (version 0.23) and the image
+carries a placement note (12.4), a loader asks for the image's span at the
+note's base (`kal_exec_alloc_at`). Given it, the loader takes each stored
+segment's bytes instead of the file's and applies only the relocations that
+name a symbol: a part of a stored segment that is read-only after relocation
+(the image's `PT_GNU_RELRO`) and that no such relocation writes is the file's
+bytes (`kal_exec_map_part`) where `KAL_EXEC_PROP_FILE` is set, and the rest is
+copied. Refused, or where the position is zero, the loader reserves the span
+anywhere and relocates the file's segments as before. The program observes the
+same memory either way; what differs is that a program placed at its base writes
+no address its relative relocations compute, as a program of its environment
+linked for one address does not.
+
 Where an environment's own convention differs from the image's --- on x86-64,
 one environment passes arguments in other registers --- the loader presents each
 entry in the image's convention, and a function the image passes to the
@@ -2030,8 +2072,11 @@ An image carries notes whose owner is `OPENKAL`, in a section `.note.openkal`:
 | --- | --- |
 | 1, requirements | `kal_u32` major and `kal_u32` minor version of this clause (1 and 0), then a `kal_u64` of `KAL_IFACE_*` positions: **the interfaces the image requires**, derived from the names it imports other than weakly |
 | 2, signature | 32 bytes of an Ed25519 public key, then 64 bytes of the signature, over the whole file with these 96 bytes read as zero |
+| 3, placement | a `kal_u64` base, a multiple of 65536; a `kal_u32` count and a `kal_u32` zero; then, for each of `count` writable loadable segments that have bytes in the file, in ascending order of address, three `kal_u64`: the segment's address in the image, the file offset of its stored bytes, congruent to that address modulo 65536, and their length, the segment's size in the file. The stored bytes are the segment's file bytes with each relative relocation, and each of the packed relative form, applied for `base`; a relocation that names a symbol is not applied. Version 1.1 of this clause |
 
-The first is required and the second is not. A loader compares the required interfaces with `kal_interfaces` and
+The first is required and the others are not. A count of zero states no
+placement, and a loader reads a placement note only after the requirements note
+states version 1.1 or higher. A loader compares the required interfaces with `kal_interfaces` and
 refuses to load an image that requires one the implementation does not provide,
 naming the interface. That is clause 6.1 in this arrangement: the loader binds
 at load what a linker binds at link, so it reports at load what a linker reports

SURFACE.txt

@@ -1,4 +1,4 @@
-# The C surface of openkal 0.22.0, one name per line.
+# The C surface of openkal 0.23.0, one name per line.
 #
 # This file is normative and is the single source consulted by clause 9. A
 # conforming implementation exports the names of the interfaces it provides
@@ -74,6 +74,7 @@ kal_fs_read_at
 kal_fs_remove
 kal_fs_rename
 kal_fs_rename_flags
+kal_fs_resolved_name
 kal_fs_seek
 kal_fs_set_executable_at
 kal_fs_set_modified
@@ -115,6 +116,7 @@ kal_task_wake
 kal_task_yield
 # openkal.exec
 kal_exec_alloc
+kal_exec_alloc_at
 kal_exec_free
 kal_exec_granularity
 kal_exec_map_part

conformance/src/declarations.c

@@ -45,6 +45,7 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_env_var_at);
     (void)sizeof(&kal_env_var_count);
     (void)sizeof(&kal_exec_alloc);
+    (void)sizeof(&kal_exec_alloc_at);
     (void)sizeof(&kal_exec_free);
     (void)sizeof(&kal_exec_granularity);
     (void)sizeof(&kal_exec_map_part);
@@ -60,6 +61,7 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_fs_info);
     (void)sizeof(&kal_fs_link_create);
     (void)sizeof(&kal_fs_link_read);
+    (void)sizeof(&kal_fs_resolved_name);
     (void)sizeof(&kal_fs_list_begin);
     (void)sizeof(&kal_fs_list_next);
     (void)sizeof(&kal_fs_lock);

conformance/src/macros_reach.cpp

@@ -45,5 +45,7 @@ static_assert(kal::macros::KAL_SPAWN_NULL_IN_M == 4u);
 static_assert(kal::macros::KAL_SPAWN_NULL_OUT_M == 8u);
 static_assert(kal::macros::KAL_SPAWN_NULL_ERR_M == 16u);
 static_assert(kal::macros::KAL_PROCESS_PROP_NULL_STREAMS_M == 8192u);
+static_assert(kal::macros::KAL_EXEC_PROP_PLACE_M == 8u);
+static_assert(kal::macros::KAL_FS_PROP_RESOLVED_NAME_M == 2048u);
 
 }  // namespace

conformance/src/sections/exec.cpp

@@ -2,6 +2,7 @@ module okc.exec;
 
 import openkal.types;
 import openkal.exec;
+import openkal.memory;
 import openkal.macros;
 import openkal.stream;
 import okc.report;
@@ -70,6 +71,43 @@ bool make_file() {
     return ok;
 }
 
+// A region at the address asked for (0.23): an address just released is given
+// again, and one a region holds is refused with nothing reserved; where the
+// position is zero, every request is refused. An address that is not a multiple
+// of the reservation quantum is refused either way.
+void at_an_address() {
+    const kal_uintptr q = kal_memory_granularity();
+    const kal_uintptr size = 4 * q;
+    void* r = kal_exec_alloc(size);
+    if (r == nullptr) {
+        unobserved(kind::behaviour, "a region is reserved at the address asked for",
+                   "no region could be reserved to find a free address");
+        return;
+    }
+    auto* bytes = static_cast<unsigned char*>(r);
+    observe(kind::behaviour, kal_exec_alloc_at(bytes + 1, size) == nullptr,
+            "an address that is not a multiple of the reservation quantum is refused");
+    if (!kal::exec::has(kal::exec::place)) {
+        kal_exec_free(r, size);
+        observe(kind::behaviour, kal_exec_alloc_at(r, size) == nullptr,
+                "a region at an address is refused where the implementation does not claim it");
+        return;
+    }
+    observe(kind::behaviour, kal_exec_alloc_at(r, size) == nullptr,
+            "an address a region holds is refused");
+    bytes[0] = 5;
+    observe(kind::behaviour, bytes[0] == 5, "and the region there is as it was");
+    kal_exec_free(r, size);
+    void* again = kal_exec_alloc_at(r, size);
+    observe(kind::behaviour, again == r, "a region is reserved at an address just released");
+    if (again == r) {
+        auto* b = static_cast<unsigned char*>(again);
+        b[size - 1] = 6;
+        observe(kind::behaviour, b[size - 1] == 6, "and is written as a region kal_exec_alloc returned");
+        kal_exec_free(again, size);
+    }
+}
+
 void from_a_file() {
     const kal_uintptr g = kal_exec_granularity();
     if (g == 0 || kAlign % g != 0) {
@@ -154,7 +192,7 @@ void run() {
 
     claim("kal_exec_props()", kal_exec_props());
     observe(kind::abi,
-            (kal_exec_props() & ~(kal::exec::republish | kal::exec::available | kal::exec::file).bits) == 0,
+            (kal_exec_props() & ~(kal::exec::republish | kal::exec::available | kal::exec::file | kal::exec::place).bits) == 0,
             "no position the specification has not assigned is reported");
 
     // WHETHER THE INTERFACE CAN BE EXERCISED BY THIS ARTIFACT IS READ BEFORE
@@ -286,6 +324,8 @@ void run() {
     }
 
     claim("KAL_EXEC_PROP_FILE", kal_exec_props() & kal::exec::file.bits);
+    claim("KAL_EXEC_PROP_PLACE", kal_exec_props() & kal::exec::place.bits);
+    at_an_address();
 #if defined(MCPP_FEATURE_FS)
     from_a_file();
 #else