@jsonstudio/rcc 0.89.1348 → 0.89.1488

package/docs/llms-wasm-replay-baseline.md

@@ -0,0 +1,171 @@
+---
+title: "llms-wasm 基线回放集（Replay Baseline）"
+tags:
+  - wasm
+  - migration
+  - baseline
+status: planning
+created: 2026-01-26
+---
+
+# llms-wasm 基线回放集（Replay Baseline）
+
+> [!important] 目标
+> 构建可重复、可回溯、可脱敏的基线回放集，用于 TS/WASM 双跑对比与差异修复闭环。
+
+---
+
+## 1. 采样策略（Sampling Strategy）
+
+> [!tip] 分层覆盖
+> 采样应覆盖 **模型 / 工具 / 路由 / SSE** 的典型场景，并保留长尾样本用于发现边界差异。
+
+### 1.1 样本分层
+
+- **模型维度**：高频模型 + 长尾模型（至少覆盖每个 provider 的主力模型）
+- **工具维度**：tool_calls + function_call + 无工具场景
+- **路由维度**：主路 / failover / alias 切换 / 冷却恢复
+- **SSE 维度**：流式 chunk（含拆包差异）+ 非流式 response
+
+### 1.2 采样比例（建议）
+
+- 全量采样：0.1% - 1%（按租户/路由分层）
+- 长尾采样：按错误率/差异率动态加权
+- 基线回放集：固定 1000 - 5000 条稳定样本
+
+### 1.3 采样触发条件
+
+- diff 率升高时：自动提高该模块采样比例
+- 新版本发布时：额外采样并标记 `build_version`
+- 关键模块切换阶段（shadow → canary → default）：强制采样
+
+---
+
+## 2. 存储格式（Storage Format）
+
+> [!warning] 必须可脱敏
+> 所有字段必须经过 PII/密钥脱敏；存储结构必须保持可重放。
+
+### 2.1 基线记录结构（JSON）
+
+```json
+{
+  "request_id": "req_123",
+  "tenant": "tenant_a",
+  "route": "route_main",
+  "timestamp": "2026-01-26T10:00:00Z",
+  "request": {
+    "endpoint": "/v1/chat/completions",
+    "payload": {"...": "..."}
+  },
+  "response": {
+    "status": 200,
+    "payload": {"...": "..."}
+  },
+  "metadata": {
+    "provider": "anthropic",
+    "model": "claude-3-5",
+    "compatibility_profile": "chat-gemini",
+    "runtime_main": "ts",
+    "runtime_shadow": "wasm"
+  }
+}
+```
+
+### 2.2 索引字段
+
+- `request_id`
+- `tenant`
+- `route`
+- `provider`
+- `model`
+- `compatibility_profile`
+- `timestamp`
+
+---
+
+## 3. 脱敏规则（Data Sanitization）
+
+> [!important] 不可逆脱敏
+> PII 与 secrets 必须不可逆处理；但结构必须保持一致以保证重放。
+
+### 3.1 PII 处理
+
+- 字段值 → hash + mask
+- 保留结构与字段名
+
+示例：
+
+```json
+{
+  "user_email": "sha256:***",
+  "user_name": "sha256:***"
+}
+```
+
+### 3.2 Secrets 处理
+
+- API keys / tokens：完全移除
+- 如果必需存在：替换为固定占位符 `"__redacted__"`
+
+---
+
+## 4. 基线版本快照字段
+
+> [!note] 版本快照必须固定
+> 回放时必须明确 TS/WASM/ruleset 版本，以保证对比可复现。
+
+### 4.1 必含字段
+
+- `ts_version`（@jsonstudio/llms 版本）
+- `wasm_version`（llms-wasm 版本）
+- `ruleset_version`（diff ruleset 版本）
+- `compat_profile_version`（compat profile 版本）
+- `sse_protocol_version`（SSE 协议版本）
+
+示例：
+
+```json
+{
+  "ts_version": "0.6.1172",
+  "wasm_version": "0.1.0",
+  "ruleset_version": "diff_ruleset_v1",
+  "compat_profile_version": "compat_profiles_v1",
+  "sse_protocol_version": "sse_protocol_v1"
+}
+```
+
+---
+
+## 5. 回放执行（Replay Runner）
+
+> [!tip] 回放方式
+> 优先离线回放；如需线上验证，必须隔离生产主路。
+
+### 5.1 离线回放
+
+- 输入固定基线集
+- 输出 diff 结果
+- 自动归因到模块（compat / logic / nondeterministic）
+
+### 5.2 线上回放（可选）
+
+- 影子模式执行
+- 只记录 diff 摘要
+- 不影响主路
+
+---
+
+## 6. 保留策略
+
+- **全量回放集**：7-14 天
+- **采样摘要**：30-90 天
+- **历史归档**：按版本归档
+
+---
+
+## 相关文档
+
+- [[docs/llms-wasm-migration.md]] - 迁移计划概要
+- [[docs/plans/llms-wasm-migration-plan.md]] - 可执行清单
+- [[docs/llms-wasm-module-boundaries.md]] - 模块边界清单

