spec(runtime): C runtime 唯一核心 + runtime-rs 定位

stdlib/kvlang/spec/05-runtime语义/01-执行模型.kv

@@ -2,7 +2,9 @@
 lib kvlang/spec/runtime语义/执行模型 {
 	r####"# 执行模型
 
-runtime 是 kvlang 的**动态语义**阶段：对已由 layout 布进 kvspace 的指令做**纯解释执行**。runtime 不编译、不优化、不重排；它只按 PC 逐条取指、解码、执行。存在两套等价实现——C runtime（`kvlang/runtime/`，纯 C + `extern "C"`）与 Rust runtime（`kvlang/runtime-rs/`，二进制名 `kvlang`）——二者必须表现相同的动态语义（差异见 [[cruntime与后端abi]]）。
+runtime 是 kvlang 的**动态语义**阶段：对已由 layout 布进 kvspace 的指令做**纯解释执行**。runtime 不编译、不优化、不重排；它只按 PC 逐条取指、解码、执行。
+
+runtime 的核心**只有一套**：**C runtime（`kvlang/runtime/`，纯 C + `extern "C"`）是唯一的 runtime 核心与标准实现**——动态语义以它为准。其余 runtime 一律是**扩展运行时**：嵌入 C runtime 核心、套用其取指-解码-执行、native 派发与正典 codec，只在其上追加己方 opcode 的解释，绝不另起一套核心或编解码器（见 [[rwirext扩展]]、[[cruntime与后端abi]]）。Rust runtime（`kvlang/runtime-rs/`，二进制名 `kvlang`）即这一架构的**参考实现**——它是 rwirext 宿主，而非第二套等价核心；未来的 **deepx-gpu-compute（GPU 算子融合计算引擎）与之同架构**：同样嵌入 C runtime 核心，只把 tensor 融合算子作为己方 rwir 追加。扩展运行时**必须**与 C runtime 核心表现相同的核心动态语义。
 
 ## 状态皆在 kvspace
 

stdlib/kvlang/spec/05-runtime语义/04-函数调用与内建.kv

@@ -26,7 +26,7 @@ lib kvlang/spec/runtime语义/函数调用与内建 {
 
 ## native builtin 判定
 
-`kvlangBuiltinIsNative(opcode)`（`runtime/src/builtin.c`）先剥数字类型前缀（`int64·add` / `float32·add` … 经 `strip_num_kind` 归并到同一 `add`，按操作数 kind 归约），再在**静态注册表**线性查表。命中即为 native。native 判定**先于** `/lib` 查表，故 native opcode 不会被当须经 def rwir 路由的 rwir 或用户函数。
+`kvlangBuiltinIsNative(opcode)`（`runtime/src/builtin.c`）先剥数字类型前缀（`int64·add` / `float32·add` … 经 `strip_num_kind` 归并到同一 `add`，按操作数 kind 归约），再在**静态注册表**线性查表。命中即为 native。native 判定**先于** `/lib` 查表，故 native opcode 不会被当须经 def rwir 路由的 rwir 或用户函数。此静态注册表即**核心 runtime-c 的 myrwircaps**（见 [[rwirext扩展]]）——核心能就地跑的 opcode 全在这张表里。
 
 ## native builtin 全集（权威）
 

stdlib/kvlang/spec/05-runtime语义/06-rwirext扩展.kv

@@ -6,13 +6,23 @@ kvlang 是**小核心 + 扩展主导**语言。中央 runtime 只实现执行核
 
 ## 扩展运行时模型
 
-**扩展运行时 = 只解析己方 opcode 的迷你执行器**：从中央 runtime 拿到 PC，连续执行己方 rwir，直到遇到非己方指令，把最终 PC 交还中央 runtime。
+**扩展运行时 = 只解析 myrwircaps 内 opcode 的迷你执行器**：从中央 runtime 拿到 PC，连续执行 myrwircaps 内的 rwir，直到遇到不在 myrwircaps 内的指令，把最终 PC 交还中央 runtime。
+
+### 关键术语：myrwircaps（本 runtime 的 rwir 能力表）
+
+**myrwircaps 是每个 runtime 都必须定义的一张 map/table**——登记本 runtime **能就地解释的全部 opcode**，映射 `opcode → 就地处理器`。它是 kvlang runtime 分层与派发的核心术语：一个 runtime「能跑什么」由且仅由它的 myrwircaps 界定。
+
+- **每个 runtime 必须声明自己的 myrwircaps**。核心 runtime-c 的 myrwircaps 就是其 **native 静态注册表**（数组 + 线性查找，见 [[cruntime与后端abi]]），登记 native builtin（+ 控制流 `call`/`return`/`br`/`goto` + `=` 拷贝，见 [[函数调用与内建]]）。
+- **每个扩展运行时各自定义一张 myrwircaps**，登记其自带的 rwir opcode。例：runtime-rs 为 `term`/`json`/`http`/`kvlanglayout`/`networld` 等（见 [[rwirext扩展_b]] 就地集合）；未来 deepx-gpu-compute 为 tensor 融合算子。
+- **派发判据**：`opcode ∈ 本 runtime.myrwircaps` → 查表取处理器**就地执行**；否则该 rwir 须经 def rwir 路由，**移交**给以它为 myrwircaps 的另一扩展（跨进程 handoff/watch，或嵌入式交回宿主，见 [[rwirext扩展_b]]、[[cruntime与后端abi_续]]）。实现里 `rwir::is_inproc(op)` 即「`op ∈ myrwircaps`」的查表判定。
+
+myrwircaps **只关乎执行位置**（哪张表登记了它、由谁就地跑），不改变 rwir 的动态语义——同一 rwir 无论落进哪个 runtime 的 myrwircaps，行为必须一致。
 
 核心公理（normative）：
 
 1. **rwir 自描述**：opcode + 读/写参已含执行所需全部信息。
 2. **注册即签名**：扩展把 `/lib/<opcode>`（kind=`def rwir`，主槽 body=[nr][nw][dynamic]，各参数类型在签名行 `[0,x]` 各槽）写进 kvspace 即完成声明——无 `/sys/`、无中心目录。
-3. **批量执行**：扩展连续执行己方 rwir 到非己方指令，把最终 PC 写回 vthread。
+3. **批量执行**：扩展连续执行 myrwircaps 内的 rwir 到不在 myrwircaps 内的指令，把最终 PC 写回 vthread。
 4. **被动消费**：跨进程扩展只监控己方 `/lib/<opcode>/vids` 队列。
 
 ## 注册与发现

stdlib/kvlang/spec/05-runtime语义/07-rwirext扩展-b.kv

@@ -13,14 +13,14 @@ lib kvlang/spec/runtime语义/rwirext扩展_b {
 第一个 rwir 的 `vids` 是真实 strkeymap；后续同 opcode 的 `vids` 是 `Ptr` 指向第一个（共享同一队列）。时序：
 
 1. 中央 runtime `isothersrwir` 命中 → `handoff_external_rwir`：`Set /lib/<op>/vids/<vtid>=pc`。
-2. 扩展发现队列中的 vtid，`RunSeq(pc)`：从 PC 起逐条解码，只要 opcode ∈ 己方集合就执行，遇第一条非己方指令即停（**顺序执行，非并行 batch**）；写回最终 PC，删 `vids` 项。
+2. 扩展发现队列中的 vtid，`RunSeq(pc)`：从 PC 起逐条解码，只要 `opcode ∈ 本扩展.myrwircaps` 就执行，遇第一条不在 myrwircaps 内的指令即停（**顺序执行，非并行 batch**）；写回最终 PC，删 `vids` 项。
 3. 中央 runtime `Watch` 直到 vtid 从队列消失（30s 超时），继续。
 
 中央 runtime **不推进 PC**——扩展批量执行后已写回最终 PC，中央直接读新 PC 续跑。
 
 ## 就地扩展（同进程）
 
-同进程扩展在驱动循环里就地派发（Rust `run_vid`：`rwir::is_inproc(op)` 命中 → `rwir::dispatch`），无 handoff、无 watch。当前就地集合（`runtime-rs`）：
+同进程扩展在驱动循环里就地派发（Rust `run_vid`：`rwir::is_inproc(op)`——即 `op ∈ myrwircaps`——命中 → `rwir::dispatch`），无 handoff、无 watch。runtime-rs 的 myrwircaps（就地集合）当前登记：
 
 ```
 term      print / println / cerr / input

stdlib/kvlang/spec/05-runtime语义/09-cruntime与后端abi.kv

@@ -14,6 +14,11 @@ lib kvlang/spec/runtime语义/cruntime与后端abi {
 2. **值语义与编解码**：TLV / kindexpr 的**唯一编解码器**在 kvspace 正典 codec（`kvspaceTlvEncode` / `kvspaceDecodeHead` / `kvspaceNewPtr`/`NewChar`/`NewBool`/`NewInt64`/`NewFloat64`）；runtime-c 的 `xvalue.c` 只是其薄封装。kindexpr 串是类型的唯一真相，怎么拼、怎么解，只此一处。
 3. **指令解码与签名校验**：`rwir.c:RwirDecode`（稠密探查、遇空即停）、`/lib/<op>` 签名的读写码规范、`KindexprValid`/`KindexprMatch` 类型判定。
 
+**扩展运行时套用核心，不复刻**：runtime-c 把上述三件能力经嵌入式 C ABI（下节 `kvlang_runtime.h` + `kvlang_rwirext.h`）对外开放。扩展运行时**嵌入**这套核心、复用其执行循环、native 派发与正典 codec，只**自行解释己方 opcode**——不得另起执行核心、不得另写编解码器、不得复刻 native 算子。据此：
+
+- **runtime-rs 是扩展运行时的参考实现**，不是第二套等价核心。它作为 rwirext 宿主，套用 runtime-c 核心，在自己的 **myrwircaps**（见 [[rwirext扩展]]）里登记 print/fs/http/networld/vthread 等「OS 工具箱」rwir。其对 head/kindexpr 的读写**必须**走正典 codec，不得自持一份编解码。
+- **未来的 deepx-gpu-compute（GPU 算子融合计算引擎）同架构**：同样嵌入 runtime-c 核心，只在其 **myrwircaps** 里登记 tensor 融合算子——算子融合发生在扩展侧（见 [[rwirext扩展]]），核心的解释语义不变。
+
 ## C runtime 结构
 
 `kvlang/runtime/` 是通用嵌入式执行器（纯 C + `extern "C"`），可嵌入 rwirext 项目（op-gpu、agent、livebyte）。两组对外 C ABI：

stdlib/kvlang/spec/05-runtime语义/10-cruntime与后端abi-续.kv

@@ -12,11 +12,11 @@ lib kvlang/spec/runtime语义/cruntime与后端abi_续 {
 
 `conn(dsn)` 按 scheme（`shm://` / `redis://` / `fs://`）选后端，DSN 是唯一的后端区分。三后端**语义必须完全一致**：一致性判据是 `tutorial/` 全量三后端逐字节相同输出（见导言卷）。后端存储布局差异（如 fs 把 `·` 编码为 `·/` 嵌套目录）经对称编解码还原，**不是**语义差异。
 
-## C runtime 与 Rust runtime 一致性
+## 核心与扩展宿主的一致性（runtime-c ↔ runtime-rs）
 
-两套 runtime 必须表现相同动态语义，但**执行位置策略**允许不同：
+runtime-c 是唯一核心；runtime-rs 是套用该核心的扩展宿主（见 [[执行模型]]、[[cruntime与后端abi]]）。因套用同一核心，二者的核心动态语义**天然一致**、不存在两套需人工对齐的核心；差异**仅限**须经 def rwir 路由的 rwir 的**执行位置策略**，且对 kvlang 程序不可观测：
 
-- **C runtime**：须经 def rwir 路由的 rwir（不在本 runtime myrwircaps 内的 rwir）一律经 `handoff_external_rwir`（Set `/lib/<op>/vids/<vtid>` + Watch 30s 超时）移交，供独立进程扩展消费；嵌入式模式（`KVMODE_RETURN`）经 `out_pc` 把控制交回同进程扩展。
+- **C runtime**：须经 def rwir 路由的 rwir（不在本 runtime myrwircaps 内的 rwir，见 [[rwirext扩展]]）一律经 `handoff_external_rwir`（Set `/lib/<op>/vids/<vtid>` + Watch 30s 超时）移交，供独立进程扩展消费；嵌入式模式（`KVMODE_RETURN`）经 `out_pc` 把控制交回同进程扩展。
 - **Rust runtime**：`is_inproc(op)` 命中的 rwir 在驱动循环里就地 `dispatch`（无 handoff、无 watch）；非就地 rwir 经 `kvlang_rwirextHandoff` 移交独立进程扩展或委托宿主 `ext` 处理器。
 
 二者对 native builtin、控制流、`=` 拷贝、值语义的处理**必须**一致；差异仅限须经 def rwir 路由的 rwir 的**就地 vs 移交**这一执行位置维度，且对 kvlang 程序不可观测（同一 tutorial 三后端两 runtime 输出一致）。