spec: 写侧落盘时机入条款；tutorial/04-ndarray 散列形态读数改用 kvspace·listlen

stdlib/kvlang/spec/02-kvspace模型/04-CABI.kv

@@ -38,6 +38,14 @@ camelCase）——kvspace 层前缀 `kvspace`（`kvspaceGet` / `kvspaceWriteInPl
 `kvspaceDelTree` 对**最终组件**不解析 link——写/删 Ptr 键只作用该键本体，不重定向到 target
 （`Del`/`DelTree` 为 POSIX rm 式：删指针本身，不删被指向者）。解引用由 runtime 显式 `*` 掌控（见
 [[ptr]]）。否则「写实参地址 Ptr 到帧槽」会被重定向到 target，导致丢参 / 写坏被指向的值。
+
+**写侧落盘时机（normative）**：`kvspaceWriteInPlace` / `kvspaceWriteNewPlace` 返回 body 偏移指针
+给调用方**在返回后**填，故本笔写不可能在返回前落盘——写在下一次 `kvspace*` 调用（读也算：每个 op
+开头先落盘上一笔）或 `kvspaceClose` 时落盘；前者失败以返回码 + err 报出，后者失败写 stderr。
+进程正常退出（`exit` / main 返回）时，前端（dispatch）对所有未 `Close` 句柄兜底关闭即落盘：
+**漏调 Close 不丢数据，真丢也绝不静默**。shm 后端写即落盘（body 指针即最终位置），两后端在
+「下一次调用前可见」上一致。
+
 ## kvspace C ABI 导出符号（快照）
 
 权威来源是**构建产物**——`nm -D --defined-only /usr/lib/kvspace/libkvspace.so | grep '^kvspace'`（前端

tutorial/04-ndarray/array_append.kv

@@ -1,12 +1,12 @@
 // array_append: 向数组追加元素
 // 规范依据: 02-kvspace模型/07-数组两种物理形态 —— array·append 作用于 compact 时
 //           先自动 scatter，即 compact 数组必须能直接 append
-// 语义: compact [1,2,3] 追加 4 后应有 4 个元素
+// 语义: compact [1,2,3] 追加 4 后应有 4 个元素（散列数组的元素数用 kvspace·listlen 读）
 // 期望输出:
 //   4
 rwfunc test() -> () {
 	a:[]int64 = [1, 2, 3]
 	array·append(a, 4) -> a
-	ndarray·numel(a) -> n
+	kvspace·listlen(a) -> n
 	println(n)
 }

tutorial/04-ndarray/array_append_sparse.kv

@@ -0,0 +1,14 @@
+// array_append_sparse: 散列数组的 append 坐标由 memindex 决定，不得假设坐标键连续
+// 规范依据: 03-类型系统/11-stringkeymap形态、05-runtime语义/03-成员访问 ——
+//           memindex 是成员集合的唯一权威，遍历/追加必须据它枚举
+// 语义: 散列 {[0],[1],[2],[5]} 追加 7，应落 [6]（最大坐标 5 + 1），不得落 [3]
+// 期望输出:
+//   7
+rwfunc test() -> () {
+	a:[]int64 = [1, 2, 3]
+	b = array·scatter(a)
+	b·[5] = 9
+	array·append(b, 7) -> b
+	b·[6] -> v
+	println(v)
+}

tutorial/04-ndarray/array_slice.kv

@@ -1,12 +1,12 @@
 // array_slice: 数组切片 [lo,hi)（原地语义：写槽即源）
 // 规范依据: 02-kvspace模型/07-数组两种物理形态 —— array·slice 作用于 compact 时
 //           先自动 scatter，即 compact 数组必须能直接 slice
-// 语义: compact [1,2,3,4,5] 取 [1:3) 后应有 2 个元素
+// 语义: compact [1,2,3,4,5] 取 [1:3) 后应有 2 个元素（散列元素数用 kvspace·listlen 读）
 // 期望输出:
 //   2
 rwfunc test() -> () {
 	a:[]int64 = [1, 2, 3, 4, 5]
 	array·slice(a, 1, 3) -> a
-	ndarray·numel(a) -> n
+	kvspace·listlen(a) -> n
 	println(n)
 }

tutorial/04-ndarray/ndarray_numel_scattered.kv

@@ -0,0 +1,13 @@
+// ndarray_numel_scattered: numel 对 stringkeymap（散列数组）读成员数
+// 规范依据: 03-类型系统/13-ndarray元数据算子 —— "ndarray·numel(a)：元素总数
+//           （compact 读 head array_len；stringkeymap 读成员数）"，且卷首声明三算子
+//           "统一观测数组形状，对两形态均适用"（同卷 dim/shape 对散列形态同样被拒）
+// 语义: 散列数组 b 有 3 个成员 → numel = 3
+// 期望输出:
+//   3
+rwfunc test() -> () {
+	a:[]int64 = [1, 2, 3]
+	b = array·scatter(a)
+	ndarray·numel(b) -> n
+	println(n)
+}