package/docs/plans/llms-wasm-migration-plan.md

@@ -0,0 +1,401 @@
+---
+title: "llms-wasm 逐步替换迁移计划"
+tags:
+  - migration
+  - wasm
+  - architecture
+status: planning
+priority: high
+created: 2026-01-26
+owners:
+  - name: RouteCodex Team
+    role: Architecture
+---
+
+# llms-wasm 逐步替换迁移计划
+
+> [!important] 核心目标
+> 让 llms-wasm 和 llms TS 同时加载、同一请求可双跑；默认流量仍走 TS，WASM 跑影子并产出 diff；diff 可回溯、可修正；按模块逐步替换并具备清晰的验收与回滚开关。
+
+## 成功指标（建议起始阈值）
+
+- diff rate ≤ 0.5%（按模块可更严格）
+- shadow error rate ≤ 0.1%（影子侧）
+- P95 latency delta ≤ +10ms（主路 vs 基线）
+
+> [!note] 统计口径
+> 指标必须按 `tenant`、`route`、`module`、`runtime(ts|wasm)` 分维度统计，并支持按 ruleset 版本回溯。
+
+---
+
+## 阶段 0：边界与基线
+
+### 0.1 模块边界清单（Contract + 归属）
+
+> [!tip] 产出物
+> 输出一份“模块边界清单”，用于：替换顺序、归因、验收与回滚。
+
+| 模块 | 输入 Contract | 输出 Contract | Owner/修复路径 | 仓库归属 |
+|---|---|---|---|---|
+| tokenizer/encoding | `text` | `tokens` | wasm core | llmswitch-core |
+| tool canonicalization | `ToolCallRaw[]` | `ToolCallCanonical[]` | wasm core | llmswitch-core |
+| compat | `UpstreamResponse` | `CanonicalResponse` | compat adapter | llmswitch-core |
+| streaming (SSE) | `SSEChunk[]` | `CanonicalSSEEvents[]` | wasm core | llmswitch-core |
+| routing | `RequestContext` | `ProviderTarget` | wasm core | llmswitch-core |
+
+> [!note] 依赖顺序
+> `tokenizer → tools → routing → compat → streaming`（可按实际代码调整，但必须写入清单）。
+
+**任务清单**：
+
+- [ ] 产出模块边界清单文档（`docs/llms-wasm-module-boundaries.md`）
+- [ ] 定义每个模块的输入/输出 Contract（TypeScript interface）
+- [ ] 明确依赖顺序与替换优先级
+- [ ] 确认 Owner/修复路径（wasm core vs compat adapter）
+
+> [!important] 本轮补充要求（阶段 0 必须落地）
+> - **统一 tokenizer**：整理成单一实现与单一入口（single source of truth）。
+> - **统一 SSE event 协议**：定义唯一 canonical SSE event schema + diff 协议（event + token 级）。
+> - **统一 compat profile**：在 llmswitch-core 统一定义、版本化、并成��唯一触发来源。
+
+### 0.2 基线回放集（Replay Baseline）
+
+- 固定请求集：覆盖典型模型/工具/路由/SSE 场景
+- 固定版本快照：记录 TS 与 WASM 的版本号 + core ruleset 版本
+- 回放方式：离线 replay + 线上 sampled replay（可选）
+
+> [!important] 回放基线必须可重复
+> - 输入需要脱敏但可复现（结构不变）
+> - 影子侧必须能独立重放同一请求（同版本、同 ruleset）
+
+**任务清单**：
+
+- [ ] 设计回放集采样策略（覆盖典型场景）
+- [ ] 实现回放集存储格式（JSON + 脱敏）
+- [ ] 实现回放 runner（支持离线 replay）
+- [ ] 建立 baseline 版本管理（TS/WASM/ruleset 版本号）
+
+---
+
+## 阶段 1：双加载 + 开关矩阵
+
+### 1.1 双加载初始化
+
+- TS runtime：当前 `@jsonstudio/llms`（TS）
+- WASM runtime：`llms-wasm`
+- 目标：同进程内并存、互不影响、初始化失败可降级（不 silent fallback；需上报错误）
+
+> [!warning] Fail fast + 可观测
+> WASM 初始化失败必须走 `providerErrorCenter` + `errorHandlingCenter` 上报；主路仍按模式走 TS。
+
+**任务清单**：
+
+- [ ] Host 实现双加载初始化（`src/server/runtime/http-server/dual-runtime.ts`）
+- [ ] WASM 初始化失败上报（通过 `providerErrorCenter`）
+- [ ] 验证双加载互不影响（隔离测试）
+
+### 1.2 运行模式
+
+- `ts_primary`：主路 TS（默认）
+- `shadow`：主路 TS，WASM 影子
+- `wasm_primary`：主路 WASM，TS 影子
+- `split`：按比例分流（用于逐步切流）
+
+**任务清单**：
+
+- [ ] 定义 RuntimeMode 类型与枚举
+- [ ] 实现模式切换逻辑（Host 侧）
+
+### 1.3 开关优先级与作用域
+
+> [!important] 优先级（强制）
+> 全局 > 租户 > 路由 > 请求
+
+| 作用域 | 示例 | 说明 |
+|---|---|---|
+| 全局（进程级） | env `ROUTECODEX_WASM_MODE=shadow` | 默认行为 |
+| 租户级 | config `tenants[*].wasmMode` | 覆盖全局 |
+| 路由级 | virtual router `routes[*].wasmMode` | 覆盖租户 |
+| 请求级 | header `X-WASM-Mode: wasm_primary` | 单次请求 override |
+
+> [!note] 开关读取位置
+> Host 只做“读取与决策分发”；具体逻辑执行（含 canonicalization、diff 协议）在 llmswitch-core。
+
+**任务清单**：
+
+- [ ] 实现开关读取逻辑（Host 侧）
+- [ ] 实现优先级解析（全局 > 租户 > 路由 > 请求）
+- [ ] 更新配置 schema（支持 wasmMode 字段）
+- [ ] 文档化开关优先级矩阵
+
+---
+
+## 阶段 2：影子 + Diff 机制（含 SSE 协议）
+
+### 2.1 影子请求分发
+
+- 主路请求正常执行
+- 影子请求异步执行（不阻塞主路响应）
+- 影子失败不重试（默认）；如需重试必须可配置且有预算（error budget）
+
+**任务清单**：
+
+- [ ] Host 实现影子请求分发（异步、非阻塞）
+- [ ] 影子失败记录（error 摘要，不影响主路）
+- [ ] 实现影子重试配置（可选，带 error budget）
+
+### 2.2 Diff 协议与 Canonicalization（在 llmswitch-core）
+
+> [!warning] Canonicalization 归属
+> 所有 canonicalization、diff ruleset、比较逻辑都必须在 llmswitch-core；Host 不做字段修补。
+
+#### 通用 Diff 规则（降噪）
+
+- 排除/标准化：`timestamp`、随机 id、trace id 等
+- 容忍策略：浮点容忍、集合无序、JSON 格式化
+- 非确定性：白名单 + ruleset 版本化（见附录 A）
+
+#### SSE 对比协议（event + token）
+
+> [!tip] 核心原则
+> 允许 chunk 拆包差异，但要求最终 token 序列一致；对比基于 event-level schema。
+
+Canonical event schema：
+
+- `event_type`
+- `ordinal_index`
+- `normalized_payload`
+- `token_digest`（可选，用于 token 级校验）
+
+判定逻辑：
+
+- event 序列可容忍“拆包导致的分段差异”
+- 最终 token_digest 序列一致则通过
+- 失败时输出最小 diff 摘要（added/removed/mismatch）
+
+**任务清单**：
+
+- [ ] 实现通用 Diff 规则（降噪、容忍策略）
+- [ ] 实现 SSE canonicalization schema
+- [ ] 实现 SSE diff 判定逻辑（event + token 级）
+- [ ] 实现 diff ruleset 版本化（`diff_ruleset_v1`）
+
+### 2.3 Diff 记录（绑定 ruleset）
+
+每条 diff 必须包含：
+
+- `requestId` / `tenant` / `route`
+- `runtime_main` / `runtime_shadow`
+- `ruleset_version`
+- `diff_summary`（可索引）
+- `payload_refs`（可选：用于回放；存储时需脱敏）
+
+**任务清单**：
+
+- [ ] 设计 diff 记录 schema
+- [ ] 实现 diff 存储（索引 + 保留策略）
+- [ ] 实现脱敏规则（PII hash + mask，secrets 完全移除）
+- [ ] 实现 diff 查询接口（按 requestId/ruleset）
+
+---
+
+## 阶段 3：责任归属与修复路径
+
+### 3.1 责任归属表（Owner + Fix Location）
+
+> [!important] 修复入口
+> 所有 diff 必须能被归因到“修复路径”：`compat` vs `wasm core`（Host 永远不是修复入口）。
+
+| 模块 | Owner | 修复路径 | 入口函数/文件（示例） |
+|---|---|---|---|
+| tokenizer | @team/core | wasm core | `llmswitch-core/src/tokenizer/*` |
+| tools | @team/tools | wasm core | `llmswitch-core/src/tools/*` |
+| compat | @team/compat | compat adapter | `llmswitch-core/src/conversion/compat/*` |
+| streaming | @team/streaming | wasm core | `llmswitch-core/src/streaming/*` |
+| routing | @team/routing | wasm core | `llmswitch-core/src/routing/*` |
+
+**任务清单**：
+
+- [ ] 产出责任归属表（`docs/llms-wasm-ownership-table.md`）
+- [ ] 实现自动归因逻辑（diff → module + owner + fix location）
+
+### 3.2 修复闭环
+
+1. 影子 diff 收集 → 2. 分类（compat/logic/nondeterministic） → 3. 修复 → 4. 基线回放验证 → 5. diff 下降 → 6. 推进模块替换阶段
+
+**任务清单**：
+
+- [ ] 实现 diff 分类器（compat_issue / logic_bug / nondeterministic / data_quality）
+- [ ] 实现修复建议生成（自动推断 fix location）
+- [ ] 集成基线回放验证（修复后自动回归）
+- [ ] 实现 diff 下降趋势监控
+
+---
+
+## 阶段 4：模块级替换（shadow → canary → default）
+
+### 4.1 建议替换顺序（低风险 → 高风险）
+
+1. tokenizer/encoding
+2. tool canonicalization
+3. compat layer
+4. streaming response formatting (SSE)
+5. routing decision logic
+
+**任务清单**：
+
+- [ ] 确认替换顺序（风险评级）
+- [ ] 定义每个模块的验收阈值（diff rate / error rate / latency delta）
+- [ ] 定义观察期时长（shadow/canary/default）
+
+### 4.2 每个模块的替换 Gate
+
+> [!note] 状态机
+> `shadow → canary → default → deprecated → removed`
+
+- shadow：TS 主路，WASM 影子；跑满观察期（建议 1-2 周）
+- canary：WASM 主路小流量（5-10%），TS 影子；对稳定性最敏感
+- default：WASM 主路大流量（50-100%）；TS 影子可逐步关闭
+- deprecated：TS 保留 2-3 个 release 作为 fallback
+
+#### 验收门槛（示例，按模块调整）
+
+- diff rate：按模块设阈值（tokenizer 可到 0.01%，streaming 可到 0.5%）
+- error rate：≤ 0.1%（canary 阶段更严格）
+- latency delta：P95 ≤ +10ms（或按模块调整）
+
+**任务清单**：
+
+- [ ] 实现模块状态机（shadow/canary/default/deprecated）
+- [ ] 实现自动 gate 切换（满足阈值后自动推进）
+- [ ] 实现回滚触发器（diff 激增 / 错误率超阈值 / 性能降级）
+- [ ] 文档化每个模块的验收阈值
+
+---
+
+## 阶段 5：安全与可观测性
+
+### 5.1 必需指标
+
+- `diff_rate`（按 module/tenant/route/ruleset）
+- `shadow_error_rate`（按 runtime）
+- `latency_delta_p50/p95/p99`
+- `wasm_init_time` / `wasm_memory`
+
+**任务清单**：
+
+- [ ] 实现指标上报（通过 `providerErrorCenter` + `errorHandlingCenter`）
+- [ ] 实现指标分维度聚合（tenant/route/module/runtime/ruleset）
+- [ ] 实现指标查询接口（Prometheus/自定义）
+
+### 5.2 告警与 Error Budget
+
+- diff 突增（超过阈值 2x）
+- shadow error rate 超阈值
+- 主路延迟显著上升
+- WASM 初始化失败/崩溃
+
+> [!warning] 自动回滚建议
+> 若具备自动回滚能力：以“错误率 + 延迟 + diff 突增”作为触发器，回滚到 `ts_primary` 或回滚单模块。
+
+**任务清单**：
+
+- [ ] 实现告警规则配置（diff/error/latency/threshold）
+- [ ] 实现自动回滚触发器（单模块 / 全局）
+- [ ] 实现回滚开关（环境变量 + config）
+- [ ] 文档化告警与回滚流程
+
+---
+
+## 阶段 6：正式切换与清理
+
+### 6.1 版本策略
+
+- TS 逻辑保留 2-3 个 release（建议）
+- 在 release note 标记迁移状态与开关说明
+- 在移除双路 diff 逻辑前：保留 ruleset 版本与历史 diff 归档
+
+**任务清单**：
+
+- [ ] 定义 TS 保留策略（版本数量 / 时长）
+- [ ] 更新 release note 模板（迁移状态）
+- [ ] 实现 ruleset 版本归档
+- [ ] 实现历史 diff 归档
+
+### 6.2 清理原则
+
+> [!important] No deletions without approval
+> 如需删除现有文件或大规模移除 TS 路径，必须先提案并获得确认。
+
+清理候选（仅列举，不直接执行）：
+
+- 移除 TS 专用实现（在确认无流量后）
+- 移除双路 diff 代码（若不再需要审计）
+- 更新 docs/ 与 CLI 运行手册
+
+**任务清单**：
+
+- [ ] 制定清理提案（需 approval）
+- [ ] 实现清理脚本（可选，自动化）
+- [ ] 更新文档（README / docs/）
+- [ ] 更新 CLI 运行手册
+
+---
+
+## 附录 A：Ruleset 版本化规范
+
+### A.1 命名与存放
+
+- 命名：`diff_ruleset_vN`
+- 存放：`llmswitch-core/src/diff/rulesets/`
+
+### A.2 必含字段
+
+- `version`（v1/v2/...）
+- `created_at`（日期）
+- `field_whitelist`（忽略字段）
+- `tolerance_policy`（容忍策略）
+- `nondeterministic_rules`（非确定性规则）
+- `sse_protocol`（SSE 协议版本）
+
+### A.3 升级流程
+
+1. 新增 v(N+1) ruleset（不改旧版本）
+2. 切换 `current_ruleset` 指针
+3. 所有 diff 记录写入 `ruleset_version`
+
+**任务清单**：
+
+- [ ] 创建 ruleset 目录结构
+- [ ] 实现 `diff_ruleset_v1`（初始版本）
+- [ ] 实现 ruleset 版本管理（current 指针）
+- [ ] 文档化 ruleset 升级流程
+
+---
+
+## 附录 B：Diff 存储与脱敏
+
+### B.1 索引字段
+
+- `requestId`
+- `tenant`
+- `route`
+- `ruleset_version`
+- `timestamp`
+
+### B.2 保留策略
+
+- 全量：7-14 天
+- 采样摘要：30-90 天
+
+### B.3 脱敏规则
+
+- PII：hash + mask（结构保留）
+- secrets：完全移除（不入库）
+- stack：stack hash（用于聚类），必要时保留截断 stack（受访问控制）
+
+**任务清单**：
+
+- [ ] 设计 diff 存储索引（支持高效查询）
+- [ ] 实现保留策略（全量 / 采样 / TTL）
+- [ ] 实现脱敏规则（PII / secrets / stack）

