Skip to content

refactor(collaboration): slim conversation_binding.ts from 2,000 to 1,769 LOC - #9266

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-conversation-binding-20261122
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-conversation-binding-20261122

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Pure behavior-preserving net-negative-LOC refactoring of loopx/control_plane/collaboration/conversation_binding.ts to bring it cleanly under the 2,000-line maintainability ceiling (and target <= 1,785 LOC) without modifying loopx/canary/module_metric_baseline.json or extracting any new sibling module.

  • Line count delta: 2,000 LOC → 1,769 LOC (-231 net LOC; 1 file changed, 767 insertions(+), 998 deletions(-)).
  • Contract & prose invariance: Zero changes to any of the 7 exported functions (resolveConversationAgentTarget, planConversationBinding, resolveBoundConversation, listLocalBoundSessions, planBoundConversationRequest, stewardCommand, authorizeStewardCreation), signatures/types, return payload shapes/keys/values, reason codes, state transitions, or verbatim agent/user guidance prose.

What Changed

Consolidated repeated validation guards, closed command/key sets, endpoint/turn/proof predicates, response envelope builders, and quota/cooldown helpers inside loopx/control_plane/collaboration/conversation_binding.ts:

  • Closed constant tables: NO_RECOVERY, RESPONSE_METADATA_KEYS, RECOVERY_FAMILY_KEYS, RECIPIENT_COMMANDS, STEWARD_COMMANDS, VALID_REQUEST_COMMANDS, PENDING_ERROR_CODES.
  • Scalar & record guards: ensure, matchId, isNonEmptyStr, isNonBlankStr, isBareSha256, isSafeInt, allUnique, hasNoFields, hasAnyField, hasConflictingRecoveryKey, fieldsMatch, isStewardEndpoint, boundChannelId.
  • Recovery / turn / proof & review helpers: recoveryClientBase, reviewClientId, matchesReservation, matchesOriginalTurn, isFreshEpochSeconds, withinTurnWindow, validNativeAnchor, isClosedNativeSegment, matchesAttachedSession, matchesPrivateOwnerSource, matchesNativeProofBase, codexErrorDetail, provenanceThreads, admittedRecoveryResult, parseCorePreparationEvents, cooldownNotBefore, matchesFailedTurnBase, stewardAnswerWithCapacity, reviewCandidate, matchesRetainedWorkReview, isEligibleEndpointPair, isValidQuotaRecord.

Verification

All checks ran locally on final commit f905fefbe0eea8e73a9279a22d8875b1bdf186e1 (or identical final file contents immediately prior to commit):

  • npm run typecheck:control-plane: passed (0 errors)
  • Core & dependent TS suite (8 files: conversation_binding.test.ts, steward_managed_mode.test.ts, steward_pr_merge_auth.test.ts, project_conversation.test.ts, action_review_plan.test.ts, action_review_plan_session.test.ts, effect_runtime_handlers.test.ts, effect_runtime_handler_loading.test.ts): 162 passed, 0 failed, 0 skipped
  • Matching control-plane TS suite (44 files covering conversation_binding, steward, collaboration, action_review_plan, excluding pre-existing unrelated content_digest_single_owner.test.ts origin/main failure on control_plane/quota/execution_loss_closeout_record.ts where conversation_binding.ts passes in CANONICAL_CONSUMERS): 517 passed, 0 failed, 10 skipped (postgresql)
  • Required Python pytest suites (tests/canary/test_maintainability_ratchet.py, tests/test_chat_project_coordination.py, tests/test_chat_manager_context.py, tests/test_manager_context_roundtrip.py): 215 passed
  • Additional binding/web/peer Python pytest suites (tests/test_chat_conversation_bindings.py, tests/control_plane/test_bound_owner_web_input.py, tests/control_plane/test_original_conversation_peer.py): 229 passed
  • scripts/check_rfc_bilingual.py --base origin/main --head HEAD: passed
  • Public-boundary scan (loopx check --scan-path loopx/control_plane/collaboration/conversation_binding.ts): 0 errors, 0 warnings (5 checks passed)
  • Change Quality Qualification (change-quality verify): status: "valid", decision: "pass", receipt_id: "cqr_38e4773444484f2a0586"
  • Pre-merge gate (loopx canary premerge --from-git-diff --git-diff-base origin/main): ok: true (4 direct checks + 2 catalog canaries + 8 risk-profile smokes = 14 passed, 0 failed)

Consolidate repeated recovery turn admission, cooldown backoff, failed-turn preflight, retained-work review, native anchor/segment validation, and request-error assertion patterns into local helpers while preserving all exported signatures, payload shapes, reason codes, state transitions, and verbatim prose.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@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)

动机 / Motivation

维护控制面外部会话绑定、恢复调度与 Steward 授权逻辑的开发者,以及通过 effect_runtime_handlers.ts 和 Python conversation_bindings.py 调用这 7 个导出决策入口的上游控制面与端到端链路。

