Merge branch 'master' into feat/issue-268-handle-cache

冲突：runtime/src/runtime_internal.h（master 的 clang-format 重排 + 本 PR 新增
kvspaceRef_t/三个 weak 声明/ref 表字段/kvlangKvInvalidateFrame 声明），按
master 风格保留两侧内容；runtime/src/kv.c 自动合并。

Co-Authored-By: Claude Code <noreply@anthropic.com>

Author: miaobyte

.github/workflows/ci.yml

@@ -1,8 +1,15 @@
 name: ci
 on: [push, pull_request, repository_dispatch]
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
+    name: test-${{ matrix.backend.name }}
+    strategy:
+      fail-fast: false
+      matrix:
+        backend:
+          - { name: shm, dsn: "shm:///tmp/kvlang_ci_shm.shm" }
+          - { name: fs,  dsn: "fs:///tmp/kvlang_ci_fs" }
     steps:
       - uses: actions/checkout@v4
       - name: 下载 ABI 依赖
@@ -15,6 +22,6 @@ jobs:
           sudo cp layout/target/release/libkvlanglayout.so /usr/lib/
           make runtime-rs
           sudo make install
-      - name: 测试
-        env: { KVSPACE: "shm:///tmp/kvlang_ci" }
+      - name: 测试 (${{ matrix.backend.name }})
+        env: { KVSPACE: "${{ matrix.backend.dsn }}" }
         run: python3 tutorial/test.py

benchmark/README.md

@@ -56,6 +56,8 @@ kvlang 是被测对象，**分别在三个 kvspace 后端上各跑一遍，占
 | `k_nucleotide` | 字符串 + 哈希表 | 逐字符 `ord` 入哈希表统计碱基频次 |
 | `iops` | 最小寻址单元往返地板价 | 单 key 读-改-写 `a=a+1`，per-op 延迟（对齐 #204，参考基线） |
 | `prime_sieve` | 计算 / 控制流密集 | 嵌套 `while` + 取模，O(n²) 内层迭代（参考基线） |
+| `matmul_compact` | **数组物理形态**（compact） | 同 `matmul` 算法，矩阵落单个 `[N,N]float64`（storetype=ARRAYND，元素连续打包），对照「每元素一个 key 的散 key map」 |
+| `quicksort_compact` | **数组物理形态**（compact） | 同 `quicksort` 算法，待排数组与显式栈都落单个 `[N]int64`，全程在 compact 数组里直接交换 |
 
 kvlang 的性能瓶颈是「PC/帧/局部全落 KV 树、每步一次往返」的架构本质（见 kvlang#194 #204 #116），
 不是某个热点函数；`iops`/`prime_sieve` 单独隔离出这条地板价，其余八例是跨语言等价算法对照。

benchmark/cases/binary_search/binary_search.kv

@@ -2,7 +2,7 @@
 // 建 arr[i]=i，对 0..N-1 逐个二分，累加命中下标；N 由 __SCALE__ 占位（勿改逻辑）
 // 期望输出（N=32 时）:
 //   bsearch: found = 32 sum = 496
