hunjing/engine/proto/liushen/v1/liushen.proto

syntax = "proto3";

package liushen.v1;

// 灵台引擎独立服务形态（契约 docs/contracts/lingtai-service.md）。
// 部署内部网络专用；错误映射见契约第 6 节。字段语义与进程内 C ABI JSON 边界同源。

service LingtaiEngine {
  // 版本、ABI major、parser version、能力位
  rpc GetEngineInfo(GetEngineInfoRequest) returns (GetEngineInfoResponse);

  // Markdown → canonical ContentBlock JSON
  rpc TransformMarkdown(TransformMarkdownRequest) returns (TransformMarkdownResponse);

  // canonical Block → 可移植 Markdown 重建（预留：实现随 WP-03 导出）
  rpc RebuildExport(RebuildExportRequest) returns (RebuildExportResponse);

  // 双向流：宿主喂增量，服务回 content.block.* envelope JSON
  rpc OpenStream(stream StreamFrame) returns (stream StreamEvent);

  // 计划 DAG 预算核算（最小：标量预算）
  rpc CheckBudget(CheckBudgetRequest) returns (CheckBudgetResponse);

  // 候选确定性重排
  rpc RerankRecall(RerankRecallRequest) returns (RerankRecallResponse);

  // 四维裁决（autonomy × risk）
  rpc EvaluatePolicy(EvaluatePolicyRequest) returns (EvaluatePolicyResponse);

  // URL 协议白名单校验
  rpc ValidateUrl(ValidateUrlRequest) returns (ValidateUrlResponse);

  // Run/Turn 状态转换合法性
  rpc CheckStateTransition(CheckStateTransitionRequest) returns (CheckStateTransitionResponse);
}

message GetEngineInfoRequest {}

message GetEngineInfoResponse {
  uint32 abi_major = 1;
  string parser_version = 2;
  string engine_version = 3;
  repeated string capabilities = 4;
}

message TransformMarkdownRequest {
  string markdown = 1;
}

message TransformMarkdownResponse {
  string canonical_json = 1;  // canonical ContentBlock JSON（键序确定）
}

message RebuildExportRequest {
  string canonical_json = 1;
}

message RebuildExportResponse {
  string markdown = 1;
}

message StreamFrame {
  oneof frame {
    string block_started = 2;   // block_id：开启新 block（重置 delta_index）
    string text_delta = 3;      // 文本增量
  }
}

message StreamEvent {
  string event_json = 1;  // content.block.* envelope（canonical JSON）
}

message CheckBudgetRequest {
  int64 used = 1;
  int64 maximum = 2;
}

message CheckBudgetResponse {
  bool allowed = 1;
  string reason = 2;
}

message RerankRecallRequest {
  string candidates_json = 1;
}

message RerankRecallResponse {
  string ranked_json = 1;
}

message EvaluatePolicyRequest {
  int32 autonomy_level = 1;  // 0 自省 / 1 循律 / 2 请命 / 3 禁域
  int32 risk_level = 2;      // 0 只读 / 1 副作用 / 2 高影响
}

message EvaluatePolicyResponse {
  int32 decision = 1;  // 0 allow / 1 ask / 2 deny
}

message ValidateUrlRequest {
  string url = 1;
}

message ValidateUrlResponse {
  bool allowed = 1;
  string reason = 2;
}

enum RunStatus {
  RUN_STATUS_UNSPECIFIED = 0;
  RUN_STATUS_QUEUED = 1;
  RUN_STATUS_RUNNING = 2;
  RUN_STATUS_WAITING_APPROVAL = 3;
  RUN_STATUS_COMPLETED = 4;
  RUN_STATUS_FAILED = 5;
  RUN_STATUS_CANCELLED = 6;
}

message CheckStateTransitionRequest {
  RunStatus from = 1;
  RunStatus to = 2;
}

message CheckStateTransitionResponse {
  bool valid = 1;
  string reason = 2;
}