// 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