chenxin
127191c889
- C ABI 新增 hj_transform_version / hj_transform_markdown（契约登记同步）；HjBuffer 真实实现（头部+紧随数据） - v1 解析（hunjing-markdown-v1）：fenced code/mermaid 提取、独占行 $$ 块级数学、未闭合结构保持源码态、其余归并 markdown block；canonical JSON 键序确定、UTF-8 校验、1MiB/256 block/64KiB 行硬限额 - 引擎内部设施抽取（engine_internal.h：last_error/句柄表/buffer 共享） - doctest 12 个用例（含 1 万次随机鲁棒性冒烟，固定种子可复现）；libFuzzer 目标（-DHJ_BUILD_FUZZER，Apple clang 无 fuzzer 运行时，正式跑在 Linux CI） - nm 验证 9 个导出符号全部 hj_*
84 lines
2.8 KiB
C
84 lines
2.8 KiB
C
// Hunjing 灵台引擎公共头（Lingtai C ABI）。
|
||
// 契约真源：docs/contracts/lingtai-ffi.md；本文件是机器化前的稳定声明基线。
|
||
// 只导出 extern "C" 的 hj_* 符号与不透明句柄；异常、STL、RTTI 不跨越边界。
|
||
#ifndef HUNJING_LINGTAI_H
|
||
#define HUNJING_LINGTAI_H
|
||
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
|
||
#if defined(_WIN32)
|
||
#if defined(HJ_BUILDING)
|
||
#define HJ_API __declspec(dllexport)
|
||
#else
|
||
#define HJ_API __declspec(dllimport)
|
||
#endif
|
||
#else
|
||
#define HJ_API __attribute__((visibility("default")))
|
||
#endif
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
// 当前 ABI major；major 不匹配时 hj_engine_new 拒绝初始化。
|
||
#define HJ_ABI_VERSION 1
|
||
|
||
// 不透明句柄：字段布局不进入契约。
|
||
typedef struct HjEngine HjEngine;
|
||
typedef struct HjBuffer HjBuffer;
|
||
|
||
// 稳定状态码（登记于契约第 5 节；新增不破坏兼容）。
|
||
typedef enum HjStatus {
|
||
HJ_OK = 0,
|
||
HJ_ERR_INVALID_ARGUMENT = 1,
|
||
HJ_ERR_OUT_OF_MEMORY = 2,
|
||
HJ_ERR_UNSUPPORTED_ABI = 3,
|
||
HJ_ERR_HANDLE_INVALID = 4,
|
||
HJ_ERR_REENTRANCY = 5,
|
||
HJ_ERR_PARSE_FAILED = 6,
|
||
HJ_ERR_LIMIT_EXCEEDED = 7,
|
||
HJ_ERR_POLICY_DENIED = 8,
|
||
HJ_ERR_SIGNATURE_INVALID = 9,
|
||
HJ_ERR_INDEX_CORRUPT = 10,
|
||
HJ_ERR_BUFFER_TOO_SMALL = 11,
|
||
HJ_ERR_INTERNAL = 12
|
||
} HjStatus;
|
||
|
||
// 返回引擎构建时的 ABI major。
|
||
HJ_API uint32_t hj_abi_version(void);
|
||
|
||
// 创建引擎句柄；宿主传入所需 major，不匹配返回 HJ_ERR_UNSUPPORTED_ABI 且不产生句柄。
|
||
// 成功时 *out_engine 非空。HjEngine 线程安全。
|
||
HJ_API HjStatus hj_engine_new(uint32_t required_abi_major, HjEngine **out_engine);
|
||
|
||
// 释放引擎句柄；句柄不在登记表（含二次释放）返回 HJ_ERR_HANDLE_INVALID，不崩溃。
|
||
HJ_API HjStatus hj_engine_free(HjEngine *engine);
|
||
|
||
// 释放引擎分配的缓冲；仅用于引擎产出的 HjBuffer。
|
||
HJ_API HjStatus hj_buffer_free(HjBuffer *buffer);
|
||
|
||
// 读取缓冲内容与长度；非法句柄返回 NULL / 0。
|
||
HJ_API const void *hj_buffer_data(const HjBuffer *buffer);
|
||
HJ_API size_t hj_buffer_len(const HjBuffer *buffer);
|
||
|
||
// 线程局部的最近一次错误消息（UTF-8、脱敏、不含正文与密钥）；下一次调用覆盖。
|
||
HJ_API const char *hj_last_error(void);
|
||
|
||
// ===== 脾神（hj_transform）：Markdown → canonical ContentBlock 确定性解析 =====
|
||
|
||
// 返回当前 parser version（稳定标识，随实现演进递增）。
|
||
HJ_API const char *hj_transform_version(void);
|
||
|
||
// 将 Markdown 规范化为 canonical ContentBlock JSON（键序确定、UTF-8）。
|
||
// 输出经 HjBuffer 返回，由 hj_buffer_free 释放；blocks 不含 id（由宿主生成）。
|
||
// 限额与非法 UTF-8 分别返回 HJ_ERR_LIMIT_EXCEEDED / HJ_ERR_INVALID_ARGUMENT。
|
||
HJ_API HjStatus hj_transform_markdown(
|
||
HjEngine *engine, const char *input, size_t input_len, HjBuffer **out);
|
||
|
||
#ifdef __cplusplus
|
||
} // extern "C"
|
||
#endif
|
||
|
||
#endif // HUNJING_LINGTAI_H
|