AllasCode Intitute / FullAgenticStack: The Intent-Based Router

AllasCode Institute / FullAgenticStack: The Intent-Based Router

Specification: The Intent-Based Router
Status: Draft / Experimental
Version: 1.0.0
Context: AllasCode Institute / FullAgenticStack
Package: @allascodeintitute/routes2gateway

规范： 基于意图的路由器 (Intent-Based Router)
状态： 草案 / 实验性
版本： 1.0.0
上下文： AllasCode Institute / FullAgenticStack
包： @allascodeintitute/routes2gateway

Abstract: The Intent-Based Router is an API execution engine that prioritizes client intent over the syntactic precision of the request. Unlike traditional deterministic routers that operate on binary logic (Success/404 Error/400 Error), this router implements a layer of fuzzy logic and self-healing heuristics. It assumes that protocol, route, or data structure failures are, in most cases, intent translation problems, and attempts to resolve them autonomously before rejecting the request.

摘要： “基于意图的路由器”是一个 API 执行引擎，它将客户端的“意图”置于请求的语法精确度之上。与基于二进制逻辑（成功/404 错误/400 错误）运行的传统确定性路由器不同，该路由器实现了一层模糊逻辑（fuzzy logic）和自愈启发式算法。它假设协议、路由或数据结构故障在大多数情况下是意图翻译问题，并尝试在拒绝请求之前自主解决这些问题。

1. Routing Heuristics (Route Healing)

The router intercepts route resolution failures (404/405) and applies search algorithms to find the probable destination.

1. 路由启发式算法（路由自愈）

路由器会拦截路由解析失败（404/405），并应用搜索算法来寻找可能的目的地。

2.1. Fuzzy Path Matching: If the exact route is not found, the router calculates the Levenshtein distance between the requested URL and the registered routes.

Scenario: Client requests POST /api/v1/usres (Typo).
Action: Router detects 90% similarity with /api/v1/users.
Resolution: Internally redirects the request to the users handler and adds a warning header: X-Intent-Correction: redirected-from-typo.

2.1. 模糊路径匹配： 如果未找到确切路由，路由器将计算请求 URL 与已注册路由之间的莱文斯坦距离（Levenshtein distance）。

场景： 客户端请求 POST /api/v1/usres（拼写错误）。
操作： 路由器检测到与 /api/v1/users 的相似度为 90%。
解析： 在内部将请求重定向到用户处理程序，并添加警告头：X-Intent-Correction: redirected-from-typo。

2.2. Method Inference: Resolves common HTTP verb errors (405 Method Not Allowed) based on payload analysis.

Scenario: Client sends GET /users/create with a JSON Body.
Analysis: GET requests should not have a semantic body, but the intent is clearly creation.
Action: The router transmutes the request to POST /users if that route exists and accepts the provided payload.

2.2. 方法推断： 基于负载分析解决常见的 HTTP 动词错误（405 Method Not Allowed）。

场景： 客户端发送带有 JSON Body 的 GET /users/create。
分析： GET 请求不应包含语义主体，但其意图显然是创建。
操作： 如果该路由存在并接受提供的负载，路由器会将请求转换为 POST /users。

2.3. Semantic Version Fallback: Allows clients to consume deprecated routes or non-existent future versions without breaking.

Scenario: Client requests /api/v3/products (does not exist yet).
Action: The router identifies that the most stable version is v2, verifies if the contract is compatible, and serves the v2 response with a Deprecation or Version-Mismatch warning.

2.3. 语义版本回退： 允许客户端在不中断的情况下使用已弃用的路由或尚不存在的未来版本。

场景： 客户端请求 /api/v3/products（尚不存在）。
操作： 路由器识别出最稳定的版本是 v2，验证契约是否兼容，并提供 v2 的响应，同时附带 Deprecation 或 Version-Mismatch 警告。

3. Data Self-Healing (Payload Healing)

Implements the robustness principle (Postel’s Law) by semantically analyzing the request body and parameters (Query/Params).

3. 数据自愈（负载自愈）

