Skip to content

refactor(native-chat): eliminate Any and slim conversation_bindings - #8970

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/conversation-bindings-slim-20261118
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/conversation-bindings-slim-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Eliminate all Any annotations (69 -> 0) and mypy --strict errors (73 -> 0) in loopx/capabilities/native_chat/conversation_bindings.py while slimming the module (1,155 -> 1,093 lines) in a strictly behavior-preserving change, and register its zero-Any ratchet baseline in loopx/canary/module_metric_baseline.json.

Changes

  • loopx/capabilities/native_chat/conversation_bindings.py (1,155 -> 1,093 lines, 69 -> 0 Any):
    • Replaced all Any, dict[str, Any], and Mapping[str, Any] usage with object, JsonDict (dict[str, object]), JsonMap (Mapping[str, object]), TypedDict (_AgentObservation), and TYPE_CHECKING protocols (_BindingController, _ProjectContextRegistry, _NativePeerSession, inbox function aliases).
    • Consolidated repeated runtime narrowing, binding lookup/reverification, session scan/filtering, host observation assembly, state publication, inbox request locking/validation, and atomic file write verification into local typed helpers (_need, _as_dict, _dict_or_empty, _dict_list, _find_binding, _require_binding, _session_mentions_binding, _iter_open_session_turns, _host_observation_fields, _publish_state, _verify_unchanged, _resolve_source, _path, _entry_path, _lock_request, _write_verified, _validate_current).
    • Preserved all existing docstrings, explanatory comments, public and test-monkeypatched symbol names/signatures (including delegating through self.resolve(...) and preserving two-argument _atomic_write_json compatibility unless preserve_mode=True), return dictionary shapes, and error message strings.
  • loopx/canary/module_metric_baseline.json:
    • Registered "loopx/capabilities/native_chat/conversation_bindings.py" with {"any_count": 0, "dict_any_count": 0, "lines": 1108} alphabetically between pr_lifecycle.py and external_conversations.py.

Verification

  • module_metrics(Path("loopx/capabilities/native_chat/conversation_bindings.py")): {'lines': 1093, 'any_count': 0, 'dict_any_count': 0} (baseline on origin/main: {'lines': 1155, 'any_count': 69, 'dict_any_count': 0}).
  • uv run --extra test mypy --strict --follow-imports=silent loopx/capabilities/native_chat/conversation_bindings.py: Success: no issues found in 1 source file (down from 73 errors on origin/main).
  • uv run --extra test mypy: Success: no issues found in 17 source files.
  • uv run --extra test ruff check loopx/capabilities/native_chat/conversation_bindings.py tests/canary/test_maintainability_ratchet.py: All checks passed!.
  • Targeted pytest across 11 test files (test_chat_conversation_bindings.py, test_private_chat_backlog_projection.py, test_chat_manager_model_adoption.py, test_chat_http_runtime_scope.py, test_lark_private_conversations.py, test_lark_private_compatibility.py, test_native_steward_private.py, test_bound_owner_web_input.py, test_original_conversation_peer.py, test_maintainability_ratchet.py, test_semantic_vocabulary_drift.py): 1044 passed, 9 failed — all 9 failures (test_http_binding_discovery_preserves_duplicate_observations_for_the_typed_owner[file|sqlite] and the 7 test_listener_* tests in test_chat_conversation_bindings.py) reproduce identically on unmodified origin/main (684400582063e16d6c460b005598714f03ae380b: 9 failed, 180 deselected).
  • uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: passed (ok: true, selected=3, failures=0 — control-plane-maintainability-ratchet-smoke.py, semantic-vocabulary-drift-smoke.py, catalog-planner-smoke.py).
  • Public boundary check (loopx check --scan-path ...): public boundary scan clean: 2 files (errors=0, warnings=0).

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对 PR #8970 exact head e254a70dbf03dbbac04524df12c9e35ba838b0be 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 问题)。

动机 / Motivation

受影响调用方与维护者:所有依赖 loopx/capabilities/native_chat/conversation_bindings.py 管理外部会话授权绑定、输入准入、Steward 执行器对齐以及原生 Peer 会话请求的协调控制路径,以及 loopx/canary/ 可维护性棘轮检查。

修改前(6844005820):loopx/capabilities/native_chat/conversation_bindings.py 体积达到 1,155 行,内部散布 69 处 Any / dict[str, Any] / Mapping[str, Any] 宽松标注,在 mypy --strict --follow-imports=silent 下产生 73 个类型错误,且尚未登记入 loopx/canary/module_metric_baseline.json;大量字段校验、状态发布、前置绑定复核与原子 JSON 校验写入分散在重复模板分支中。修改后(e254a70dbf):全模块净减 62 行至 1,093 行,any_count 与 dict_any_count 均降至 0,mypy --strict 错误清零,并在 module_metric_baseline.json 锁定 lines <= 1108, any_count = 0。

可观测结果:module_metrics 实测为 {'lines': 1093, 'any_count': 0, 'dict_any_count': 0};mypy --strict --follow-imports=silent 与全仓 mypy(17 个文件)均报告 0 问题;ruff check、快速预合并门禁(3/3 canaries)和公私边界扫描均通过;相关 11 个测试集跑出 1044 passed,且其余 9 处失败已独立证明在未改动的基线 origin/main@6844005820 上完全复现。若放任不管,核心会话绑定契约将继续处于静态类型盲区并缺乏防膨胀棘轮保护。

非目标边界:本 PR 不更改 conversation-bindings.json 持久化结构、核心规则协议、既有报错字符串、测试兼容猴子补丁接口或 origin/main 上既有的 test_listener_* / test_bound_owner_web_input.py 问题,也不授予自动合入权限。

改动思路 / Approach

