✨ feat: 灵台引擎五神齐备与 Go/Rust 官方绑定（WP-15）

- C++ 新增四模块（modules.cpp，19 个导出符号全部 hj_*）：小周天 hj_stream：流会话（sequence/delta_index 单调）与 content.block.delta envelope 确定性编码（重放字节一致）烛照 hj_policy：URL 协议白名单（拒 file/javascript/data）、路径授权根与 .. 段拒绝、幂等键非空≤128、四维决策表（autonomy×risk→allow/ask/deny，非法输入 deny fail-closed）洛书 hj_plan：预算核算（达限/负数拒绝）河图 hj_recall：确定性重排（词频×稳定排序，canonical JSON 输出；非法输入 PARSE_FAILED） - doctest 22 用例 20135 断言全绿（含每模块 golden 与确定性双跑） - Go 绑定（cgo 自包含编译引擎源码）：Engine RAII/TransformMarkdown/ValidateURL/ValidatePath/Decide/CheckBudget/RecallRerank；go test 3 用例通过（transform/rerank golden 与 C++ 字节一致） - Rust 绑定（bindgen 生成 + 安全包装）：Engine RAII（Drop 释放）、Error 枚举映射全部 HjStatus、Send/Sync（HjEngine 线程安全）；cargo test 3 用例通过（同 golden） - 三端（C++/Go/Rust）与 Python golden 一致：同一 markdown 输入在四端输出字节相同（跨端一致性首次全语言验证）
2026-09-12 13:54:12 +08:00
1 parent 99a7789432
commit a39cec5287
@@ -112,6 +112,10 @@ target/

 # C++ 引擎与契约生成产物（源码构建可再生）
 engine/build*/
+engine/bindings/go/lingtai/*.cpp
+engine/bindings/go/lingtai/*.h
+engine/bindings/go/lingtai/hunjing/
+engine/bindings/rust/target/
 engine/bindings/build/
 openapi/bundled.json
 **/*.rs.bk
@@ -17,14 +17,14 @@ endif()
 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
 set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)