通过对请求体（Body）和参数（Query/Params）进行语义分析，实现鲁棒性原则（波斯塔尔法则，Postel’s Law）。

3.1. Semantic Field Mapping: The router uses a reverse semantic dictionary to correct incorrect field names in the JSON payload.

Mechanism: Upon receiving a schema validation error (e.g., “missing field email”), the router scans the received payload for semantically equivalent fields (e_mail, mail, emailAddress).
Healing: If found, the field is renamed in memory and validation is re-executed.

3.1. 语义字段映射： 路由器使用反向语义字典来纠正 JSON 负载中不正确的字段名称。

机制： 在收到模式验证错误（例如：“missing field email”）时，路由器会扫描接收到的负载，寻找语义等效的字段（e_mail、mail、emailAddress）。
修复： 如果找到，该字段将在内存中重命名，并重新执行验证。

3.2. Structural Flattening & Hoisting: Corrects nesting errors in JSON.

Scenario: The API expects { "userId": 123 }, but the client sends { "data": { "user": { "id": 123 } } }.
Action: The router detects the excessive nesting pattern and “hoists” the deep properties to the root level expected by the Schema, based on data types.

3.2. 结构扁平化与提升： 纠正 JSON 中的嵌套错误。

场景： API 期望 { "userId": 123 }，但客户端发送了 { "data": { "user": { "id": 123 } } }。
操作： 路由器检测到过度嵌套模式，并根据数据类型将深层属性“提升”（hoist）到 Schema 预期的根级别。

3.3. Intelligent Type Coercion: Goes beyond simple string-to-number coercion.

Scenario: Boolean field isActive receives string “sim” or “enabled”.
Action: The router interprets positive semantic values in pt-BR/en-US as true.

3.3. 智能类型强制转换： 超越简单的字符串到数字的转换。

场景： 布尔字段 isActive 接收到字符串 “sim” 或 “enabled”。
操作： 路由器将 pt-BR/en-US 中的肯定语义值解释为 true。

4. HTTP Protocol Correction (Protocol Healing)

The router acts as an intelligent reverse proxy for itself, correcting failures in the transport and session layers.

4. HTTP 协议纠正（协议自愈）

路由器充当自身的智能反向代理，纠正传输层和会话层的故障。

4.1. Rate Limit Negotiation (429):

Trigger: The handler or an upstream service returns 429 Too Many Requests.
Heuristic: The router reads the Retry-After header. If the time is acceptable (within configured SLA, e.g., < 2s), it holds the request in a memory buffer. It emits status 102 Processing to the client (if in AON mode) and executes the request again after the wait time.

4.1. 速率限制协商 (429)：

触发： 处理程序或上游服务返回 429 Too Many Requests。
启发式： 路由器读取 Retry-After 头。如果时间在可接受范围内（在配置的 SLA 内，例如 < 2秒），它会将请求保留在内存缓冲区中。它向客户端发出 102 Processing 状态（如果处于 AON 模式），并在等待时间后重新执行请求。

4.2. Idempotency Assurance: To avoid side effects in healing retries (especially in POST/PUT), the router automatically generates and manages idempotency keys (Idempotency-Key), ensuring that healing does not duplicate transactions in the database.

4.2. 幂等性保证： 为避免在修复重试中产生副作用（特别是在 POST/PUT 中），路由器会自动生成并管理幂等键（Idempotency-Key），确保修复操作不会在数据库中重复执行事务。

Intent Telemetry (AON Integration)

All healing actions generate telemetry events specific to the Adaptive Observability Negotiation standard.

intent.route_corrected: “Redirected from /usres to /users”
intent.data_healed: “Field ‘mail’ mapped to ‘email’”
intent.protocol_fixed: “JWT token automatically renewed”

意图遥测 (AON 集成)

所有修复操作都会生成特定于“自适应可观测性协商”（Adaptive Observability Negotiation）标准的遥测事件。

intent.route_corrected: “从 /usres 重定向到 /users”
intent.data_healed: “字段 ‘mail’ 映射到 ‘email’”
intent.protocol_fixed: “JWT 令牌自动续期”