✨ 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
@@ -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}]}"#);
+}
				`@@ -0,0 +1 @@`
				`/Users/chenxin/code/python/hunjing/engine/include/hunjing`