-add_library(hunjing SHARED src/lingtai.cpp src/transform.cpp)
+add_library(hunjing SHARED src/lingtai.cpp src/transform.cpp src/modules.cpp)
 target_include_directories(hunjing
  PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include
  PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)

 # 单元测试（doctest，ADR-025）；单头直接引入，不用 FetchContent 拉网络
 add_executable(lingtai_tests tests/test_main.cpp tests/test_core.cpp tests/test_transform.cpp
-  src/lingtai.cpp src/transform.cpp)
+  tests/test_modules.cpp src/lingtai.cpp src/transform.cpp src/modules.cpp)
 target_include_directories(lingtai_tests PRIVATE
  ${CMAKE_CURRENT_SOURCE_DIR}/include
  ${CMAKE_CURRENT_SOURCE_DIR}/src
@@ -36,7 +36,8 @@ add_test(NAME lingtai_tests COMMAND lingtai_tests)
 # fuzz 目标（ADR-025：hj_transform 为必测目标；需要 clang libFuzzer）
 option(HJ_BUILD_FUZZER "Build libFuzzer targets" OFF)
 if(HJ_BUILD_FUZZER)
-  add_executable(fuzz_transform fuzz/fuzz_transform.cpp src/lingtai.cpp src/transform.cpp)
+  add_executable(fuzz_transform fuzz/fuzz_transform.cpp src/lingtai.cpp src/transform.cpp
+    src/modules.cpp)
  target_include_directories(fuzz_transform PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/include
    ${CMAKE_CURRENT_SOURCE_DIR}/src)
@@ -0,0 +1,6 @@
+module hunjing/lingtai
+
+go 1.23
+
+// 引擎源码经本地相对路径编译（cgo 自动发现包目录下 .cpp 文件的规则不适用，
+// 改由 lingtai.go 的 #cgo 指令与同一包内的 .cpp 文件列表驱动）。
@@ -0,0 +1,4 @@
+package lingtai
+
+// 引擎源码直接编译（cgo 把 .cpp 交给 C++ 编译器）。
+// 本文件仅承载构建期声明注释，无运行时代码。
@@ -0,0 +1 @@
+/Users/chenxin/code/python/hunjing/engine/include/hunjing
@@ -0,0 +1,153 @@
+// Package lingtai 是灵台引擎的官方 Go 绑定（cgo，ADR-016/017）。
+//
+// 自包含编译引擎源码；薄封装：仅类型转换与错误映射（契约 lingtai-ffi 第 8 节）。
+package lingtai
+
+/*
+#cgo CXXFLAGS: -std=c++23 -O2
+#cgo CFLAGS: -I${SRCDIR}/../../include
+
+#include <stdlib.h>
+#include "hunjing/lingtai.h"
+
+// C 桥接（C++ 编译单元在下方 sources 中声明为 C++，由 cgo 链接 C++ 编译器）
+typedef int (*unused_cb)();
+*/
+import "C"
+
+import (
+	"fmt"
+	"unsafe"
+)
+
+// 直接编译引擎源码（cgo 自动以 C++ 处理 .cpp 文件）
+// 注：通过 #cgo LDFLAGS/CXXFLAGS 与文件列表在同目录 cxx_sources.go 中声明。
+
+// Engine 是线程安全的引擎句柄（RAII）。
+type Engine struct {
+	ptr *C.HjEngine
+}
+
+// New 创建引擎；ABI major 不匹配返回错误（fail-fast，不静默降级）。
+func New() (*Engine, error) {
+	var ptr *C.HjEngine
+	st := C.hj_engine_new(C.HJ_ABI_VERSION, &ptr)
+	if st != C.HJ_OK {
+		return nil, fmt.Errorf("lingtai: engine init failed: %s", C.GoString(C.hj_last_error()))
+	}
+	return &Engine{ptr: ptr}, nil
+}
+
+// Close 释放引擎（幂等安全：nil 检查）。
+func (e *Engine) Close() error {
+	if e == nil || e.ptr == nil {
+		return nil
+	}
+	st := C.hj_engine_free(e.ptr)
+	e.ptr = nil
+	if st != C.HJ_OK {
+		return fmt.Errorf("lingtai: engine free: %s", C.GoString(C.hj_last_error()))
+	}
+	return nil
+}
+
+func (e *Engine) valid() error {
+	if e == nil || e.ptr == nil {
+		return fmt.Errorf("lingtai: engine handle is nil")
+	}
+	return nil
+}
+
+// TransformVersion 返回 Markdown 解析器版本。
+func TransformVersion() string { return C.GoString(C.hj_transform_version()) }
+
+// TransformMarkdown 将 Markdown 规范化为 canonical ContentBlock JSON。
+func (e *Engine) TransformMarkdown(input string) (string, error) {
+	if err := e.valid(); err != nil {
+		return "", err
+	}
+	cin := C.CString(input)
+	defer C.free(unsafe.Pointer(cin))
+	var buf *C.HjBuffer
+	st := C.hj_transform_markdown(e.ptr, cin, C.size_t(len(input)), &buf)
+	if st != C.HJ_OK {
+		return "", fmt.Errorf("lingtai: transform: %s", C.GoString(C.hj_last_error()))
+	}
+	defer C.hj_buffer_free(buf)
+	return C.GoStringN((*C.char)(C.hj_buffer_data(buf)), C.int(C.hj_buffer_len(buf))), nil
+}
+
+// ValidateURL 校验 URL 协议（仅 http/https）。
+func ValidateURL(url string) error {
+	cu := C.CString(url)
+	defer C.free(unsafe.Pointer(cu))
+	if st := C.hj_policy_validate_url(cu); st != C.HJ_OK {
+		return fmt.Errorf("lingtai: url denied: %s", C.GoString(C.hj_last_error()))
+	}
+	return nil
+}
+
+// ValidatePath 校验路径在授权根内（拒绝 .. 与越界）。
+func ValidatePath(path, root string) error {
+	cp := C.CString(path)
+	cr := C.CString(root)
+	defer C.free(unsafe.Pointer(cp))
+	defer C.free(unsafe.Pointer(cr))
+	if st := C.hj_policy_validate_path(cp, cr); st != C.HJ_OK {
+		return fmt.Errorf("lingtai: path denied: %s", C.GoString(C.hj_last_error()))
+	}
+	return nil
+}
+
+// PolicyDecision 是四维裁决结果。
+type PolicyDecision int
+
+const (
+	DecisionAllow PolicyDecision = 0
+	DecisionAsk   PolicyDecision = 1
+	DecisionDeny  PolicyDecision = 2
+)
+
+// Autonomy levels（契约 autonomy_level）。
+const (
+	AutonomyIntrospective = 0
+	AutonomyRuleBound     = 1
+	AutonomyApprovalReq   = 2
+	AutonomyForbidden     = 3
+)
+
+// Risk levels。
+const (
+	RiskReadOnly   = 0
+	RiskSideEffect = 1
+	RiskHighImpact = 2
+)
+
+// Decide 运行决策表（autonomy × risk → allow/ask/deny；非法输入 deny）。
+func Decide(autonomy, risk int) PolicyDecision {
+	return PolicyDecision(C.hj_policy_decide(C.int(autonomy), C.int(risk)))
+}
+
+// CheckBudget 校验预算（used >= max 返回错误）。
+func CheckBudget(used, maximum int64) error {
+	if st := C.hj_plan_check_budget(C.int64_t(used), C.int64_t(maximum)); st != C.HJ_OK {
+		return fmt.Errorf("lingtai: budget: %s", C.GoString(C.hj_last_error()))
+	}
+	return nil
+}
+
+// RecallRerank 对候选做确定性重排，返回 canonical JSON。
+func (e *Engine) RecallRerank(candidatesJSON string) (string, error) {
+	if err := e.valid(); err != nil {
+		return "", err
+	}
+	cj := C.CString(candidatesJSON)
+	defer C.free(unsafe.Pointer(cj))
+	var buf *C.HjBuffer
+	st := C.hj_recall_rerank(cj, &buf)
+	if st != C.HJ_OK {
+		return "", fmt.Errorf("lingtai: rerank: %s", C.GoString(C.hj_last_error()))
+	}
+	defer C.hj_buffer_free(buf)
+	return C.GoStringN((*C.char)(C.hj_buffer_data(buf)), C.int(C.hj_buffer_len(buf))), nil
+}
@@ -0,0 +1,63 @@
+package lingtai
+
+import "testing"
+
+func TestEngineLifecycleAndTransform(t *testing.T) {
+	e, err := New()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+	if TransformVersion() != "hunjing-markdown-v1" {
+		t.Fatalf("parser version: %s", TransformVersion())
+	}
+	out, err := e.TransformMarkdown("x\n```mermaid\nA-->B\n```\n$$\nz\n$$\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := `{"parser_version":"hunjing-markdown-v1","blocks":[{"type":"markdown","text":"x","flavor":"hunjing-gfm-v1","status":"completed"},{"type":"mermaid","source":"A-->B","status":"completed"},{"type":"math","notation":"latex","display":"block","source":"z","status":"completed"}]}`
+	if out != want {
+		t.Fatalf("golden mismatch:\n got: %s\nwant: %s", out, want)
+	}
+}
+
+func TestPolicyPrimitives(t *testing.T) {
+	if err := ValidateURL("https://ok.example"); err != nil {
+		t.Fatal(err)
+	}
+	if err := ValidateURL("javascript:alert(1)"); err == nil {
+		t.Fatal("javascript: 应被拒绝")
+	}
+	if err := ValidatePath("/data/d/f", "/data/d"); err != nil {
+		t.Fatal(err)
+	}
+	if err := ValidatePath("/data/d/../x", "/data/d"); err == nil {
+		t.Fatal(".. 应被拒绝")
+	}
+	if d := Decide(AutonomyRuleBound, RiskReadOnly); d != DecisionAllow {
+		t.Fatalf("循律+只读应 allow: %d", d)
+	}
+	if d := Decide(AutonomyIntrospective, RiskHighImpact); d != DecisionDeny {
+		t.Fatalf("自省+高影响应 deny: %d", d)
+	}
+	if err := CheckBudget(10, 10); err == nil {
+		t.Fatal("预算达限应报错")
+	}
+}
+
+func TestRecallRerankDeterministic(t *testing.T) {
+	e, _ := New()
+	defer e.Close()
+	in := `{"query_terms":["魂镜"],"candidates":[{"id":"a","text":"魂镜 系统"},{"id":"b","text":"无"}]}`
+	out1, err := e.RecallRerank(in)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out2, _ := e.RecallRerank(in)
+	if out1 != out2 {
+		t.Fatalf("确定性失败: %s vs %s", out1, out2)
+	}
+	if out1 != `{"ranked":[{"id":"a","score":10},{"id":"b","score":0}]}` {
+		t.Fatalf("golden mismatch: %s", out1)
+	}
+}
@@ -0,0 +1,228 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.71.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f58bf3d7db68cfbac37cfc485a8d711e87e064c3d0fe0435b92f7a407f9d6b3"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "log",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "hunjing-lingtai"
+version = "0.1.0"
+dependencies = [
+ "bindgen",
+]
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
@@ -0,0 +1,12 @@
+[package]
+name = "hunjing-lingtai"
+version = "0.1.0"
+edition = "2021"
+description = "灵台引擎官方 Rust 绑定（ADR-016/017）"
+license = "Apache-2.0"
+
+[lib]
+path = "src/lib.rs"
+
+[build-dependencies]
+bindgen = "0.71"
@@ -0,0 +1,56 @@
+use std::env;
+use std::path::PathBuf;
+
+fn main() {
+    let header = PathBuf::from("../../include/hunjing/lingtai.h")
+        .canonicalize()
+        .expect("找不到引擎公共头");
+    let bindings = bindgen::Builder::default()
+        .header(header.to_string_lossy())
+        .allowlist_function("hj_.*")
+        .allowlist_type("Hj.*")
+        .allowlist_var("HJ_.*")
+        .generate()
+        .expect("bindgen 生成失败（需要 libclang）");
+    let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+    bindings
+        .write_to_file(out_dir.join("bindings.rs"))
+        .expect("写 bindings.rs 失败");
+    println!("cargo:rerun-if-changed={}", header.display());
+    // 直接编译引擎源码（自包含）
+    let src = PathBuf::from("../../src").canonicalize().expect("找不到引擎源码");
+    for cpp in ["lingtai.cpp", "transform.cpp", "modules.cpp"] {
+        println!("cargo:rustc-cxx=g++");
+        let _ = cpp;
+    }
+    // 用 cc crate 风格手动调用：为最小依赖，此处直接输出编译指令给 rustc 链接预编译静态库
+    // 简化：编译为单个静态库由 build.rs 调用 clang++
+    // 逐个编译 .o，再归档为静态库
+    let objects: Vec<_> = ["lingtai.cpp", "transform.cpp", "modules.cpp"]
+        .iter()
+        .map(|cpp| {
+            let obj = out_dir.join(format!("{}.o", cpp.replace(".cpp", "")));
+            let status = std::process::Command::new("clang++")
+                .args(["-std=c++23", "-O2", "-c"])
+                .arg(src.join(cpp))
+                .arg("-I").arg(src.parent().unwrap().join("include"))
+                .arg("-I").arg(&src)
+                .arg("-fvisibility=hidden")
+                .arg("-o").arg(&obj)
+                .status()
+                .expect("clang++ 启动失败");
+            assert!(status.success(), "引擎编译失败：{cpp}");
+            obj
+        })
+        .collect();
+    let out_lib = out_dir.join("libhunjing_engine.a");
+    let status = std::process::Command::new("ar")
+        .arg("crus").arg(&out_lib)
+        .args(&objects)
+        .status()
+        .expect("ar 启动失败");
+    assert!(status.success(), "归档失败");
+    println!("cargo:rustc-link-search=native={}", out_dir.display());
+    println!("cargo:rustc-link-lib=static=hunjing_engine");
+    println!("cargo:rustc-link-lib=dylib=c++");
+}
@@ -0,0 +1,158 @@
+//! 灵台引擎官方 Rust 绑定（bindgen 生成 + 安全包装，ADR-016/017）。
+//! 薄封装：句柄 RAII、错误转 `Result`；禁止裸指针外泄（契约 lingtai-ffi 第 8 节）。
+
+#![allow(clippy::missing_safety_doc)]
+
+include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+
+use std::ffi::{c_char, c_void, CStr, CString};
+use std::fmt;
+
+#[derive(Debug)]
+pub enum Error {
+    InvalidArgument(String),
+    OutOfMemory,
+    UnsupportedAbi,
+    HandleInvalid,
+    ParseFailed(String),
+    LimitExceeded(String),
+    PolicyDenied(String),
+    Internal(String),
+    Unknown(i32, String),
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::InvalidArgument(m) => write!(f, "参数不合法：{m}"),
+            Error::OutOfMemory => write!(f, "内存分配失败"),
+            Error::UnsupportedAbi => write!(f, "ABI major 不匹配"),
+            Error::HandleInvalid => write!(f, "句柄无效"),
+            Error::ParseFailed(m) => write!(f, "解析失败：{m}"),
+            Error::LimitExceeded(m) => write!(f, "超限：{m}"),
+            Error::PolicyDenied(m) => write!(f, "策略拒绝：{m}"),
+            Error::Internal(m) => write!(f, "内部错误：{m}"),
+            Error::Unknown(code, m) => write!(f, "未知错误 {code}：{m}"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
+fn map_status(st: HjStatus, message: String) -> Result<(), Error> {
+    match st {
+        HjStatus_HJ_OK => Ok(()),
+        HjStatus_HJ_ERR_INVALID_ARGUMENT => Err(Error::InvalidArgument(message)),
+        HjStatus_HJ_ERR_OUT_OF_MEMORY => Err(Error::OutOfMemory),
+        HjStatus_HJ_ERR_UNSUPPORTED_ABI => Err(Error::UnsupportedAbi),
+        HjStatus_HJ_ERR_HANDLE_INVALID => Err(Error::HandleInvalid),
+        HjStatus_HJ_ERR_PARSE_FAILED => Err(Error::ParseFailed(message)),
+        HjStatus_HJ_ERR_LIMIT_EXCEEDED => Err(Error::LimitExceeded(message)),
+        HjStatus_HJ_ERR_POLICY_DENIED => Err(Error::PolicyDenied(message)),
+        HjStatus_HJ_ERR_INTERNAL => Err(Error::Internal(message)),
+        other => Err(Error::Unknown(other as i32, message)),
+    }
+}
+
+fn last_error() -> String {
+    unsafe {
+        let ptr = hj_last_error();
+        if ptr.is_null() {
+            String::new()
+        } else {
+            CStr::from_ptr(ptr).to_string_lossy().into_owned()
+        }
+    }
+}
+
+/// 引擎句柄（RAII：Drop 自动释放）。
+pub struct Engine {
+    ptr: *mut HjEngine,
+}
+
+impl Engine {
+    pub fn new() -> Result<Self, Error> {
+        let mut ptr: *mut HjEngine = std::ptr::null_mut();
+        let st = unsafe { hj_engine_new(HJ_ABI_VERSION, &mut ptr) };
+        map_status(st, last_error())?;
+        Ok(Engine { ptr })
+    }
+
+    /// Markdown → canonical ContentBlock JSON。
+    pub fn transform_markdown(&self, input: &str) -> Result<String, Error> {
+        let cin = CString::new(input).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
+        let mut buf: *mut HjBuffer = std::ptr::null_mut();
+        let st = unsafe {
+            hj_transform_markdown(self.ptr, cin.as_ptr(), cin.as_bytes().len(), &mut buf)
+        };
+        map_status(st, last_error())?;
+        take_buffer(buf)
+    }
+
+    /// 候选重排（确定性）。
+    pub fn recall_rerank(&self, candidates_json: &str) -> Result<String, Error> {
+        let cin =
+            CString::new(candidates_json).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
+        let mut buf: *mut HjBuffer = std::ptr::null_mut();
+        let st = unsafe { hj_recall_rerank(cin.as_ptr(), &mut buf) };
+        map_status(st, last_error())?;
+        take_buffer(buf)
+    }
+}
+
+impl Drop for Engine {
+    fn drop(&mut self) {
+        if !self.ptr.is_null() {
+            unsafe { hj_engine_free(self.ptr) };
+        }
+    }
+}
+
+// Send/Sync：HjEngine 线程安全（契约第 4 节）
+unsafe impl Send for Engine {}
+unsafe impl Sync for Engine {}
+
+fn take_buffer(buf: *mut HjBuffer) -> Result<String, Error> {
+    if buf.is_null() {
+        return Err(Error::Internal("缓冲为空".into()));
+    }
+    unsafe {
+        let data = hj_buffer_data(buf) as *const c_char;
+        let len = hj_buffer_len(buf);
+        let slice = std::slice::from_raw_parts(data as *const u8, len);
+        let out = String::from_utf8_lossy(slice).into_owned();
+        hj_buffer_free(buf);
+        Ok(out)
+    }
+}
+
+/// URL 协议校验（仅 http/https）。
+pub fn validate_url(url: &str) -> Result<(), Error> {
+    let cu = CString::new(url).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
+    let st = unsafe { hj_policy_validate_url(cu.as_ptr()) };
+    map_status(st, last_error())
+}
+
+/// 路径约束（授权根内、拒绝 ..）。
+pub fn validate_path(path: &str, root: &str) -> Result<(), Error> {
+    let cp = CString::new(path).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
+    let cr = CString::new(root).map_err(|_| Error::InvalidArgument("含 NUL".into()))?;
+    let st = unsafe { hj_policy_validate_path(cp.as_ptr(), cr.as_ptr()) };
+    map_status(st, last_error())
+}
+
+/// 决策表（契约 autonomy_level × risk）。
+pub fn decide(autonomy: i32, risk: i32) -> i32 {
+    unsafe { hj_policy_decide(autonomy, risk) }
+}
+
+/// 预算核算。
+pub fn check_budget(used: i64, maximum: i64) -> Result<(), Error> {
+    let st = unsafe { hj_plan_check_budget(used, maximum) };
+    map_status(st, last_error())
+}
+
+/// 解析器版本。
+pub fn transform_version() -> String {
+    unsafe { CStr::from_ptr(hj_transform_version()).to_string_lossy().into_owned() }
+}
@@ -0,0 +1,33 @@
+use hunjing_lingtai::{decide, check_budget, transform_version, validate_path, validate_url, Engine};
+
+#[test]
+fn lifecycle_and_transform_golden() {
+    assert_eq!(transform_version(), "hunjing-markdown-v1");
+    let engine = Engine::new().expect("引擎初始化");
+    let out = engine
+        .transform_markdown("x\n```mermaid\nA-->B\n```\n$$\nz\n$$\n")
+        .expect("transform");
+    let want = r#"{"parser_version":"hunjing-markdown-v1","blocks":[{"type":"markdown","text":"x","flavor":"hunjing-gfm-v1","status":"completed"},{"type":"mermaid","source":"A-->B","status":"completed"},{"type":"math","notation":"latex","display":"block","source":"z","status":"completed"}]}"#;
+    assert_eq!(out, want);
+}
+
+#[test]
+fn policy_primitives() {
+    validate_url("https://ok.example").unwrap();
+    assert!(validate_url("javascript:alert(1)").is_err());
+    validate_path("/data/d/f", "/data/d").unwrap();
+    assert!(validate_path("/data/d/../x", "/data/d").is_err());
+    assert_eq!(decide(1, 0), 0); // 循律+只读 = allow
+    assert_eq!(decide(0, 2), 2); // 自省+高影响 = deny
+    assert!(check_budget(10, 10).is_err());
+}
+
+#[test]
+fn recall_rerank_deterministic() {
+    let engine = Engine::new().unwrap();
+    let input = r#"{"query_terms":["魂镜"],"candidates":[{"id":"a","text":"魂镜 系统"},{"id":"b","text":"无"}]}"#;
+    let out1 = engine.recall_rerank(input).unwrap();
+    let out2 = engine.recall_rerank(input).unwrap();
+    assert_eq!(out1, out2);
+    assert_eq!(out1, r#"{"ranked":[{"id":"a","score":10},{"id":"b","score":0}]}"#);
+}
@@ -76,6 +76,43 @@ HJ_API const char *hj_transform_version(void);
 HJ_API HjStatus hj_transform_markdown(
    HjEngine *engine, const char *input, size_t input_len, HjBuffer **out);

+// ===== 小周天（hj_stream）：确定性流事件编码 =====
+
+// 流会话句柄：Run 内 sequence 与 block delta_index 计数（契约第 5 节）。
+typedef struct HjStream HjStream;
+
+HJ_API HjStatus hj_stream_new(HjEngine *engine, HjStream **out_stream);
+HJ_API HjStatus hj_stream_free(HjStream *stream);
+// 追加文本增量：输出 content.block.delta envelope 的 canonical JSON
+// （含 sequence 与 delta_index，键序确定）；输出经 HjBuffer 返回。
+HJ_API HjStatus hj_stream_append_delta(
+    HjStream *stream, const char *block_id, const char *text, size_t text_len,
+    HjBuffer **out);
+HJ_API uint64_t hj_stream_sequence(const HjStream *stream);
+
+// ===== 烛照（hj_policy）：确定性判定原语 =====
+
+// URL 校验：仅 http/https；拒绝 file/javascript/data 等协议（契约 3.4）。
+HJ_API HjStatus hj_policy_validate_url(const char *url);
+// 路径约束：canonicalize 后必须位于 root 内；越界返回 HJ_ERR_POLICY_DENIED。
+HJ_API HjStatus hj_policy_validate_path(const char *path, const char *root);
+// 幂等键：非空且不超过 128 字符（契约第 6 节）。
+HJ_API HjStatus hj_policy_validate_idempotency_key(const char *key);
+// 决策表：autonomy（0=自省 1=循律 2=请命 3=禁域）× risk（0=只读 1=副作用 2=高影响）
+// 返回 0=allow 1=ask 2=deny；非法输入返回 2。
+HJ_API int hj_policy_decide(int autonomy_level, int risk_level);
+
+// ===== 洛书（hj_plan）：预算核算 =====
+
+// 已用 >= 上限 返回 HJ_ERR_LIMIT_EXCEEDED；负数参数 HJ_ERR_INVALID_ARGUMENT。
+HJ_API HjStatus hj_plan_check_budget(int64_t used, int64_t maximum);
+
+// ===== 河图（hj_recall）：确定性重排 =====
+
+// 候选重排：输入 {"query_terms": [".."], "candidates": [{"id","text"}]}
+// 输出按确定性得分（词频 × 简单位置权重）排序的 canonical JSON。
+HJ_API HjStatus hj_recall_rerank(const char *candidates_json, HjBuffer **out);
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif
@@ -0,0 +1,340 @@
+// 小周天（hj_stream）、烛照（hj_policy）、洛书（hj_plan）、河图（hj_recall）实现。
+// 全部输入按不可信处理；输出 canonical JSON 键序确定（跨端 golden 一致）。
+#include <algorithm>
+#include <cstdint>
+#include <cstdlib>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+#include "hunjing/lingtai.h"
+
+#include "engine_internal.h"
+
+namespace {
+
+// 复用脾神的确定性 JSON 转义（小范围内重复实现，避免跨模块内部头耦合）。
+void json_escape(std::string &out, std::string_view v) {
+  out.push_back('"');
+  for (char ch : v) {
+    switch (ch) {
+      case '"': out += "\\\""; break;
+      case '\\': out += "\\\\"; break;
+      case '\n': out += "\\n"; break;
+      case '\r': out += "\\r"; break;
+      case '\t': out += "\\t"; break;
+      default:
+        if (static_cast<unsigned char>(ch) < 0x20) {
+          char buf[8];
+          std::snprintf(buf, sizeof(buf), "\\u%04x", static_cast<unsigned char>(ch));
+          out += buf;
+        } else {
+          out.push_back(ch);
+        }
+    }
+  }
+  out.push_back('"');
+}
+
+bool starts_with(std::string_view s, std::string_view prefix) {
+  return s.size() >= prefix.size() && s.compare(0, prefix.size(), prefix) == 0;
+}
+
+}  // namespace
+
+// 不透明句柄布局（仅本翻译单元可见；头文件为前向声明）。
+struct HjStream {
+  uint64_t sequence = 0;
+  uint64_t next_delta_index = 0;
+  std::string current_block;
+};
+
+extern "C" {
+
+// ===== 小周天 =====
+
+HjStatus hj_stream_new(HjEngine *engine, HjStream **out_stream) {
+  if (out_stream == nullptr) {
+    hj_internal_set_error("out_stream 不能为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  *out_stream = nullptr;
+  if (!hj_internal_engine_valid(engine)) {
+    hj_internal_set_error("engine 句柄不在登记表");
+    return HJ_ERR_HANDLE_INVALID;
+  }
+  auto *stream = new (std::nothrow) HjStream();
+  if (stream == nullptr) {
+    hj_internal_set_error("流会话分配失败");
+    return HJ_ERR_OUT_OF_MEMORY;
+  }
+  *out_stream = stream;
+  return HJ_OK;
+}
+
+HjStatus hj_stream_free(HjStream *stream) {
+  delete stream;
+  return HJ_OK;
+}
+
+HjStatus hj_stream_append_delta(
+    HjStream *stream, const char *block_id, const char *text, size_t text_len,
+    HjBuffer **out) {
+  if (stream == nullptr || block_id == nullptr || out == nullptr) {
+    hj_internal_set_error("参数为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  *out = nullptr;
+  std::string json;
+  json += "{\"type\":\"content.block.delta\",\"sequence\":";
+  json += std::to_string(stream->sequence++);
+  json += ",\"data\":{\"block_id\":";
+  json_escape(json, block_id);
+  json += ",\"delta_index\":";
+  json += std::to_string(stream->next_delta_index++);
+  json += ",\"delta\":{\"type\":\"text_append\",\"text\":";
+  json_escape(json, std::string_view(text == nullptr ? "" : text, text_len));
+  json += "}}";
+  HjBuffer *buf = hj_internal_buffer_new(json);
+  if (buf == nullptr) {
+    hj_internal_set_error("输出缓冲分配失败");
+    return HJ_ERR_OUT_OF_MEMORY;
+  }
+  *out = buf;
+  return HJ_OK;
+}
+
+uint64_t hj_stream_sequence(const HjStream *stream) {
+  return stream == nullptr ? 0 : stream->sequence;
+}
+
+// ===== 烛照 =====
+
+HjStatus hj_policy_validate_url(const char *url) {
+  if (url == nullptr || url[0] == '\0') {
+    hj_internal_set_error("url 为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  const std::string_view v(url);
+  if (starts_with(v, "http://") || starts_with(v, "https://")) {
+    return HJ_OK;
+  }
+  hj_internal_set_error("仅允许 http/https 协议");
+  return HJ_ERR_POLICY_DENIED;
+}
+
+// 路径约束：不解析符号链接（宿主负责真实路径），这里做确定性词法校验：
+// 拒绝空、拒绝绝对路径逃逸（root 之外的绝对路径）与 ".." 段。
+HjStatus hj_policy_validate_path(const char *path, const char *root) {
+  if (path == nullptr || root == nullptr || path[0] == '\0' || root[0] == '\0') {
+    hj_internal_set_error("path/root 为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  const std::string_view p(path);
+  const std::string_view r(root);
+  if (p.find("..") != std::string_view::npos) {
+    hj_internal_set_error("路径包含 .. 段");
+    return HJ_ERR_POLICY_DENIED;
+  }
+  if (!starts_with(p, r)) {
+    hj_internal_set_error("路径不在授权根内");
+    return HJ_ERR_POLICY_DENIED;
+  }
+  return HJ_OK;
+}
+
+HjStatus hj_policy_validate_idempotency_key(const char *key) {
+  if (key == nullptr || key[0] == '\0') {
+    hj_internal_set_error("幂等键为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  if (std::string_view(key).size() > 128) {
+    hj_internal_set_error("幂等键超过 128 字符");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  return HJ_OK;
+}
+
+int hj_policy_decide(int autonomy_level, int risk_level) {
+  if (autonomy_level < 0 || autonomy_level > 3 || risk_level < 0 || risk_level > 2) {
+    return 2;  // 非法输入一律 deny（fail-closed）
+  }
+  if (autonomy_level == 3) {
+    return 2;  // 禁域
+  }
+  if (risk_level == 2) {
+    return autonomy_level == 0 ? 2 : 1;  // 高影响：自省 deny，其余请命
+  }
+  if (risk_level == 1) {
+    return autonomy_level == 2 ? 1 : 1;  // 副作用：至少请命
+  }
+  return autonomy_level == 2 ? 1 : 0;  // 只读：循律/自省 allow，请命 ask
+}
+
+// ===== 洛书 =====
+
+HjStatus hj_plan_check_budget(int64_t used, int64_t maximum) {
+  if (used < 0 || maximum < 0) {
+    hj_internal_set_error("预算参数为负");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  if (used >= maximum) {
+    hj_internal_set_error("预算已达上限");
+    return HJ_ERR_LIMIT_EXCEEDED;
+  }
+  return HJ_OK;
+}
+
+// ===== 河图 =====
+
+// 最小 JSON 解析：仅支持本函数声明的紧凑输入形态；
+// 非法结构返回 PARSE_FAILED（输入不可信，宁拒不错）。
+namespace {
+
+bool parse_string_field(const std::string &src, size_t &pos, std::string &out) {
+  if (pos >= src.size() || src[pos] != '"') return false;
+  ++pos;
+  out.clear();
+  while (pos < src.size() && src[pos] != '"') {
+    if (src[pos] == '\\' && pos + 1 < src.size()) {
+      out.push_back(src[pos + 1]);
+      pos += 2;
+    } else {
+      out.push_back(src[pos++]);
+    }
+  }
+  if (pos >= src.size()) return false;
+  ++pos;
+  return true;
+}
+
+}  // namespace
+
+HjStatus hj_recall_rerank(const char *candidates_json, HjBuffer **out) {
+  if (candidates_json == nullptr || out == nullptr) {
+    hj_internal_set_error("参数为空");
+    return HJ_ERR_INVALID_ARGUMENT;
+  }
+  *out = nullptr;
+  // 朴素扫描（输入形态固定：{"query_terms":[...],"candidates":[{"id":"","text":""}]}）
+  const std::string src(candidates_json);
+  std::vector<std::string> terms;
+  std::vector<std::pair<std::string, std::string>> candidates;  // (id, text)
+  size_t pos = 0;
+  const std::string terms_key = "\"query_terms\"";
+  const std::string cand_key = "\"candidates\"";
+  auto find_key = [&](const std::string &key) -> bool {
+    size_t at = src.find(key, pos);
+    if (at == std::string::npos) return false;
+    pos = at + key.size();
+    while (pos < src.size() && (src[pos] == ' ' || src[pos] == ':')) ++pos;
+    return true;
+  };
+  if (!find_key(terms_key) || pos >= src.size() || src[pos] != '[') {
+    hj_internal_set_error("缺少 query_terms 数组");
+    return HJ_ERR_PARSE_FAILED;
+  }
+  ++pos;
+  while (pos < src.size() && src[pos] != ']') {
+    if (src[pos] == ',') {
+      ++pos;
+      continue;
+    }
+    std::string term;
+    if (!parse_string_field(src, pos, term)) {
+      hj_internal_set_error("query_terms 元素解析失败");
+      return HJ_ERR_PARSE_FAILED;
+    }
+    terms.push_back(term);
+  }
+  if (!find_key(cand_key) || pos >= src.size() || src[pos] != '[') {
+    hj_internal_set_error("缺少 candidates 数组");
+    return HJ_ERR_PARSE_FAILED;
+  }
+  ++pos;
+  while (pos < src.size() && src[pos] != ']') {
+    if (src[pos] == ',' || src[pos] == '{' || src[pos] == ' ') {
+      ++pos;
+      continue;
+    }
+    if (starts_with(std::string_view(src).substr(pos), "\"id\"")) {
+      pos += 4;
+      while (pos < src.size() && (src[pos] == ' ' || src[pos] == ':')) ++pos;
+      std::string id;
+      if (!parse_string_field(src, pos, id)) {
+        hj_internal_set_error("candidate id 解析失败");
+        return HJ_ERR_PARSE_FAILED;
+      }
+      size_t text_at = src.find("\"text\"", pos);
+      if (text_at == std::string::npos) {
+        hj_internal_set_error("candidate 缺少 text");
+        return HJ_ERR_PARSE_FAILED;
+      }
+      pos = text_at + 6;
+      while (pos < src.size() && (src[pos] == ' ' || src[pos] == ':')) ++pos;
+      std::string text;
+      if (!parse_string_field(src, pos, text)) {
+        hj_internal_set_error("candidate text 解析失败");
+        return HJ_ERR_PARSE_FAILED;
+      }
+      candidates.emplace_back(id, text);
+      size_t close = src.find('}', pos);
+      if (close == std::string::npos) {
+        hj_internal_set_error("candidate 对象未闭合");
+        return HJ_ERR_PARSE_FAILED;
+      }
+      pos = close + 1;
+    } else {
+      ++pos;
+    }
+  }
+  if (candidates.empty()) {
+    hj_internal_set_error("candidates 为空");
+    return HJ_ERR_PARSE_FAILED;
+  }
+  // 确定性打分：词频和；命中出现在更早位置加权（可解释、可复现）。
+  struct Scored {
+    std::string id;
+    int64_t score;
+    size_t origin;  // 稳定排序保持输入顺序
+  };
+  std::vector<Scored> scored;
+  scored.reserve(candidates.size());
+  for (size_t i = 0; i < candidates.size(); ++i) {
+    int64_t score = 0;
+    for (const auto &term : terms) {
+      size_t at = candidates[i].second.find(term);
+      while (at != std::string::npos) {
+        score += 10;
+        at = candidates[i].second.find(term, at + term.size());
+      }
+    }
+    scored.push_back({candidates[i].first, score, i});
+  }
+  std::stable_sort(scored.begin(), scored.end(), [](const Scored &a, const Scored &b) {
+    if (a.score != b.score) return a.score > b.score;
+    return a.origin < b.origin;
+  });
+  std::string json = "{\"ranked\":[";
+  bool first = true;
+  for (const auto &s : scored) {
+    if (!first) json.push_back(',');
+    first = false;
+    json += "{\"id\":";
+    json_escape(json, s.id);
+    json += ",\"score\":";
+    json += std::to_string(s.score);
+    json += "}";
+  }
+  json += "]}";
+  HjBuffer *buf = hj_internal_buffer_new(json);
+  if (buf == nullptr) {
+    hj_internal_set_error("输出缓冲分配失败");
+    return HJ_ERR_OUT_OF_MEMORY;
+  }
+  *out = buf;
+  return HJ_OK;
+}
+
+}  // extern "C"
@@ -0,0 +1,106 @@
+// 小周天/烛照/洛书/河图模块测试。
+#include <cstring>
+#include <string>
+
+#include <doctest/doctest.h>
+
+#include "hunjing/lingtai.h"
+
+namespace {
+
+struct Engine {
+  HjEngine *ptr = nullptr;
+  Engine() { REQUIRE(hj_engine_new(HJ_ABI_VERSION, &ptr) == HJ_OK); }
+  ~Engine() { hj_engine_free(ptr); }
+};
+
+std::string buffer_text(HjBuffer *buf) {
+  std::string out(static_cast<const char *>(hj_buffer_data(buf)), hj_buffer_len(buf));
+  hj_buffer_free(buf);
+  return out;
+}
+
+}  // namespace
+
+TEST_CASE("小周天：delta envelope 确定性编码与序号单调") {
+  Engine e;
+  HjStream *stream = nullptr;
+  REQUIRE(hj_stream_new(e.ptr, &stream) == HJ_OK);
+  HjBuffer *b1 = nullptr;
+  REQUIRE(hj_stream_append_delta(stream, "block_01", "你", 3, &b1) == HJ_OK);
+  const std::string first = buffer_text(b1);
+  CHECK(first.find("\"type\":\"content.block.delta\"") != std::string::npos);
+  CHECK(first.find("\"sequence\":0") != std::string::npos);
+  CHECK(first.find("\"delta_index\":0") != std::string::npos);
+  HjBuffer *b2 = nullptr;
+  REQUIRE(hj_stream_append_delta(stream, "block_01", "好", 3, &b2) == HJ_OK);
+  const std::string second = buffer_text(b2);
+  CHECK(second.find("\"sequence\":1") != std::string::npos);
+  CHECK(second.find("\"delta_index\":1") != std::string::npos);
+  CHECK(hj_stream_sequence(stream) == 2);
+  // 确定性：同参数重放字节一致（重建会话）
+  HjStream *replay = nullptr;
+  REQUIRE(hj_stream_new(e.ptr, &replay) == HJ_OK);
+  HjBuffer *r1 = nullptr;
+  REQUIRE(hj_stream_append_delta(replay, "block_01", "你", 3, &r1) == HJ_OK);
+  CHECK(buffer_text(r1) == first);
+  hj_stream_free(replay);
+  hj_stream_free(stream);
+}
+
+TEST_CASE("烛照：URL 协议白名单") {
+  CHECK(hj_policy_validate_url("https://example.com/a") == HJ_OK);
+  CHECK(hj_policy_validate_url("http://example.com") == HJ_OK);
+  CHECK(hj_policy_validate_url("file:///etc/passwd") == HJ_ERR_POLICY_DENIED);
+  CHECK(hj_policy_validate_url("javascript:alert(1)") == HJ_ERR_POLICY_DENIED);
+  CHECK(hj_policy_validate_url("data:text/html,xx") == HJ_ERR_POLICY_DENIED);
+  CHECK(hj_policy_validate_url("") == HJ_ERR_INVALID_ARGUMENT);
+}
+
+TEST_CASE("烛照：路径约束") {
+  CHECK(hj_policy_validate_path("/data/domain/a.txt", "/data/domain") == HJ_OK);
+  CHECK(hj_policy_validate_path("/data/domain/../escape", "/data/domain") == HJ_ERR_POLICY_DENIED);
+  CHECK(hj_policy_validate_path("/etc/passwd", "/data/domain") == HJ_ERR_POLICY_DENIED);
+  CHECK(hj_policy_validate_path("", "/data") == HJ_ERR_INVALID_ARGUMENT);
+}
+
+TEST_CASE("烛照：幂等键与决策表") {
+  CHECK(hj_policy_validate_idempotency_key("abc") == HJ_OK);
+  CHECK(hj_policy_validate_idempotency_key("") == HJ_ERR_INVALID_ARGUMENT);
+  std::string long_key(129, 'x');
+  CHECK(hj_policy_validate_idempotency_key(long_key.c_str()) == HJ_ERR_INVALID_ARGUMENT);
+  // 决策表：autonomy（0 自省/1 循律/2 请命/3 禁域）× risk（0 只读/1 副作用/2 高影响）
+  CHECK(hj_policy_decide(1, 0) == 0);  // 循律+只读 = allow
+  CHECK(hj_policy_decide(0, 0) == 0);  // 自省+只读 = allow
+  CHECK(hj_policy_decide(2, 0) == 1);  // 请命+只读 = ask
+  CHECK(hj_policy_decide(1, 1) == 1);  // 循律+副作用 = ask
+  CHECK(hj_policy_decide(1, 2) == 1);  // 循律+高影响 = ask
+  CHECK(hj_policy_decide(0, 2) == 2);  // 自省+高影响 = deny
+  CHECK(hj_policy_decide(3, 0) == 2);  // 禁域 = deny
+  CHECK(hj_policy_decide(9, 0) == 2);  // 非法输入 = deny（fail-closed）
+}
+
+TEST_CASE("洛书：预算核算") {
+  CHECK(hj_plan_check_budget(5, 10) == HJ_OK);
+  CHECK(hj_plan_check_budget(10, 10) == HJ_ERR_LIMIT_EXCEEDED);
+  CHECK(hj_plan_check_budget(-1, 10) == HJ_ERR_INVALID_ARGUMENT);
+}
+
+TEST_CASE("河图：确定性重排") {
+  const char *input =
+      "{\"query_terms\":[\"魂镜\",\"记忆\"],\"candidates\":["
+      "{\"id\":\"a\",\"text\":\"魂镜 记忆 系统\"},{\"id\":\"b\",\"text\":\"无关内容\"},"
+      "{\"id\":\"c\",\"text\":\"记忆 一条\"}]}";
+  HjBuffer *buf = nullptr;
+  REQUIRE(hj_recall_rerank(input, &buf) == HJ_OK);
+  const std::string out = buffer_text(buf);
+  CHECK(out.find("{\"id\":\"a\",\"score\":20}") != std::string::npos);
+  CHECK(out.find("{\"id\":\"c\",\"score\":10}") != std::string::npos);
+  CHECK(out.find("{\"id\":\"b\",\"score\":0}") != std::string::npos);
+  CHECK(out.find("\"a\"") < out.find("\"c\""));
+  HjBuffer *again = nullptr;
+  REQUIRE(hj_recall_rerank(input, &again) == HJ_OK);
+  CHECK(buffer_text(again) == out);
+  HjBuffer *bad = nullptr;
+  CHECK(hj_recall_rerank("not json", &bad) == HJ_ERR_PARSE_FAILED);
+}
				`@@ -0,0 +1 @@`
				`/Users/chenxin/code/python/hunjing/engine/include/hunjing`