-rwfunc bsearch(arr:[int64]·int64, n:int64, target:int64) -> (idx:int64) {
+rwfunc bsearch(arr:*[int64]·int64, n:int64, target:int64) -> (idx:int64) {
 	0 -> lo
 	n - 1 -> hi
 	-1 -> idx

benchmark/cases/matmul/matmul.kv

@@ -1,31 +1,30 @@
-// matrix multiplication benchmark — 稠密方阵乘（浮点运算 + 三重循环）
-// A/B 元素取 0.25 倍数（二进制精确），C 校验和 × 1e6 恒为精确整数、跨语言逐字节一致
+// matrix multiplication benchmark（compact 形式）— 同 matmul 算法，矩阵落**单个 compact XValue**
+// （`[N,N]float64`，storetype=ARRAYND，元素连续打包），而非散 key 的 `[int64]·float64` map。
+// 对比点：同一算法的两种 kv 物理形态——map 每次元素访问一次 KV 往返，compact 一次 xv·at/set。
 // 方阵阶 N 由 __SCALE__ 占位（O(N^3)，勿改逻辑）
 // 期望输出（N=6 时）:
 //   matmul: check = 82750000
 rwfunc test() -> () {
 	__SCALE__ -> n
-	A:[int64]·float64 = {}
-	B:[int64]·float64 = {}
+	A:[__SCALE__,__SCALE__]float64 = []
+	B:[__SCALE__,__SCALE__]float64 = []
 	0 -> i
 	while (i < n) {
 		0 -> j
 		while (j < n) {
-			i × n -> base
-			base + j -> idx
 			i + j -> ta
 			ta % 4 -> qa
 			float64(qa) -> qaf
 			qaf × 0.25 -> pa
 			pa + 0.25 -> av
-			av -> A·*idx
+			av -> A[i, j]
 			i × 2 -> i2
 			i2 + j -> tb
 			tb % 4 -> qb
 			float64(qb) -> qbf
 			qbf × 0.25 -> pb
 			pb + 0.25 -> bv
-			bv -> B·*idx
+			bv -> B[i, j]
 			j + 1 -> j
 		}
 		i + 1 -> i
@@ -39,12 +38,8 @@ rwfunc test() -> () {
 			0.0 -> acc
 			0 -> k
 			while (k < n) {
-				i × n -> ba
-				ba + k -> ia
-				kv·get(A, ia) -> av
-				k × n -> bb
-				bb + j -> ib
-				kv·get(B, ib) -> bv
+				A[i, k] -> av
+				B[k, j] -> bv
 				av × bv -> pr
 				acc + pr -> acc
 				k + 1 -> k

benchmark/cases/quicksort/quicksort.kv

@@ -1,63 +1,66 @@
-// quicksort benchmark — 迭代 Lomuto 分区就地排序（数组访问 + 显式栈递归）
+// quicksort benchmark（compact 形式）— 同 quicksort 算法，待排数组与显式栈都落**单个 compact
+// XValue**（`[N]int64`，storetype=ARRAYND），而非散 key 的 `[int64]·int64` map。
+// 对比点：同一算法的两种 kv 物理形态。
 // 数据由 LCG 确定生成，规模 N 由 __SCALE__ 占位，run.py 按扫描点替换（勿改逻辑）
 // 期望输出（N=64 时）:
 //   qsort: a0 = 1 amid = 52 alast = 99
 rwfunc test() -> () {
 	__SCALE__ -> n
-	arr:[int64]·int64 = {}
+	arr:[__SCALE__]int64 = []
 	1 -> seed
 	0 -> i
 	while (i < n) {
 		seed × 1103515245 -> s1
 		s1 + 12345 -> s2
 		s2 % 2147483648 -> seed
 		seed % 100 -> v
-		v -> arr·*i
+		v -> arr[i]
 		i + 1 -> i
 	}
 	t0 = time·now()
-	st_lo:[int64]·int64 = {}
-	st_hi:[int64]·int64 = {}
+	// 显式栈也用 compact：与待排数组一样落单个 ARRAYND XValue，全程只在 compact 数组里直接交换。
+	st_lo:[__SCALE__]int64 = []
+	st_hi:[__SCALE__]int64 = []
 	0 -> top
-	0 -> st_lo·*top
-	n - 1 -> st_hi·*top
+	0 -> st_lo[top]
+	n - 1 -> st_hi[top]
 	top + 1 -> top
 	while (top > 0) {
 		top - 1 -> top
-		kv·get(st_lo, top) -> lo
-		kv·get(st_hi, top) -> hi
+		st_lo[top] -> lo
+		st_hi[top] -> hi
 		if (lo < hi) {
-			kv·get(arr, hi) -> pivot
+			arr[hi] -> pivot
 			lo - 1 -> ii
 			lo -> jj
 			while (jj < hi) {
-				kv·get(arr, jj) -> aj
+				arr[jj] -> aj
 				if (aj <= pivot) {
 					ii + 1 -> ii
-					kv·get(arr, ii) -> ai
-					aj -> arr·*ii
-					ai -> arr·*jj
+					arr[ii] -> ai
+					aj -> arr[ii]
+					ai -> arr[jj]
 				}
 				jj + 1 -> jj
 			}
 			ii + 1 -> pp
-			kv·get(arr, pp) -> app
-			pivot -> arr·*pp
-			app -> arr·*hi
-			lo -> st_lo·*top
-			pp - 1 -> st_hi·*top
+			arr[pp] -> app
+			pivot -> arr[pp]
+			app -> arr[hi]
+			lo -> st_lo[top]
+			pp - 1 -> st_hi[top]
 			top + 1 -> top
-			pp + 1 -> st_lo·*top
-			hi -> st_hi·*top
+			pp + 1 -> st_lo[top]
+			hi -> st_hi[top]
 			top + 1 -> top
 		}
 	}
 	t1 = time·now()
 	n ÷ 2 -> mid
 	n - 1 -> last
-	kv·get(arr, 0) -> a0
-	kv·get(arr, mid) -> am
-	kv·get(arr, last) -> al
+	arr[0] -> a0
+	arr[mid] -> am
+	arr[last] -> al
 	println("qsort: a0 =", a0, "amid =", am, "alast =", al)
 	delta = time·sub(t1, t0)
 	ns = time/duration·as_nanos(delta)

benchmark/results/results-v0.2.17-20260911T062301Z.csv

@@ -0,0 +1,31 @@
+timestamp,version,commit,cpu,case,input,samples,kvlang_shm_ns,kvlang_fs_ns,kvlang_redis_ns,python_ns,rust_ns,c_ns,python_ver,rust_ver,c_ver,native_opt,valid
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_search,N=16,3,7313124,226927819,721008200,14125,775,495,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_search,N=32,3,15726642,510049531,1665331585,24156,1348,1027,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_search,N=64,3,34739485,1156523966,3888196146,45648,2731,2070,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_trees,depth=4,3,5439068,285068576,741714334,14280,2432,5703,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_trees,depth=5,3,10102902,647583144,1486591770,22621,3120,5978,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,binary_trees,depth=6,3,20038128,1665730463,2959716628,41278,4530,9013,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,fib,n=8,3,8501530,169606104,564228105,10063,293,347,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,fib,n=9,3,14082441,274390900,897718626,11933,390,434,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,fib,n=10,3,22645702,442703420,1466602784,15005,469,639,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,hash_table,N=50,3,4883936,226509681,689478766,34328,5179,291,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,hash_table,N=100,3,9612434,542014962,1352878929,61394,8017,422,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,hash_table,N=200,3,20282647,1465888122,2696365584,112130,15274,754,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,iops,N=500,3,7517156,360301809,1522084963,23411,438,295,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,iops,N=1000,3,14693824,704939703,3028980970,45530,797,456,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,iops,N=2000,3,29213367,1410555284,6077347742,90625,1441,789,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,k_nucleotide,rep=3,3,11183984,423026404,1570778984,39344,3276,209,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,k_nucleotide,rep=5,3,21573718,716464129,2652754541,63553,4899,287,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,k_nucleotide,rep=8,3,42270280,1123691010,4239436534,98025,7474,445,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,matmul,N=4,3,2494216,136715770,483656644,20395,368,210,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,matmul,N=6,3,7083273,402128302,1440631693,53986,459,348,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,matmul,N=8,3,15423851,888971709,3230714695,115948,741,547,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,nqueens,N=4,3,5590964,165772756,367770434,14053,318,272,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,nqueens,N=5,3,16894989,519718568,1152138069,23330,561,542,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,nqueens,N=6,3,48264056,1499696803,3372465913,50155,1535,1456,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,prime_sieve,N=50,3,12394540,508802480,2110607702,42322,15134,18902,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,prime_sieve,N=75,3,23866546,1034530878,4335316972,61660,17961,20724,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,prime_sieve,N=100,3,34597505,1506271857,6433111590,82541,21256,23008,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,quicksort,"N=32,seed=1",3,7643381,398343054,1424143169,18634,1143,1014,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,quicksort,"N=64,seed=1",3,16954506,875656570,3313404372,33625,2424,2231,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True
+2026-09-11T06:23:01Z,v0.2.17,7cabf55,Intel(R) Xeon(R) Platinum 8336C CPU @ 2.30GHz,quicksort,"N=128,seed=1",3,36533670,1926614467,7222936156,65903,5071,4766,3.12.7,1.97.1,13.3.0,gcc -O1 / rustc opt-level=1 / cpython,True

benchmark/run.py

@@ -61,6 +61,10 @@
     "hash_table":    [50, 100, 200],
     "matmul":        [4, 6, 8],
     "k_nucleotide":  [3, 5, 8],
+    # 同一算法的 compact 形态：数组落单个 ARRAYND XValue（`[N]T`），而非每元素一个 key 的散 key map。
+    # 与 matmul / quicksort 同规模、同基线（native 三份与原 case 算法完全一致，仅输出标签不同）。
+    "matmul_compact":    [4, 6, 8],
+    "quicksort_compact": [32, 64, 128],
 }
 SCALE_ENV = "BENCH_SCALE"   # python/rust/c 从此环境变量读规模
 SCALE_TOKEN = "__SCALE__"   # kvlang 源码里的规模占位符

deps.json

@@ -1,7 +1,7 @@
 {
-  "kvspace": "v0.2.16",
-  "kvspace-c": "v0.2.16",
-  "kvspace-durable": "v0.2.16",
+  "kvspace": "v0.2.17",
+  "kvspace-c": "v0.2.17",
+  "kvspace-durable": "v0.2.17",
   "blockmalloc": "v0.1.4",
   "slotsboxmalloc": "v0.1.5"
 }