REST API 认知控制与资源契约

为了实现多租户智能体（Agent）资源的精细化生命周期准入控制 (Admission Control)，以及私有化商业许可管理，VecminDB 对外提供了统一的 REST 接口层。接口层基于 Actix-web 构建，配有严格的 RBAC 角色鉴权中间件以及资源开销熔断拦截器。

1. 全局 API 响应与错误契约

所有接口均采用统一响应封装结构 ApiResponse<T>：

1.1 成功响应 JSON 骨架

{
  "success": true,
  "data": {
    "max_qps": 100.0,
    "max_memory_bytes": 1073741824,
    "max_cpu_ratio": 0.5
  },
  "error": null
}

1.2 错误响应 JSON 骨架

{
  "success": false,
  "data": null,
  "error": {
    "message": "License expired. Please upgrade at https://vecmindb.com/pricing",
    "code": 402
  }
}

2. 智能体运行配额控制 (Agent Admission & Quotas)

2.1 获取/热更新智能体配额

获取配额 (GET): /api/v1/agents/{agent_id}/quota
修改配额 (PUT): /api/v1/agents/{agent_id}/quota

底层同步与覆盖机制：为了确保动态修改在数据库发生故障崩溃后不丢失，系统会先通过 ResourceManager 锁更新配额，接着异步在通道分发热限制，最后调用 to_yaml_file 将其同步改写进主配置 config.yml 与隐藏的粘性运行配置 .vecmin.runtime.yml 中。

2.2 获取运行状态与遥测 (GET)

路由: /api/v1/agents/{agent_id}/stats
响应结构：返回智能体标识、当前计算配额、以及后台未决的记忆晋升数（pending_promotions）。

3. 大脑商业许可 (License Control) API

许可状态 (GET): /api/v1/license/status —— 返回当前许可的激活阶段 (trial, active, expired)、剩余天数及最大限制。
离线激活 (POST): /api/v1/license/activate —— 提供 activation_key。系统调用 verify_activation_key 执行 Ed25519 公钥签名解密，并启动 SovereigntyAuditor::log_access 写入不可篡改的防盗版审计链日志。
邮箱注册与 OTA 校准 (POST): /api/v1/license/register & /api/v1/license/sync —— 提供在线更新续期和主动证书再对齐通道。
反馈回传 (POST): /api/v1/license/feedback —— 使用 VECMIN_ACCOUNT_TOKEN 将加密反馈回传至授权服务器 https://license.lingxinmind.com。

4. 认知网络拦截器与 HTTP 状态码矩阵

在中间件 AdmissionControl 拦截管道中，如智能体行为违反资源配额、安全边界或商业限制，会抛出特定状态码：

HTTP 状态码	拦截器判定类型	触发业务场景与错误信息示例	业务应对与恢复路径
402 Payment Required	License过期或越界	1. 证书过期: `"License expired..."` 2. 宽限期限制写操作: `"License grace period: writes are frozen..."` 3. 注册实例超限: `"License limit exceeded..."`	1. 续费获取新 Activation Key； 2. 使用 `/license/activate` 离线激活； 3. 或使用 `/license/sync` 主动作 OTA 校准。
403 Forbidden	鉴权失败或越权	1. 凭证缺失或伪造: `"Forbidden: Missing or invalid API Key..."` 2. 越权探测: `"Forbidden: RBAC permission denied."` (只读角色试图写入)	1. 检查 Header 中的 `x-api-key` 或 `Authorization: Bearer` 令牌； 2. 验证 API Key 权限等级。
429 Too Many Requests	QPS/内存配额限流	1. 并发超出: `"Admission Control DENIED: QPS quota exceeded"` 2. 内存超载保护: `"Memory quota exceeded"`	1. 发起调用时执行指数避退退避策略 (Exponential Backoff)； 2. 管理员通过 `PUT /quota` 接口调大该智能体的计算边界限制。

REST API Cognitive Control & Resource Contract

To enforce multi-tenant Agent resource Admission Control and manage commercial OTA licensing, VecminDB exposes a unified REST interface. Built on Actix-web, it implements strict RBAC middlewares and resource circuit breakers.

1. Global API Response & Error Contract

Every REST endpoint encapsulates responses in a structured ApiResponse<T> envelope:

1.1 Success JSON Response Schema

{
  "success": true,
  "data": {
    "max_qps": 100.0,
    "max_memory_bytes": 1073741824,
    "max_cpu_ratio": 0.5
  },
  "error": null
}

1.2 Error JSON Response Schema

{
  "success": false,
  "data": null,
  "error": {
    "message": "License expired. Please upgrade at https://vecmindb.com/pricing",
    "code": 402
  }
}

2. Agent Admission & Quotas

2.1 Manage Quotas (GET / PUT)

Fetch (GET): /api/v1/agents/{agent_id}/quota
Modify (PUT): /api/v1/agents/{agent_id}/quota

Underlying Persistence: Updates acquire memory write-locks via ResourceManager, dispatch changes through async commands, and call to_yaml_file to overwrite static config.yml and hidden sticky .vecmin.runtime.yml configurations, ensuring survivability during host crashes.

2.2 Fetch Stats (GET)

Route: /api/v1/agents/{agent_id}/stats
Response: Returns agent specifications, active quotas, and pending memory promotion counts (pending_promotions).

3. Commercial License APIs

License Status (GET): /api/v1/license/status —— Outputs licensing state (trial, active, expired) and node/agent boundaries.
Offline Activation (POST): /api/v1/license/activate —— Validates Base64URL-encoded signatures using the embedded Ed25519 key and logs actions into the tamper-proof ledger via SovereigntyAuditor::log_access.
Register & Synchronize (POST): /api/v1/license/register & /api/v1/license/sync —— Auto-triggers background OTA synchronizations with the remote portal.

4. Middleware Admission & HTTP Status Codes

The AdmissionControl middleware intercepts operations violating quotas or licensing parameters:

HTTP Code	Decision Filter	Triggers & Error Message Examples	Recovery Actions
402 Payment Required	License expired / boundaries crossed	1. Expiry: `"License expired..."` 2. Write block: `"License grace period: writes are frozen..."` 3. Agent bloat: `"License limit exceeded..."`	1. Renew subscription; 2. Feed key using `/license/activate`; 3. Trigger OTA synchronization via `/license/sync`.
403 Forbidden	Authentication / RBAC denial	1. Missing key: `"Forbidden: Missing or invalid API Key..."` 2. RBAC mismatch: `"Forbidden: RBAC permission denied."` (Viewer role trying to write)	1. Verify `x-api-key` or `Authorization: Bearer` headers; 2. Confirm API Key permissions.
429 Too Many Requests	QPS / Memory rate limiting	1. QPS spikes: `"Admission Control DENIED: QPS quota exceeded"` 2. Memory overhead: `"Memory quota exceeded"`	1. Implement Exponential Backoff on clients; 2. Elevate limits dynamically using `PUT /quota`.