package/docs/servertool-framework.md

@@ -0,0 +1,65 @@
+# ServerTool 框架设计草案
+
+统一的 Server-Side Tool（ServerTool）框架，目标是用一套标准流程承载所有「由服务端执行的工具」：web_search、vision followup（图像模型 → 文本模型）以及未来的自定义工具。
+
+## 核心流程（统一 5 步）
+
+1. **注册 & 初始化**
+   - 提供 `ServerToolRegistry`，在 llmswitch-core 初始化时注册各个工具 handler。
+   - 通过配置（`virtualrouter.webSearch` 等）决定哪些工具启用、使用哪些后端引擎（providerKey / model / 参数）。
+
+2. **命中条件 & 工具注入**
+   - 请求阶段：由 Hub 的工具治理层根据分类结果和配置，完成：
+     - 工具 **命名空间/名称规范化**（如统一 `web_search` 函数名）；
+     - 工具 **强制注入**（force）或 **条件注入**（selective）到 tools 列表；
+   - 响应阶段：从模型返回中统一抽取 `tool_call`（OpenAI style / Responses style），按 name 在注册表里匹配 ServerTool handler。
+
+3. **工具调用拦截 & 执行**
+   - 在 `runServerSideToolEngine()` 中：
+     - 收集所有命中的 `tool_call`（支持多个工具、多个调用）。
+     - 对每个 `tool_call` 调用对应的 ServerTool handler，由 handler 负责：
+       - 解析 arguments；
+       - 根据配置选择后端引擎（如 Gemini CLI、GLM）；
+       - 通过 `providerInvoker` 调用后端 provider（HTTP + compat 已由 llmswitch-core/Host 处理）。
+
+4. **执行结果归一化 & 虚拟 Tool 响应**
+   - 每个 handler 返回统一结构：
+     - 结构化结果 payload（如 web_search 的 `summary + hits[] + engine`）。
+     - 与原始 `tool_call_id` 绑定的「虚拟工具消息」：
+       ```jsonc
+       {
+         "role": "tool",
+         "tool_call_id": "<原 tool_call.id>",
+         "name": "<tool_name>",
+         "content": "<JSON string or structured tokens>"
+       }
+       ```
+   - ServerTool 框架负责把这些虚拟工具消息插入到 ChatEnvelope.messages 中，形成标准的「工具调用 + 工具结果」形态，供后续推理使用。
+
+5. **二次请求（对客户端/主模型透明）**
+   - 框架将更新后的 ChatEnvelope 交还给 Hub Pipeline：
+     - 对 Responses 协议：作为「带 tool 结果的 responses 响应」，再经过 tool governance / finalize → 客户端看到的是已经融合工具结果的回答。
+     - 对 Chat 协议：按 OpenAI 工具规范让主模型继续一轮对话（视为第二跳），调用对话/路由逻辑，但这一层对客户端和 provider runtime 透明。
+   - 整个过程中，客户端仍然只看到一次 `/v1/responses` / `/v1/chat/completions` 请求，ServerTool 的所有调用和重放都封装在 llmswitch-core 内部。
+
+## 模块划分
+
+- `llmswitch-core/src/servertool/registry`（计划）
+  - 负责 ServerTool handler 的注册与查找。
+  - 提供按 tool name（如 `web_search`）查找 handler 的接口。
+
+- `llmswitch-core/src/servertool/engine`（计划）
+  - 替换/封装现有 `runServerSideToolEngine()` 的实现：
+    - 统一抽取工具调用；
+    - 调用 handler；
+    - 注入虚拟 tool 消息；
+    - 触发第二跳或返回更新后的 ChatEnvelope。
+
+- `llmswitch-core/src/servertool/handlers/web_search`（计划）
+  - web_search 的具体 handler：
+    - 解析 `query/engine/recency/count`；
+    - 根据 `virtualrouter.webSearch.engines` 选择后端引擎（Gemini CLI / GLM 等）；
+    - 调后端 provider，解析返回结果，构造统一的搜索结果结构；
+    - 返回绑定原始 tool_call_id 的虚拟 tool 消息。
+
+后续 vision followup 等也会迁移为独立 handler，挂到同一框架上，尽量做到「ServerTool 框架 + 多个 handler」的统一模式。