全部强类型化与结构瘦身严格限定在既有的 loopx/capabilities/native_chat/conversation_bindings.py 与 loopx/canary/module_metric_baseline.json 所有者边界内完成,复用标准库 object、Mapping[str, object]、TypedDict、Sequence[object] 与 TYPE_CHECKING 协议接口收敛外部协作依赖,未引入任何平行模块、运行时开关或接口破坏性重构。

当前 PR 边界:范围聚焦于 conversation_bindings.py 的零 Any 收敛、跨方法重复窄化/发布/文件校验辅助抽提以及 module_metric_baseline.json 棘轮基线注册;对外部尚无严格类型签名的 inbox 底层模块及 tests/ 既有主干基线缺陷保持独立修复边界,不混改无关文件。

  • 类型系统边界收口:使用 JsonDict/JsonMap 别名、TypedDict(_AgentObservation)与本地 TYPE_CHECKING Protocol 描述控制器、项目上下文、原生 Peer 会话与异步事件接收器,并在入参/内部 JSON 解码处用显式运行期类型收窄函数替代 Any 透传。
  • 重复流程辅助聚合:抽提 _need、_as_dict、_dict_or_empty、_dict_list、_find_binding / _require_binding、_session_mentions_binding、_iter_open_session_turns、_host_observation_fields、_publish_state、_verify_unchanged、_resolve_source、_path / _entry_path / _lock_request / _write_verified / _validate_current,保留原有方法签名、猴子补丁点(如 self.resolve(...) 与二参 _atomic_write_json 默认路径)及全部注释文档。

具体改动 / Changes

本次 diff 仅修改 2 个文件(640 insertions(+), 697 deletions(-),净减 57 行):

  1. loopx/capabilities/native_chat/conversation_bindings.py(+635 / -697 行,全文件 1155 -> 1093 行,69 Any -> 0,mypy --strict 错误 73 -> 0):清除全部 Any,抽提共享窄化/校验/发布/请求文件操作辅助函数,完整保留原有 docstring、注释与异常文案。
  2. loopx/canary/module_metric_baseline.json(+5 / -0 行,L32-36):按字典序插入 "loopx/capabilities/native_chat/conversation_bindings.py": {"any_count": 0, "dict_any_count": 0, "lines": 1108}。

本文档基线检查按 spec_basis = no_spec 处理:无独立外部规范文档,验收对照严格基于既有类型安全契约、测试兼容面与棘轮基线规则。

关键代码讲解

  • _need / _as_dict / _dict_or_empty / _dict_list(loopx/capabilities/native_chat/conversation_bindings.py:61-78):统一封装运行期 isinstance(..., kind) 类型收窄与稳定错误信息,在消除 Any 透传的同时维持原有 TypeError / ValueError 契约与 object 边界校验。
  • ChatConversationBindings._publish_state 与 _verify_unchanged(L132-146):收敛绑定变更后的原子持久化、_atomic_write_json 兼容参数传递(仅在显式 preserve_mode=True 时透传 preserve_mode,保留现有二参测试替身兼容性)以及 provider IO 之后的精确绑定一致性复核。
  • ChatConversationBindings._resolve_source(L147-157):将输入/会话来源拼装收敛为单入口并显式经由 self.resolve(...) 委派,从而兼容测试对实例 resolve 方法的拦截替换,避免静默绕过授权链路。
  • OriginalConversationRequests._write_verified 与 _validate_current(L737-742、L1015-1022):合并多处状态校验写入回读确认以及原会话请求访问/状态检查路径,减少条件分支漂移。

对主干的风险 / Risks

  • 测试兼容性与基线回归隔离:针对 conversation_bindings.py 相关 11 个测试文件实测跑出 1044 passed,另 9 项失败(tests/control_plane/test_bound_owner_web_input.py::test_http_binding_discovery_preserves_duplicate_observations_for_the_typed_owner[file|sqlite] 共 2 项,以及 tests/test_chat_conversation_bindings.py 中 7 项 test_listener_* 用例);经在干净基线工作树 origin/main@6844005820 同条件复跑确认,这 9 项在合入前主干即完全失败(9 failed, 180 deselected in 11.72s),属于既有主干缺陷而非本 PR 引入的回归。
  • 调用方类型契约与副作用边界:静态类型收窄未改变任何对外返回字典键名、错误消息文本或持久化写入协议;全仓 mypy(17 个文件)与 mypy --strict --follow-imports=silent 均 0 错误,确认无跨模块调用签名撕裂。
  • 完整验证矩阵(exact head e254a70dbf03dbbac04524df12c9e35ba838b0be):
    • module_metrics: PASS — {'lines': 1093, 'any_count': 0, 'dict_any_count': 0}(基线 lines=1155, any_count=69)
    • uv run --extra test mypy --strict --follow-imports=silent loopx/capabilities/native_chat/conversation_bindings.py & uv run --extra test mypy: PASS — 各自 0 issues(17 个追踪模块全部通过)
    • uv run --extra test ruff check loopx/capabilities/native_chat/conversation_bindings.py tests/canary/test_maintainability_ratchet.py: PASS — All checks passed!
    • 11 个核心/契约/棘轮/词表漂移 pytest 套件: PASS on changed scope — 1044 passed;其余 9 项失败已于未改动 origin/main@6844005820 独立复现为既有主干故障
    • uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: PASS — ok=true, selected=3, failures=0(control-plane-maintainability-ratchet-smoke.py、semantic-vocabulary-drift-smoke.py、catalog-planner-smoke.py 全过)
    • loopx check --scan-path ...: PASS — public boundary scan clean: 2 files, errors=0, warnings=0
    • GitHub 远端诊断 CI(提交后即时读取): Sign-off、changes、inspect-pr-diff、dependency-review、loopx-codex-provider-routing、loopx-repo-health、loopx-obelisk、Summary 为 PASS;kernel-static-checks、loopx-core、build、prepare 尚在运行中(UNVERIFIED,不阻断审查结论)。

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 彻底消除 conversation_bindings.py 内的 69 处 Any 与 73 处严格模式报错,净减 62 行并将 any_count=0, dict_any_count=0, lines=1108 纳入棘轮约束,稳固后续长程迭代的静态安全底线。
  • User-experience 影响:not_applicable — 纯内部能力层类型硬化、辅助函数收敛与棘轮基线注册,外部交互界面与输出文案均无变化;visual_review 为 not_applicable。
  • 可观测语义 / 代码体积 / 词表边界:observable_semantics 为 equivalent,repository_reuse 为 reused,code_volume 判为 necessary 且完整保持旧签名与二参测试兼容,change_proportionality 为 proportionate,default_off_isolation 为 isolated,authority_semantics 与 semantic_alignment 均为 aligned(candidate_decision="reuse_existing",未新增词汇或权限边界)。

