# Lingtai Service

灵台引擎独立服务形态的 gRPC 契约。本文件是服务方法、错误映射与形态边界的登记处；机器化前以本文件为命名基线，机器化后以 `proto/lingtai/v1/lingtai.proto` 为真源。进程内形态契约见 [Lingtai C ABI](lingtai-ffi.md)；架构语义见[灵台引擎架构](../architecture/lingtai-engine.md)。

## 1. 适用范围与稳定性

- 消费方：同一部署内的 FastAPI 宿主、Worker、Go 网关与经部署者授权的内部系统。这是**部署内部契约**，不进入 `api.<domain>`/`gateway.<domain>` 公共分面，不经公共网关暴露，不向最终用户承诺稳定性。
- proto 按 protobuf 官方演进纪律：不修改既有字段编号与类型，新增字段由消费方忽略；破坏性变更升 `v2` 包，并行维护一个旧包的最短过渡期。
- 服务无权威状态：任何方法被路由到任一实例结果一致；实例可水平扩缩，无会话粘滞（流式方法除外，见第 5 节）。

## 2. 命名

| 对象 | 规则 | 示例 |
| --- | --- | --- |
| proto 包 | `lingtai.v<major>` | `lingtai.v1` |
| 服务 | `LingtaiEngine` | `lingtai.v1.LingtaiEngine` |
| 方法 | 模块职责 + 动词 | `TransformMarkdown`、`EvaluatePolicy` |
| 消息 | 请求/响应后缀 | `TransformMarkdownRequest` |
| 二进制 | `hunjing-lingtai-server` | 监听部署内部地址 |

字段命名使用 `snake_case`，与 [协议与稳定标识](README.md) 一致；消息字段语义与 C ABI 的 JSON 边界（[统一富内容与流式协议](content-blocks-and-streaming.md)）同源，不另造字段语义。

## 3. 能力与方法

| 方法 | 对应子系统 | 语义 |
| --- | --- | --- |
| `GetEngineInfo` | `hj_core` | 版本、ABI major、parser version、能力位 |
| `TransformMarkdown` | `hj_transform` | Markdown → canonical ContentBlock 列表（含 parser version） |
| `RebuildExport` | `hj_transform` | canonical Block → 可移植 Markdown 重建 |
| `OpenStream` | `hj_stream` | 双向流：宿主喂增量，服务回 `content.block.*` 事件 envelope |
| `ValidatePlan` | `hj_plan` | 计划 DAG 校验、拓扑排序与预算核算 |
| `AssembleContext` | `hj_plan` | Context Manifest 裁剪与优先级排序计算 |
| `RerankRecall` | `hj_recall` | 多路检索结果重排与合并（服务形态能力） |
| `EvaluatePolicy` | `hj_policy` | Schema/路径/URL 校验、验签、幂等键规范化、决策表评估 |
| `CheckStateTransition` | `hj_core` | Run/Turn 状态转换合法性校验 |

- 形态边界登记：`hj_recall` 的离线索引文件 mmap 仅进程内形态可用；服务形态只提供 `RerankRecall` 等 CPU 计算部分。新增单形态能力必须在本表登记。
- 所有请求携带调用方声明的限额（长度/深度/预算）；服务端按部署配置二次钳制，取两者较小值。

## 4. 传输与认证

- 仅监听部署内部网络；TLS 必启，客户端与服务端双向 mTLS，证书由部署内部 CA 签发。
- 认证是工作负载身份（客户端证书/SPIFFE 类标识），不是用户凭据；用户级授权判定在宿主完成后才调用引擎，引擎不重复也不绕过用户授权。
- 不存在匿名访问；未经认证连接在握手阶段断开并记审计。
- 部署元数据（trace 上下文）经 gRPC metadata 传播，与 `traceparent` 语义一致；业务请求 ID 由宿主透传，服务不生成权威 ID。

## 5. 流式语义

- `OpenStream` 为双向流：客户端按序发送增量帧，服务端按序返回事件 envelope；事件带 `sequence` 与 `delta_index`，语义与 C ABI 回调一致。
- 一条流绑定一个服务端会话句柄；流中断（网络/超时）后会话丢弃，客户端以最终权威数据重放重建，不依赖半程状态。
- 背压：服务端按配置的内存水位暂停读取；客户端必须在水位恢复前停止发送，不得假设无限缓冲。

## 6. 错误映射

`HjStatus`（[Lingtai C ABI](lingtai-ffi.md)）到 gRPC status 的映射：

| `HjStatus` | gRPC code |
| --- | --- |
| `HJ_OK` | `OK` |
| `HJ_ERR_INVALID_ARGUMENT` / `HJ_ERR_PARSE_FAILED` | `INVALID_ARGUMENT` |
| `HJ_ERR_LIMIT_EXCEEDED` | `OUT_OF_RANGE` 或 `RESOURCE_EXHAUSTED`（按限额类型） |
| `HJ_ERR_POLICY_DENIED` / `HJ_ERR_SIGNATURE_INVALID` | `FAILED_PRECONDITION` 或 `PERMISSION_DENIED`（按调用语义） |
| `HJ_ERR_INDEX_CORRUPT` | `DATA_LOSS`（要求重建索引） |
| `HJ_ERR_UNSUPPORTED_ABI` | `UNIMPLEMENTED` |
| `HJ_ERR_OUT_OF_MEMORY` / `HJ_ERR_INTERNAL` | `INTERNAL` |
| `HJ_ERR_HANDLE_INVALID` / `HJ_ERR_REENTRANCY` | `INTERNAL`（进程内契约，服务面不应出现） |

- 服务自身的基础设施错误（不可达、超时、认证失败、过载）使用标准 gRPC code：`UNAVAILABLE`、`DEADLINE_EXCEEDED`、`UNAUTHENTICATED`、`UNAVAILABLE`（过载）。
- 错误 detail 不包含请求正文、密钥或凭据；宿主对 `UNAVAILABLE`/`DEADLINE_EXCEEDED` 的重试由 gRPC 重试策略统一配置，计算方法无副作用、可安全重试。

## 7. 禁令清单

- 不得把本服务经公共网关或 `api.<domain>` 暴露给外部调用方。
- 不得在服务面引入用户身份认证或授权判定（那是宿主与 Policy Core 的职责）。
- 不得让任何方法在服务形态与进程内形态产生不同语义；发现分歧按缺陷处理并以 golden 测试复现。
- 不得绕过 `GetEngineInfo` 的版本/能力协商硬编码猜测方法行为。
- 不得将引擎错误消息原样透传给最终用户；错误本地化由宿主完成。