package/docs/v2-architecture/README.md

@@ -455,17 +455,15 @@ provider → compatibility → llmswitch (final) → response
 #### llmswitch-core Exclusive Responsibilities
 Only `llmswitch-core` modules may perform:
 
-1. **Tool Text Harvesting**: Extract tool calls from message content
+1. **Tool Calls Canonicalization**: Normalize tool_calls structure
    - Implementation: `sharedmodule/llmswitch-core/src/conversion/shared/tool-canonicalizer.ts`
-2. **Tool Calls Canonicalization**: Normalize tool_calls structure
+2. **Argument Stringification**: Convert tool arguments to proper string format
    - Implementation: `sharedmodule/llmswitch-core/src/conversion/shared/tool-canonicalizer.ts`
-3. **Argument Stringification**: Convert tool arguments to proper string format
-   - Implementation: `sharedmodule/llmswitch-core/src/conversion/shared/tool-canonicalizer.ts`
-4. **Result Envelope Stripping**: Remove tool result wrapper envelopes
+3. **Result Envelope Stripping**: Remove tool result wrapper envelopes
    - Implementation: `sharedmodule/llmswitch-core/src/conversion/responses/responses-openai-bridge.ts`
-5. **Schema Augmentation**: Add missing tool schemas when needed
-   - Implementation: `sharedmodule/llmswitch-core/src/conversion/shared/text-markup-normalizer.ts`
-6. **finish_reason=tool_calls Patching**: Set correct finish reason for tool calls
+4. **Schema Augmentation**: Normalize/augment tool schemas (and inject tool guidance when enabled)
+   - Implementation: `sharedmodule/llmswitch-core/src/conversion/shared/tool-governor.ts` + `sharedmodule/llmswitch-core/src/guidance/index.ts`
+5. **finish_reason=tool_calls Patching**: Set correct finish reason for tool calls
    - Implementation: `sharedmodule/llmswitch-core/src/conversion/responses/responses-openai-bridge.ts`
 
 #### V2 Guardrails