From a2b319f250e376853e1b2e55b0864b1258e3d299 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Tue, 25 Aug 2026 23:54:43 -0400 Subject: [PATCH] docs: correct how the recorders actually take their fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both recorders are (self, **fields), not explicit parameter lists, so a new column needs no signature change on them — COLUMNS plus an emitter that passes it is enough. The port Protocol stays explicit because that is where the emitter's contract and the freeze test anchor. --- research-wiki/plans/2026-08-25-thinking-observability-plan.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/research-wiki/plans/2026-08-25-thinking-observability-plan.md b/research-wiki/plans/2026-08-25-thinking-observability-plan.md index 2e50eba..24f4c46 100644 --- a/research-wiki/plans/2026-08-25-thinking-observability-plan.md +++ b/research-wiki/plans/2026-08-25-thinking-observability-plan.md @@ -303,7 +303,9 @@ conda run -n PolyGateway pytest tests/unit/test_cache.py -v **schema**：`SQLITE_DDL` / `PG_DDL` 末尾加 `thinking_observation TEXT`；`SQLITE_BACKFILL` / `_PG_BACKFILL_DECLS` 各加 `("thinking_observation", "TEXT")`；`COLUMNS` 末尾加同名项。**新列必须排在最末**——旧表只能 ALTER 追加到末尾，插在中间会让新建库与补列库的物理列序分叉（该纪律的注释就在这两个常量上方）。 -**recorder**：`sqlite.py` / `postgres.py` 的 `record_llm_call` 各加一参并接进取值元组，位置与 `COLUMNS` 严格同序。`sqlite.py:146` 的"24 字段冻结签名"改 25。 +**recorder**：两个 recorder 的 `record_llm_call` 都是 `(self, **fields: object)` 形态（**不是**显式参数列表），按 `COLUMNS` / `self._columns` 从 `fields` 取值——新列因此**不需要改签名**，只要 `COLUMNS` 里有、emitter 传了，取值就自动到位。要做的是核对两处：取值是否严格按列序、manual 档列裁剪路径是否覆盖新列。`sqlite.py:146` docstring 的"24 字段冻结签名"改 25。 + +> 端口 `ports.py` 的 Protocol 是**显式 25 参**，而实现是 `**fields`——这不矛盾：Protocol 声明的是调用契约（emitter 必须按名传全），实现选择用 kwargs 收。改端口签名仍然必要，它是 emitter 侧的编译期约束与冻结测试的锚点。 **emitter**：`_AttemptUsage` 增 `thinking_observation: ThinkingObservation = ThinkingObservation.UNKNOWN`（**内部字段用枚举类型**，裸 `str` 归一化只发生在下沉 recorder 那一步），`of()` 从 response 取；三个 `emit_*` 各传一行（`emit_terminal_failure` 传 `ThinkingObservation.UNKNOWN`——无响应可言，默认值本身不撒谎）；`_record` 签名增一参并下沉给 recorder。**所有新增字段只经 `_record` 这一个出口抵达 recorder，不新开调用点**（铁律：遥测调用点收敛为单一 helper，该出口已存在）。`middleware/telemetry.py:135` 的"组装 24 字段"改 25。