修改前:conversation_binding.ts 为 2,000 行(距离 2,000 行上限仅余 0 行),恢复计划和前置检查分支散布重复的字段存在性判断与回复封装。修改后:通过在同一文件内提炼闭集常量表和单职责局部辅助函数,文件降至 1,769 行(净减 231 行),为后续演进留出 231 行安全余量且不改变任何公开 API 或运行时行为。

wc -l loopx/control_plane/collaboration/conversation_binding.ts 降至 1,769 行(-231 LOC),control-plane-maintainability-ratchet-smoke.py、npm run typecheck:control-plane、conversation_binding.test.ts(70/70)及全套 Python 绑定测试全部通过,基线对比探测在 7 个导出函数上输出与报错完全一致。

明确非目标(Non-goals):不修改任何公开函数签名或返回值字段、不修改 loopx/canary/module_metric_baseline.json、不抽取新同级文件、也不顺带修复基线仓中无关模块(如 execution_loss_closeout_record.ts)的固定清单漂移。

改动思路 / Approach

整体重构策略聚焦于单文件内部高内聚去重与可逆性,先将散落各处的只读错误码表、回复元数据键集、命令合法集与基础空恢复对象收拢为顶层只读常量表,再为高频重复的字段合法性断言、回合窗口判定、原生分段锚点核验及恢复准入包装抽取短小单职责私有辅助函数。这样在不拆分新模块、不新增公开接口且不触碰基线例外表的前提下,显著消除了样板冗余,同时令每条分支的前置拒绝与恢复边界更加集中可读。

保留在单一控制面所有权文件 conversation_binding.ts 内,新增的局部辅助函数与闭集表格属于纯 local_helper 职责,内聚且无新边界。 当前 PR 边界:仅重构 loopx/control_plane/collaboration/conversation_binding.ts(2,000 -> 1,769 行),不新增同级文件且不改动 baseline 配置。

对比维度 基线状态 (c563a473d845) 当前 HEAD (f905fefbe0ee)
文件行数与净变化 2,000 行(处于基线阈值边缘) 1,769 行(-231 净行数;+767 / -998)
校验与封闭集合 多处散落的字面量数组和重复 if (!...) throw new EffectRuntimeRequestError(...) 提炼 NO_RECOVERY、RESPONSE_METADATA_KEYS、RECOVERY_FAMILY_KEYS、VALID_REQUEST_COMMANDS、PENDING_ERROR_CODES 与 ensure / matchId / isNonEmptyStr / isBareSha256 等辅助函数
恢复准入与回合匹配 planNativeQuotaRecovery、planUnfinishedWork 等各自内联失败回合、冷却窗口与只读复审判定 集中由 admittedRecoveryResult、cooldownNotBefore、matchesFailedTurnBase、matchesRetainedWorkReview 与 stewardAnswerWithCapacity 统一表达
外部导出与测试覆盖 7 个导出接口 7 个导出接口签名、返回结构与异常文本 100% 保持,新增文件内局部复用无额外依赖

说明:上方采用紧凑对比表替代额外渲染图(未执行浏览器渲染,仅基于精确 HEAD Diff 与类型/单测核对)。

具体改动 / Changes

本次仅修改生产控制面单文件 loopx/control_plane/collaboration/conversation_binding.ts(+767 / -998,净减 231 行)。规范依据说明(no_spec / 无新增或变更的功能规范):本次是对既有控制面模块做的等价去重重构以遵守仓库 2,000 行可维护性守门,不涉及新功能 RFC 或接口协议更改,所有既有契约约束均沿用原有定义。

关键代码讲解

  1. planConversationBinding 与入口绑定规划:继续承担外部对话绑定配置、授权智能体目标、撤销与断开的全部核心状态规划,并继续由 loopx/control_plane/effect_runtime_handlers.ts:657 唯一注册调用。重构中将重复的参数类型校验和正则模式断言收口为 ensure、matchId、isNonEmptyStr 与 isSafeInt,保持错误消息和状态版本校验顺序完全不变。
  2. planBoundConversationRequest:作为绑定对话命令与恢复规划总入口(被 effect_runtime_handlers.ts:660 消费),利用封闭常量表 RECIPIENT_COMMANDS、STEWARD_COMMANDS 与 VALID_REQUEST_COMMANDS 替代重复字面量集合,命令校验失败仍精确抛出 unsupported external conversation command,并在携带 context_recovery 时交由 planContextRecovery 分派。
  3. admittedRecoveryResult:新提炼的文件私有构造辅助函数,为 planNativeQuotaRecovery、planWorkAfterResultReview、planRelatedResultReview 与 planCompletedResultReview 等恢复规划分支统一构造 {operation: "admit_turn", recovery_candidate: true, ...} 响应载荷,消除了大量样板对象拼接,同时严格保留原有键集合与附加字段透传。
  4. matchesFailedTurnBase 与 matchesRetainedWorkReview:分别统一收口配额/路由/准备恢复中对失败回合基准、预留号、时间窗与错误码集合的多项校验,以及已完成结果只读复审中对未提交元数据、纯文本回答、原生分段闭合性与所有者来源的联合守门条件,在降低重复度的同时原封不动保留所有拒止条件。

对主干的风险 / Risks

无阻塞性问题(No blocking findings)。

  • 生产调用与范围合理性(Scope fit & Proportionality):通过全仓检索已确认 loopx/control_plane/effect_runtime_handlers.ts:643-661 与 loopx/control_plane/collaboration/project_conversation.ts:5,42 为全部 7 个导出符号的活跃生产调用路径,且 loopx/capabilities/native_chat/conversation_bindings.py 通过 Python 桥接持续调用。所有提取的常量表与函数均属于 local_helper 职责,未引入任何新机制、新接口、功能开关(default_off_isolation 不适用)或权限模型拓展(authority_semantics 不适用),相比修改 baseline 或拆文件方案风险与维护成本最低。
  • 负向路径与变异敏感度:基线 c563a473d845 与精确 HEAD(f905fefbe0ee)运行同套 70 条原生 TS 单元测试均 70/70 全过;15 组覆盖 7 个导出接口的配对反事实对比(含 9 组正常返回及 6 组非法操作、越权发送者、不匹配智能体、异常命令、失效指令与过期 Steward 授权拒绝)返回与抛错信息逐字节一致(指纹 493858c068c6feb2)。故意将 VALID_REQUEST_COMMANDS 中的 "status" 移除做变异验证时,探针立即因消息漂移(unsupported external conversation command vs invalid project conversation context)报错捕获,验证检验灵敏有效。
  • 本地验证矩阵与无关基线归因:npm run typecheck:control-plane(PASS,0 errors);8 文件关联 TS 控制面测试集(PASS,162 passed,0 failed);Python 必跑 4 套(PASS,215 passed)及 3 套绑定/Peer 扩展集(PASS,229 passed);scripts/check_rfc_bilingual.py、loopx check(0 errors/warnings)、CQR 验证(PASS,cqr_38e4773444484f2a0586)与 loopx canary premerge(PASS,14/14 checks)均通过。44 文件 TS 匹配集(517 passed,0 failed,10 条依赖实时 PostgreSQL 服务按环境跳过)中,无关基线文件 tests/control_plane_ts/content_digest_single_owner.test.ts 在基线 c563a473d845 与精确 HEAD 上出现完全相同的 1 条基线失败(control_plane/quota/execution_loss_closeout_record.ts 固定消费者列表缺失),而 conversation_binding.ts 在该测试内的自身断言通过且本 PR 未更改消费者清单,属 pre_existing_unrelated,不阻断本次评审结论。远程 CI 按 Goal 配置未作等待(wait_for_ci: false)。
  • 残留风险与最强待补验证(Residual risk & Strongest missing validation):残余风险为本地跳过了依赖实时 PostgreSQL 服务的 10 条通用控制面 TS 测试(虽然 conversation_binding.ts 本身无直连数据库逻辑),以及上述主干无关测试 content_digest_single_owner.test.ts 的既有失败;最强的补充验证是在配备可用 PostgreSQL 测试实例的环境中运行完整 test:postgresql-authority-store 全套以补齐那 10 条环境跳过项。

我的整体评价 / Verdict

  • 长程与用户体验影响:long_horizon 与 user_experience 均判定为 preserved(保留原行为等价,所有状态机转移、恢复预算、冷却边界与错误输出未出现任何退化或额外用户交互);视觉评审 visual_review 因纯后端控制面模块不涉及界面展示而为 not_applicable:本次修改仅涉及后台 TypeScript 控制面模块 loopx/control_plane/collaboration/conversation_binding.ts 的内部重构,不涉及任何前端渲染视图、页面布局或可见文案变动。(unverified_scope: none)。
  • 可观测语义与代码体量:基于基线 c563a473d845 与精确审查提交 f905fefbe0ee 的成对执行与变异验证,确认 observable_semantics 保持 equivalent 且未改动任何 Agent/用户引导文本。code_volume 净减 231 行(2,000 -> 1,769),在零兼容负担下实现了实质性的结构简化,架构边界收敛(change_proportionality: proportionate),且未引入新公开语义词汇(semantic_alignment: not_applicable,仅在单文件内复用已有常量字面量)。
  • 精确头部与结论:已在精确头 9266@f905fefbe0eea8e73a9279a22d8875b1bdf186e1 核对全部本地实测与 CQR 回执 cqr_38e4773444484f2a0586,无任何待修复阻塞项。

English verdict: APPROVE

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