本 PR 为作者自有并触及 capabilities/**,合规交付仍需维护者最终审查与合并授权。

English verdict: APPROVE exact head e254a70 (author-owned COMMENTED approval review); eliminates all 69 Any occurrences and 73 mypy --strict errors while slimming loopx/capabilities/native_chat/conversation_bindings.py (1155 -> 1093 lines) and registering a zero-Any baseline ratchet, with zero PR regressions verified by strict/repo mypy (0 issues across 17 files), ruff, quick premerge canary (3/3), public boundary check, and 1044 passing pytest cases (all 9 failures reproduced identically on unmodified origin/main@6844005820).

@mergify

mergify Bot commented Nov 19, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026
@loopx-agent
loopx-agent force-pushed the codex/conversation-bindings-slim-20261118 branch from e254a70 to 34f71f0 Compare November 19, 2026 14:33
@mergify mergify Bot removed the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对 PR #8970 rebase 后 exact head 34f71f02529f7ca6f79f277296bd42c8876d4756 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 阻塞问题;PR 保持 OPEN,不执行合并)。

动机 / Motivation

受影响调用方与维护者:所有依赖 loopx/capabilities/native_chat/conversation_bindings.py 管理外部会话授权绑定、输入准入、Steward 执行器对齐以及原生 Peer 会话请求的协调控制路径,以及 loopx/canary/ 可维护性棘轮检查。

修改前(origin/main@ff90543766):loopx/capabilities/native_chat/conversation_bindings.py 体积达到 1,155 行,内部散布 69 处 Any / dict[str, Any] / Mapping[str, Any] 宽松标注,在 mypy --strict --follow-imports=silent 下产生 131 个类型错误,且尚未登记入 loopx/canary/module_metric_baseline.json;字段收窄、状态发布、前置绑定复核与原子写入校验也重复分散在多个分支中。修改后(rebased head 34f71f0252):全模块净减 62 行至 1,093 行,any_count 与 dict_any_count 均降至 0,mypy --strict 错误清零,并在保留主干 #9072 注释调整的同时于 module_metric_baseline.json 锁定 lines <= 1108, any_count = 0, dict_any_count = 0。

可观测结果:已验证 module_metrics 为 {'lines': 1093, 'any_count': 0, 'dict_any_count': 0},mypy --strict --follow-imports=silent 与全仓 mypy(17 个文件)均报告 0 问题,ruff check、标准预合并门禁(13/13 checks,ok=true)与公私边界扫描均通过;相关 13 个目标 pytest 套件共跑出 1,258 passed,包括 test_chat_conversation_bindings.py(117/117)、test_original_conversation_peer.py(40/40)、test_chat_manager_model_adoption.py(38/38)、test_semantic_vocabulary_drift.py(124/124)、test_lark_private_conversations.py + test_native_steward_private.py(648/648)及 5 项辅助套件(208/208)全通过,而 test_maintainability_ratchet.py 中 1 项与 test_bound_owner_web_input.py 中 2 项失败已在未改动的 origin/main@ff90543766 同条件复现。

非目标边界:本 PR 不更改 conversation-bindings.json 持久化结构、核心规则协议、既有报错文案、测试兼容猴子补丁接口,也不修复 origin/main 上既有的 interaction_contract.py 决策函数长度超限或 test_bound_owner_web_input.py 既有失败,且不授予自动合并权限。

改动思路 / Approach

全部强类型化与结构瘦身严格限定在既有的 loopx/capabilities/native_chat/conversation_bindings.py 与 loopx/canary/module_metric_baseline.json 所有者边界内完成,复用标准库 object、Mapping[str, object]、TypedDict、Sequence[object] 与 TYPE_CHECKING 协议接口收敛外部协作依赖,未引入平行模块、运行时开关或接口破坏性重构,因此保留在既有文件所有者边界内。

当前 PR 边界:范围聚焦于 conversation_bindings.py 的零 Any 收敛、跨方法重复窄化/发布/文件校验辅助抽提以及 module_metric_baseline.json 棘轮基线注册;对外部尚无严格类型签名的 inbox 底层模块及 origin/main 既有基线缺陷保持独立修复边界,不混改无关文件。

  • 类型系统边界收口:使用 JsonDict / JsonMap 别名、TypedDict(_AgentObservation)与本地 TYPE_CHECKING 协议(_ProjectContexts、_BindingController、_NativePeerSession、_RequestLockFn、_RecordResultFn)描述协作边界,并在入参和持久化解码处通过显式运行期窄化辅助替代 Any 透传。
  • 重复流程收敛与主干兼容性:抽提 _need、_as_dict、_dict_or_empty、_dict_list、_find_binding、_require_binding、_session_mentions_binding、_iter_open_session_turns、_host_observation_fields、_publish_state、_verify_unchanged、_resolve_source、_path、_entry_path、_lock_request、_write_verified、_validate_current,完整保留原有签名、测试猴子补丁点(如 self.resolve(...) 与二参 _atomic_write_json 默认路径)以及 origin/main #9072 的注释更新(L479 与 L805)。

具体改动 / Changes

本次 rebase 至 origin/main@ff90543766 的 diff 仅涉及 2 个文件(640 insertions(+), 697 deletions(-),净减 57 行):

  1. loopx/capabilities/native_chat/conversation_bindings.py(+635 / -697 行,全文件 1155 -> 1093 行,69 Any -> 0,mypy --strict 错误 131 -> 0):清除全部 Any,抽提共享窄化/校验/发布/请求文件操作辅助函数,完整保留原有异常文案、持久化格式及 #9072 注释调整。
  2. loopx/canary/module_metric_baseline.json(+5 / -0 行,L47-51):按字典序插入 "loopx/capabilities/native_chat/conversation_bindings.py": {"any_count": 0, "dict_any_count": 0, "lines": 1108}。

本文档基线检查按 spec_basis = no_spec 处理:无独立外部规范文档,验收对照严格基于既有会话绑定行为契约、调用方兼容面、mypy --strict 与可维护性棘轮基线规则。

关键代码讲解

  • _need / _as_dict / _dict_or_empty / _dict_list(loopx/capabilities/native_chat/conversation_bindings.py:61-77):统一封装运行期 isinstance(..., kind) 类型收窄与稳定 ValueError 报错信息,避免 Any 透传同时保持对非对象 JSON 字段的确定性拒绝。
  • ChatConversationBindings._publish_state 与 _verify_unchanged(loopx/capabilities/native_chat/conversation_bindings.py:132-145):收敛绑定变更后的原子持久化、_atomic_write_json 兼容参数传递(仅在显式 preserve_mode=True 时传入 preserve_mode,兼容二参测试替身)以及外部 IO 后的精确绑定一致性复核。
  • ChatConversationBindings._resolve_source(loopx/capabilities/native_chat/conversation_bindings.py:147-156):将来源上下文构造收敛为单入口并显式经由 self.resolve(...) 委派,确保测试对实例 resolve 方法的拦截替换继续生效。
  • OriginalConversationRequests._write_verified 与 _validate_current(loopx/capabilities/native_chat/conversation_bindings.py:737-741、L1015-1021):合并状态持久化写入回读确认与原会话请求当前状态/权限校验逻辑,减少条件分支漂移。

对主干的风险 / Risks

  • 基线测试失败归因隔离:在 rebased head 34f71f0252 运行 13 个目标套件共取得 1,258 passed(test_chat_conversation_bindings.py 117/117、test_original_conversation_peer.py 40/40、test_chat_manager_model_adoption.py 38/38、test_semantic_vocabulary_drift.py 124/124、test_lark_private_conversations.py + test_native_steward_private.py 648/648、test_private_chat_backlog_projection.py + test_chat_http_runtime_scope.py + test_lark_private_compatibility.py + test_chat_file_discovery.py + test_native_steward_reports.py 208/208、test_maintainability_ratchet.py 13/14、test_bound_owner_web_input.py 70/72);仅 tests/canary/test_maintainability_ratchet.py::test_current_repository_debt_is_reviewed_without_line_count_pins(1 项,因 origin/main 上 loopx/control_plane/work_items/interaction_contract.py 决策函数达 96 语句超阈值)与 tests/control_plane/test_bound_owner_web_input.py::test_http_binding_discovery_preserves_duplicate_observations_for_the_typed_owner[file|sqlite](2 项,返回 200 而非 409)失败,且经在未改动 origin/main@ff90543766 独立 worktree 复跑确认这 3 项完全同因复现(3 failed in 17.87s),与本 PR 无关。
  • 运行期类型收窄与调用方兼容风险:所有运行期 _need/_as_dict 收窄仅针对原有必选或已知结构的字段,其余可选字段通过 _dict_or_empty 安全回退,且直接探针验证了二参 _atomic_write_json 替身、self.resolve(...) 委派及错误消息保真;全仓 mypy(17 个文件)和 mypy --strict --follow-imports=silent 均为 0 错误。
  • 完整验证矩阵(exact head 34f71f02529f7ca6f79f277296bd42c8876d4756):
    • module_metrics: PASS — {'lines': 1093, 'any_count': 0, 'dict_any_count': 0}(origin/main@ff90543766 基线为 lines=1155, any_count=69)
    • mypy --strict --follow-imports=silent loopx/capabilities/native_chat/conversation_bindings.py & 全仓 mypy: PASS — 0 issues(主干同文件为 131 errors,追踪 17 文件全过)
    • ruff check & scripts/check_rfc_bilingual.py --base origin/main --head HEAD & git diff --check: PASS
    • 直接行为与 AST 探针(_need、_atomic_write_json 二参兼容、_resolve_source 委派、AST 零 Any): PASS
    • loopx canary premerge --tier standard --from-git-diff --git-diff-base origin/main: PASS — ok=true, selected=13, executed=13, failures=0(含 advisory_inherited_failure=1 自动降级主干 interaction_contract.py 棘轮项)
    • loopx check --scan-path ...: PASS — public boundary scan clean: 2 files, errors=0, warnings=0
    • 13 个目标 pytest 套件: PASS on changed scope — 1,258 passed,仅上述 3 项已在 origin/main@ff90543766 独立复现的既有故障除外
    • 远端 CI 策略(wait_for_ci=false / ci_policy=not_consulted):按 Goal 配置不等待也不依赖远端 GitHub Actions CI(UNVERIFIED,不阻断本地验证与评审结论)

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 消除 conversation_bindings.py 内全部 69 处 Any 与 131 处 mypy --strict 报错,净减 62 行并将 any_count=0, dict_any_count=0, lines=1108 纳入棘轮约束,稳固核心会话绑定路径的静态类型安全与防膨胀下限。
  • User-experience 影响:not_applicable — 纯内部能力层类型硬化与棘轮基线注册,无前端或可见渲染界面变更。(visual_review 为 not_applicable,unverified_scope: none)。
  • 可观测语义 / 代码体积 / 词表边界:observable_semantics 为 equivalent,repository_reuse 为 reused,code_volume 判为 necessary(compatibility_assessment: retain,保留既有持久化和测试猴子补丁契约),change_proportionality 为 proportionate,default_off_isolation 为 isolated,authority_semantics 与 semantic_alignment 均为 aligned(candidate_decision="reuse_existing",未新增词表、持久化 schema 或权限边界)。
  • 剩余风险与合并门禁:核心行为与类型契约已通过本地标准 premerge、mypy 与 1,258 项测试通过证明,唯一未在本次单独全量重放的是独立外部模块 inbox 内部的未加类型边界;本 PR 为作者自有并触及 capabilities/**,需按维护者授权流程再行处理合并(本次操作按要求保持 PR OPEN)。

English verdict: APPROVE exact head 34f71f0 (author-owned COMMENTED approval review); cleanly rebased onto origin/main@ff90543766 preserving #9072 comment edits, eliminates all 69 Any occurrences and 131 mypy --strict errors while slimming conversation_bindings.py (1155 -> 1093 lines) and locking a zero-Any baseline ratchet, verified passing by strict/repo mypy (0 issues across 17 files), ruff, direct behavioral probes, standard premerge canary (13/13), public boundary check, and 1258 passing pytest cases across 13 suites with the 3 failing cases independently reproduced on unmodified origin/main@ff90543766.

@mergify

mergify Bot commented Nov 19, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/conversation-bindings-slim-20261118 branch from 34f71f0 to fd1d5e7 Compare November 19, 2026 18:35
@mergify mergify Bot removed the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对 PR #8970 rebase 至最新主干 origin/main@b927e20bfb 后的 exact head fd1d5e7004c91d00c1c7572a060430157d929ef8 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 阻塞问题;按当前任务要求保持 PR 为 OPEN,不执行合入)。

动机 / Motivation

  • 受影响调用方与维护者:所有通过 loopx/capabilities/native_chat/conversation_bindings.py 管理外部会话授权绑定、输入准入、Steward 执行器对齐以及原生 Peer 会话请求的控制面与运行时路径(包括 project_context.py、external_conversations.py、steward_turn.py、codex_adapter.py、steward_monitor.py、queued_admission.py、transports.py),以及依赖 loopx/canary/module_metric_baseline.json 执行可维护性棘轮检查的维护者。
  • 修改前后的具体场景与成本:在修改前(origin/main@b927e20bfb),loopx/capabilities/native_chat/conversation_bindings.py 体积达到 1,155 行,包含 69 处 Any / dict[str, Any] / Mapping[str, Any] 标注,在 mypy --strict --follow-imports=silent 下触发 131 个类型错误,且尚未登记进入 loopx/canary/module_metric_baseline.json 防回归棘轮;运行时重复的 JSON 字段收窄、绑定查找、状态回读验证与原会话请求写入分散在多个方法中,且旧分支与已合入主干的 #8911 在 module_metric_baseline.json 上存在相邻行冲突。修改并 rebase 后(fd1d5e7004c91d00c1c7572a060430157d929ef8),全文件净缩减 62 行至 1,093 行,any_count 与 dict_any_count 均降至 0,mypy --strict 错误清零,并在保留 #8911 对 external_conversations.py 2k 行上限退场与 #9072 注释更新的同时,将 conversation_bindings.py 锁定在 lines <= 1108, any_count = 0, dict_any_count = 0。
  • 可观测改善与边界:本地验证已证明 module_metrics 实测为 {'lines': 1093, 'any_count': 0, 'dict_any_count': 0},mypy --strict --follow-imports=silent 与 ruff check 均 0 错误,9 个核心绑定/Peer/棘轮测试套件跑出 346/346 全通过,24 套件并行全量验证跑出 1,775 passed(仅 1 项并行超时在单跑时 16/16 全通过,2 项失败已在未改动的 origin/main@b927e20bfb 上同因复现),TS 控制面 conversation_binding.test.ts 63/63 通过,Goal 绑定 CQR(cqr_83cd3d314c9b80ecc01a)与 canary premerge --tier quick(3/3)全通过。若不做本次清理与棘轮登记,核心绑定模块会继续暴露在静态类型盲区与后续行数/Any 回弹风险中。
  • 非目标边界:本 PR 不修改 conversation-bindings.json 持久化 schema、核心裁决语义(effect_runtime_result)、报错文案、测试猴子补丁兼容接口,不修改 external_conversations.py(完整保留 #8911 的结构调整与基线退场),也不负责修复 origin/main 上既有的 test_bound_owner_web_input.py 发现用例或 interaction_contract.py 既有 mypy 问题,且不授予合并权限。

改动思路 / Approach

本切片严格在既有的 loopx/capabilities/native_chat/conversation_bindings.py 与 loopx/canary/module_metric_baseline.json 所有者边界内实施结构收敛与类型硬化:调用入口仍经由 ChatConversationBindings 与 OriginalConversationRequests 暴露给既有调用方,权威状态仍归属 conversation-bindings.json 与 inbox 请求目录,所有策略/准入决策继续委托给 TypeScript effect_runtime_result(collaboration.conversation.* / collaboration.project.* / collaboration.source.* / collaboration.request.*),未新增平行控制面、配置开关或持久化字段。

在架构评估与复用权衡上(change_proportionality.architecture_assessment: retain):所抽提的 _need、_as_dict、_dict_or_empty、_dict_list、_find_binding、_require_binding、_publish_state、_verify_unchanged、_resolve_source、OriginalConversationRequests._path / _entry_path / _lock_request / _write_verified / _validate_current 均属于模块内局部辅助(local_helper),直接服务于 Python IO 包装层的运行期类型收窄与重复读/写/锁验证模板收敛,不改变任何外部契约或默认故障恢复链路(provider IO 失败或绑定变更仍立即抛出原有 ValueError / OSError)。外部 inbox 底层模块仍保持原有未强类型化签名,本 PR 仅在调用边界使用局部 TYPE_CHECKING 协议与 cast 收口,避免把 PR 范围扩散到跨子系统类型重写。

具体改动 / Changes

本次 base-to-head diff(origin/main@b927e20bfb..fd1d5e7004c91d00c1c7572a060430157d929ef8)仅涉及 2 个文件(640 insertions(+), 697 deletions(-),净减 57 行):

  1. loopx/capabilities/native_chat/conversation_bindings.py(+635 / -697 行,全文件 1,155 -> 1,093 行,69 Any -> 0,mypy --strict 错误 131 -> 0):使用 object、JsonDict(dict[str, object])、JsonMap(Mapping[str, object])、TypedDict(_AgentObservation)与局部 TYPE_CHECKING 协议替换全部 Any,收敛重复字段收窄、绑定查找、状态发布校验与原会话请求读写验证逻辑,同时完整保留 #9072 的注释精简与既有异常信息。
  2. loopx/canary/module_metric_baseline.json(+5 / -0 行):在 module_metric_ceilings 中按字典序注册 "loopx/capabilities/native_chat/conversation_bindings.py": {"any_count": 0, "dict_any_count": 0, "lines": 1108};rebase 解决冲突时完整保留 #8911 对 "loopx/capabilities/native_chat/external_conversations.py" 棘轮条目的移除。

规格依据(spec_basis):按 no_spec(spec_source=none)处理——本 PR 属于不改变协议 schema 与外部契约的内部类型硬化和棘轮基线锁定,无独立外部 RFC 或新增规格文档,验收标准直接对应既有会话绑定运行时契约、mypy --strict 与可维护性棘轮检查。

关键代码讲解

  • _need / _as_dict / _dict_or_empty / _dict_list 与 _find_binding / _require_binding(loopx/capabilities/native_chat/conversation_bindings.py:61-90):在 object / JsonMap 边界统一执行 isinstance 运行期类型收窄与绑定列表查找;必选字段类型不符直接抛出稳定 ValueError,可选字典字段通过 _dict_or_empty 安全回退,既消除 Any 透传又维持原有异常契约。
  • ChatConversationBindings._publish_state 与 _verify_unchanged(loopx/capabilities/native_chat/conversation_bindings.py:132-145):合并所有绑定修改后的条件原子写入与读回一致校验;显式区分 preserve_mode=True 与默认二参 _atomic_write_json(self.path, state) 调用,确保不破坏测试替身的二参签名兼容性,并在 provider IO 后复核绑定未被并发撤销或替换。
  • ChatConversationBindings._resolve_source(loopx/capabilities/native_chat/conversation_bindings.py:147-156):将 input_context、session_context、adopt_created_goal 中的来源参数校验与拼装统一收口并经由 self.resolve(...) 委派,确保测试在实例上猴子补丁 resolve 时拦截逻辑依然生效。
  • OriginalConversationRequests._write_verified 与 _validate_current(loopx/capabilities/native_chat/conversation_bindings.py:737-741、L1015-1021):收敛策略/路由/请求条目写后回读校验以及 validate_turn / _complete_answer / start_guard 中的 collaboration.project.request 与可选 original_conversation_access 复验流程,消除分支漂移。

对主干的风险 / Risks

无 P0/P1/P2 阻塞发现。主要兼容与基线风险分析如下:

  • 调用方与测试替身兼容边界(scope_fit 与反例验证):全部生产调用方(project_context.py、external_conversations.py、steward_turn.py、codex_adapter.py、steward_monitor.py、steward_reports.py、queued_admission.py、transports.py、session_queue.py、steward_managed_mode.py)签名与返回值结构均未改变;直接行为探针已证实二参 _atomic_write_json 替身、preserve_mode=True 路径、self.resolve(...) 委派以及 _need 错误类型/文案均按预期工作。负向与撤销路径(如绑定撤销后 OriginalConversationRequests.control 拒绝 revise 仍允许 inspect/cancel、绑定在观察期间变更时 _verify_unchanged 抛出 ValueError)在 test_chat_conversation_bindings.py 与 test_original_conversation_peer.py 中全部通过。
  • 既有主干基线失败归因隔离:
    • 在 24 套件并行全量验证中(1,775 passed, 3 failed),tests/control_plane/test_bound_owner_web_input.py::test_http_binding_discovery_preserves_duplicate_observations_for_the_typed_owner[file|sqlite](2 项,断言 409 实得 200)已在未改动 origin/main@b927e20bfb 独立复现(2 failed, 70 deselected in 81.28s),原因是主干 _observe_local_sessions 早先已改用 store.iter_session_metadata() 而该测试仍猴子补丁 store.list_sessions,与本 PR 无关。
    • 另 tests/test_native_steward_reports.py::test_report_quota_failure_continues_once_after_native_no_effects_and_available_allowance[current_context-True-False-sqlite] 在 -n 4 高并发长跑下出现 1 次 15s 等待超时,独立单跑该测试集(-k 覆盖 16 项变体)全部通过(16 passed)。
    • 全仓 uv run --extra test python -m mypy(对应 pyproject.toml#tool.mypy 的 17 个文件)在 origin/main 的 loopx/control_plane/work_items/interaction_contract.py:1004 存在 1 项既有类型错误(conversation_bindings.py 不在其中,而针对变更文件自身的 mypy --strict --follow-imports=silent 为 0 错误)。
  • 比例性与治理边界:改动仅限单一重构模块与棘轮登记(change_proportionality: proportionate),无特性开关与默认行为变化(default_off_isolation: not_applicable,未更改既有默认路径),公共持久化与协议名称保持不变(authority_semantics: aligned),semantic_alignment 为 aligned(candidate_decision="reuse_existing",未引入新词汇或修改现有约束语义,仅登记既有模块度量棘轮)。
  • 验证矩阵(exact head fd1d5e7004c91d00c1c7572a060430157d929ef8):
    • module_metrics & AST Any 扫描:PASS — {'lines': 1093, 'any_count': 0, 'dict_any_count': 0},AST Any count: 0(origin/main@b927e20bfb 基线为 lines=1155, any_count=69)
    • uv run --extra test python -m mypy --strict --follow-imports=silent loopx/capabilities/native_chat/conversation_bindings.py:PASS — Success: no issues found in 1 source file(origin/main@b927e20bfb 基线为 131 errors)
    • uv run --extra test python -m mypy:FAIL (pre-existing unrelated) — 1 error on origin/main loopx/control_plane/work_items/interaction_contract.py:1004
    • uv run --extra test ruff check loopx/capabilities/native_chat/conversation_bindings.py tests/canary/test_maintainability_ratchet.py:PASS — All checks passed!
    • 直接行为探针(_need / _as_dict / _dict_or_empty / _dict_list、_publish_state 二参与 preserve_mode、_resolve_source 委派):PASS
    • 核心绑定/Peer/棘轮 9 套件 pytest:PASS — 346 passed(test_chat_conversation_bindings.py、test_original_conversation_peer.py、test_maintainability_ratchet.py、test_chat_manager_model_adoption.py、test_private_chat_backlog_projection.py、test_chat_http_runtime_scope.py、test_lark_private_compatibility.py、test_chat_file_discovery.py、test_peer_source_store.py)
    • 24 套件全面回归 pytest(-n 4):PASS on changed scope — 1,775 passed, 3 failed(其中 1 项并发超时单跑 16/16 通过,另 2 项在 origin/main@b927e20bfb 同因复现)
    • tests/control_plane_ts/conversation_binding.test.ts:PASS — 63 passed, 0 failed
    • Goal 绑定 CQR(change-quality verify --goal-id personal-loopx-maintenance):PASS — receipt_id=cqr_83cd3d314c9b80ecc01a, receipt_valid=true, decision=pass
    • loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance:PASS — ok=true, direct_checks=6/6, selected_canaries=3/3(含 control-plane-maintainability-ratchet-smoke.py、semantic-vocabulary-drift-smoke.py、catalog-planner-smoke.py)
    • loopx check --scan-path ... & scripts/check_rfc_bilingual.py & git diff --check:PASS — public boundary scan clean: 2 files, errors=0, warnings=0
    • 远端 CI 策略(wait_for_ci=false / ci_policy=not_consulted):按 Goal 配置不等待也不咨询远端 GitHub Actions CI(UNVERIFIED,不影响本地审查结论)。

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 彻底消除 conversation_bindings.py 全部 69 处 Any 与 131 个 mypy --strict 错误,净缩减 62 行并将 any_count=0, dict_any_count=0, lines=1108 锁定入棘轮基线,同时在 rebase 中完整保留 #8911 的 external_conversations.py 瘦身与基线退场成果,显著降低后续长程演进的类型漂移与回归风险。
  • User-experience 影响:not_applicable — 纯内部能力模块类型收口与可维护性棘轮登记,未改变任何前端页面、交互流程或 CLI 输出格式(visual_review 为 not_applicable,原因:仅修改内部 Python 会话绑定模块与度量基线 JSON,无渲染或可见界面变更;unverified_scope: none)。
  • 可观测语义 / 代码体积 / 词表边界:observable_semantics 为 equivalent(全部签名、报错、持久化写入和猴子补丁兼容保持不变);code_volume 为 necessary(compatibility_assessment: retain,保留既有存储协议与二参测试替身兼容);change_proportionality 为 proportionate(architecture_assessment: retain);default_off_isolation 为 not_applicable;authority_semantics 为 aligned;semantic_alignment 为 aligned(candidate_decision="reuse_existing",未新增词表或权限边界)。
  • 剩余风险与合并状态:仅外部未严格类型化的 inbox 底层模块依赖边界保留局部 cast 收窄;本次已于 exact head fd1d5e7004c91d00c1c7572a060430157d929ef8 完成 CQR 验真(cqr_83cd3d314c9b80ecc01a)与本地预合并门禁验证,按本次任务约束保持 PR #8970 为 OPEN,不执行合并。

English verdict: APPROVE exact head fd1d5e7 (author-owned COMMENTED approval review); cleanly rebased onto origin/main@b927e20bfb preserving #8911 external_conversations ceiling retirement and #9072 comment edits, eliminates all 69 Any occurrences and 131 mypy --strict errors while slimming conversation_bindings.py (1155 -> 1093 lines) and locking a zero-Any baseline ratchet, verified passing by strict mypy, ruff, direct probes, 346 core pytest cases, 1775/1778 broader pytest cases (with the 1 timeout passing 16/16 standalone and the 2 bound_owner failures reproduced identically on origin/main@b927e20bfb), 63 TS control-plane tests, Goal-bound CQR (cqr_83cd3d314c9b80ecc01a), public boundary check, and quick premerge canary (3/3); left OPEN per task instructions.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

Reviewed head fd1d5e7004c91d00c1c7572a060430157d929ef8

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, max)

请修正新 Protocol 和现有 ChatRuntimeController 的兼容性。运行对照通过的路径无需改动。

动机 / Motivation

在 App 或原生聊天里回到已绑定会话的人,需要在同一条会话恢复未完成的工作。维护这些入口的人也必须能用类型检查确认它们调用同一套实际支持的接口。

原模块混用宽泛字典和重复的读取代码。它很难提示哪个字段由会话、授权或请求 owner 提供。当前尝试在保留原始会话、排队和结果归还的同时,把这些边界收成明确类型。

本地运行对照观察到同样的连接、停止、重放和回执。当前模块自身的类型诊断消失,但两个实际入口在传入现有 controller 时仍被新的类型声明拒绝。

当前变更只重整 Python 适配器和模块指标,处理会话授权、请求及结果的现行 owner 继续负责其生产判定。

改动思路 / Approach

现有 TypeScript Core 决定授权和原会话请求身份。Python 负责有序锁、读取以及原 host 启停,类型声明应准确描述实际依赖。 本 PR 可独立完成会话绑定适配器的类型收敛,验收范围包含已部署 API 的两处真实 Python 入口。 模块保留源、Goal、binding、request、Session 的栅栏顺序。未确认 stop 仍让用户用原 binding 重试。类型检查需要由调用者的真实类型覆盖这条链。

具体改动 / Changes

两个路径共 +640 / −697。生产模块减少 62 行,另补零 Any 的模块指标条目。

依据 docs/architecture/rfcs/app-conversation-and-async-inbox-v0.md(b927e20bfbe60817570bceb8654e2bfbc96abadf)。retained-stop 已实现,撤权后可用原 binding 重试确认。original-route 已实现,受理与归还仍核对现行 scope。replay-without-rerun 已实现,恢复沿用原请求和持久结果。 接受的 RFC

关键代码讲解

  • _BindingController 是两个正式入口使用的新 Protocol。当前可写的 project_contexts 声明使实际 controller 无法通过检查。 接口 · Runtime · HTTP

  • _stop_revoked_binding 用同一 helper 读取未终止的队列和活跃 Turn,只停止受该 binding 约束的工作。未确认时,恢复仍留在原 binding。 停止与恢复

  • OriginalConversationRequests._fenced 复用已有 source 和 binding 栅栏。原工作在写入及重放时保留 requester、recipient 与当前授权。 并发边界 · 提交与重放

对主干的风险 / Risks

新 _BindingController 把 project_contexts 声明为可写的 _ProjectContexts 属性。真实 ChatRuntimeController 把该属性定型为 ChatProjectContexts。mypy 会对可写 Protocol 属性做不变性检查,因此入口传入真实 controller 时类型不匹配。 使用同一 strict 命令审查模块和两个真实入口,目标模块从 73 个诊断降到 0;当前两个真实调用点仍报 arg-type。基线相同调用点的诊断是 no-untyped-call。

把协议中只读使用的 project_contexts 声明为 @Property,或使用现有调用方真正满足的窄接口。用同一命令覆盖目标模块与两个真实入口,确认调用点的 arg-type 消失。隔离源码验证只改为只读 property 即消除两处诊断。 复核命令为 python -m mypy --strict --follow-imports=silent loopx/capabilities/native_chat/conversation_bindings.py loopx/chat_runtime.py loopx/chat_server.py。

同一四份聚焦测试在两版各 149 passed;原会话 peer 额外用例中 FIFO、撤权、同意图恢复、已保存结果归还和最终读回均验证。刻意去掉活跃 Turn 分支时,既有 HTTP 复测两组由应有的 400 变为 200,说明该测试能发现丢失 stop recovery。 额外用例在 base 和 head 都是 110 pass / 2 fail。两个红项向 list_sessions 注入重复值,但两版实际发现入口都已读 iter_session_metadata。保留旧用例结果,并在实际读取点另做四组配对验证:普通发现 HTTP 200 且返回一个会话,重复观测 HTTP 409 且无列表。

标准预合并检查有一项失败:interaction catalog 的 IP-030 没列出 steward_memory。在精确基线和当前提交直接运行同一 smoke,断言相同,且本次 diff 没有修改 catalog 或 namespace 配置。

语义与 CI 对齐

沿用已有会话授权及请求状态词汇。标准验证中的 catalog 红项在可比基线确认,当前需要修改的是该适配器的静态类型合约。

我的整体评价 / Verdict

运行对照证明已验证范围内的原会话恢复和用户读回保持。请先修好两个调用点使用的类型合约,再提交新 head 复审。检查了 native_chat 模块与现有 Settings 由 HTTP 提供的读回。当前只修改后端代码与模块指标基线,页面组件、卡片模板和展示格式无改动。当前验证使用真实本地 Core HTTP / 存储及合成 host,未验证实际安装包、真实 Lark 账号链路和远端宿主。

English verdict: REQUEST_CHANGES. The new writable project_contexts protocol member rejects the real controller at both production call sites. A read-only property removes both diagnostics.

store: ChatSessionStore
coordination_runtime_root: Path
registry_path: Path | None
project_contexts: _ProjectContexts

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve the real ChatRuntimeController caller contract

这里把 project_contexts 声明成可写的 _ProjectContexts。两处正式调用传入的是带 ChatProjectContexts 属性的 ChatRuntimeController。mypy 对可写 Protocol 成员做不变性检查,所以 chat_runtime.py:924 和 chat_server.py:1585 都报 arg-type。当前构造器只读这个对象。把 Protocol 成员声明为只读 property 后,用同一条 strict 命令检查模块及两个调用方,两处诊断均消失。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant