Skip to content

refactor(types): eliminate Any annotations and slim authority and upgrade - #8991

Merged
huangruiteng merged 1 commit into
mainfrom
codex/authority-upgrade-slim-20261118
Nov 18, 2026
Merged

huangruiteng merged 1 commit into
mainfrom
codex/authority-upgrade-slim-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Eliminates all Any annotations (45 -> 0 and 46 -> 0, dict[str, Any] -> 0), slims boilerplate and duplication, and registers zero-Any ceilings in loopx/canary/module_metric_baseline.json for:

  • loopx/authority.py: 800 -> 686 lines, 45 -> 0 Any, 0 -> 0 dict[str, Any]
  • loopx/upgrade.py: 1178 -> 1062 lines, 46 -> 0 Any, 0 -> 0 dict[str, Any]

Changes

  1. loopx/authority.py:
    • Replaced all Any annotations with Payload = dict[str, object], PayloadView = Mapping[str, object], Sequence[str], object, and private narrowing helpers (_dict_view, _int_value).
    • Consolidated markdown rendering (_render_authority_markdown) for render_authority_source_markdown and render_doc_registry_authority_import_markdown.
    • Consolidated dry-run / mutate_project_registry commit and response assembly (_commit_authority_entry) across register_authority_source and import_doc_registry_authority.
    • Shared _INT_SUMMARY_FIELDS and collapsed the empty/populated skeleton in compact_authority_registry.
  2. loopx/upgrade.py:
    • Replaced all Any annotations with Payload, PayloadView, Sequence[...], object, and private narrowing helpers (_dict_view, _dict_list, _str_list, _int_value), importing build_heartbeat_prompt from .control_plane.heartbeat.builder so strict mypy checks its typed signature.
    • Consolidated repeated boilerplate via _unavailable_policy_audit, _first_match, _bullet_fields, single-pass status bucketing in build_loop_activation_summary, single-pass summary aggregation (_summarize_managed_heartbeats) in build_upgrade_plan, and single-pass status/warning extraction in render_upgrade_plan_markdown.
  3. loopx/canary/module_metric_baseline.json:
    • Registered "loopx/authority.py" (any_count: 0, dict_any_count: 0, lines: 686) before "loopx/bootstrap_command_pack.py".
    • Registered "loopx/upgrade.py" (any_count: 0, dict_any_count: 0, lines: 1062) between "loopx/todos.py" and "loopx/worker_bridge.py".

Verification (head 9e4da5eb94a189087f6d1abc8fdafe92195b8c95)

  • uv run --extra test mypy --strict --follow-imports=silent loopx/authority.py loopx/upgrade.py: Success: no issues found in 2 source files
  • uv run --extra test mypy: Success: no issues found in 17 source files
  • uv run --extra test ruff check loopx/authority.py loopx/upgrade.py: All checks passed!
  • loopx.canary.maintainability_ratchet.module_metrics:
    • loopx/authority.py: {'lines': 686, 'any_count': 0, 'dict_any_count': 0}
    • loopx/upgrade.py: {'lines': 1062, 'any_count': 0, 'dict_any_count': 0}
  • uv run --extra test pytest -q -n 4 (15 authority, upgrade, maintainability ratchet, and semantic vocabulary drift test files): 943 passed, 2 skipped in 97.26s
    • Note: separately tested tests/architecture/test_source_session_registry_denial.py passes on loopx/authority.py and fails only on an unrelated pre-existing origin/main drift (loopx/presentation/goal_storage_api.py).
  • uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: passed (selected=3 executed=3 failures=0, manual_holds=0, including module_ceiling_colocation: passed)
  • uv run --extra test loopx --runtime-root <isolated-tmp> check --scan-path loopx/authority.py --scan-path loopx/upgrade.py --scan-path loopx/canary/module_metric_baseline.json: ok: True, errors=0, public boundary scan clean: 3 files
  • Authority & upgrade example smokes (register-authority-source-smoke.py, import-doc-registry-authority-smoke.py, upgrade-plan-smoke.py, peer-agent-migration-smoke.py): all passed.

…rade

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)

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

动机 / Motivation

受影响调用方与维护者:所有使用或集成 loopx/authority.py 与 loopx/upgrade.py 的本地控制面、CLI 与测试调用方(包括 loopx/cli_commands/registry_authority.py、loopx/cli_commands/support_control_promotion.py、loopx/cli_commands/quota_scheduler_followup.py、loopx/cli_commands/quota_should_run.py、loopx/cli_commands/automation_prompts.py、loopx/history.py、loopx/registry.py、loopx/global_registry.py、loopx/project_map.py、loopx/extensions/external_connector_provider.py、loopx/codex_app_thread_activity.py、loopx/entrypoint.py、loopx/control_plane/heartbeat/automation_upgrade.py 与 loopx/control_plane/heartbeat/installed_prompt_update.py),以及 loopx/canary/ 可维护性棘轮检查。

修改前(origin/main a79e781340):loopx/authority.py 共 800 行且含 45 处 Any、loopx/upgrade.py 共 1178 行且含 46 处 Any(合计 91 处 Any)。两文件内存在多处重复样板:例如 authority.py 中 render_authority_source_markdown 与 render_doc_registry_authority_import_markdown 重复拼装 Markdown、register_authority_source 与 import_doc_registry_authority 重复执行 dry-run/mutate_project_registry 提交与回执构造、compact_authority_registry 重复声明空摘要与填充摘要字典;upgrade.py 中 build_upgrade_plan 对 managed 重复执行 9 次独立 sum(...) 遍历、三处重复构造不可用 prompt_policy_audit 字典、render_upgrade_plan_markdown 重复拼装数十行 - key: \val`模板,且loopx/upgrade.py因从无类型转发层.heartbeat_prompt导入build_heartbeat_prompt而在严格类型检查下触发no-untyped-call与no-any-return错误。同时两文件尚未录入loopx/canary/module_metric_baseline.json零Any 棘轮。修改后(9e4da5e):loopx/authority.py精简至686 行(45 Any -> 0)、loopx/upgrade.py精简至1062 行(46 Any -> 0),两文件 dict_any_count均为0,并在 loopx/canary/module_metric_baseline.json对应字母序位置锁入零Any` 基线与行上限。

可观测结果:module_metrics 输出 authority.py 为 {"lines": 686, "any_count": 0, "dict_any_count": 0}、upgrade.py 为 {"lines": 1062, "any_count": 0, "dict_any_count": 0};mypy --strict --follow-imports=silent 两文件 0 错误,全仓 mypy(17 个源码文件)0 错误,ruff check 两文件全过;15 个相关测试套件 943 passed, 2 skipped in 97.26s(另有 tests/architecture/test_source_session_registry_denial.py 在 loopx/authority.py 路径通过,仅在基线预存的 loopx/presentation/goal_storage_api.py 失败);canary premerge --tier quick 6 项直接检查(含 module_ceiling_colocation)与 3 项目录金丝雀全部通过(failures=0);loopx check --scan-path ... errors=0、public boundary scan clean: 3 files。

非目标边界:本 PR 不改动权威源注册或心跳升级计划的运行时 JSON 结构、错误文本、CLI 参数契约、既有的 docstring 与解释性注释,也不修改下游调用方模块。

改动思路 / Approach

全部强类型收口、窄化辅助函数与去重合并均限制在 loopx/authority.py 与 loopx/upgrade.py 原生边界内,未新增并行决策层,亦未修改任何外部调用方。

当前 PR 边界:仅修改 loopx/authority.py、loopx/upgrade.py 的类型注解与内部样板合并,以及 loopx/canary/module_metric_baseline.json 的两条基线记录。

  • 统一无 Any 类型别名与安全窄化边界:在模块导入语句之后定义 Payload = dict[str, object] 与 PayloadView = Mapping[str, object](规避 Ruff E402),对外返回值保持可变 Payload(兼容 cli_commands/registry_authority.py 与 support_control_promotion.py 的 PrintPayload 契约),对只读入参放宽为 PayloadView / Sequence[...]。通过 _dict_view、_dict_list、_str_list、_int_value 进行运行时显式窄化与类型守卫,保持对非法/缺失字段的原有回退行为,同时在 _apply_authority_entry 中原地修改 goals[goal_index] 对象引用不复制,确保注册表写回语义不变。
  • 直接复用已有类型化心跳构建器:loopx/upgrade.py 改由 .control_plane.heartbeat.builder 导入带完整签名的 build_heartbeat_prompt,替代无类型透传包装 loopx/heartbeat_prompt.py,在保持运行行为完全一致的前提下消除 mypy --strict 的 [no-untyped-call] 报错。
  • 合并重复样板并保留架构不变量:authority.py 抽出 _render_authority_markdown 与 _commit_authority_entry(仍保留直接调用 load_project_registry 与 require_runtime_compatible_project_registry 以满足 test_source_session_registry_denial 静态允许清单),并用 _INT_SUMMARY_FIELDS 统一 compact_authority_registry 的空值与非空摘要构造;upgrade.py 抽出 _unavailable_policy_audit、_first_match、_bullet_fields 与 _summarize_managed_heartbeats 单次聚合遍历,同时保证 build_loop_activation_summary 与 render_upgrade_plan_markdown 均一次遍历完成状态归类与 Markdown 渲染。

具体改动 / Changes

本次 diff 仅修改 3 个文件(+563 / -783,净减少 220 行):

  1. loopx/authority.py(800 -> 686 行,-114 行,45 Any -> 0):清除全部 Any,保留全部导出符号、错误文案与原注释/docstring。
  2. loopx/upgrade.py(1178 -> 1062 行,-116 行,46 Any -> 0):清除全部 Any,合并重复汇总与 Markdown 渲染样板,保留全部导出符号与原注释/docstring。
  3. loopx/canary/module_metric_baseline.json(+10 / -0):按字母序分别在 loopx/bootstrap_command_pack.py 之前加入 loopx/authority.py(any_count: 0, dict_any_count: 0, lines: 686),在 loopx/todos.py 与 loopx/worker_bridge.py 之间加入 loopx/upgrade.py(any_count: 0, dict_any_count: 0, lines: 1062)。

本 PR 为纯粹的代码结构与静态类型整理,无外部功能规范文档变更(spec_basis: no_spec),对照目标是各导出函数的既有行为与严格类型/棘轮契约(已在当前 head 全部兑现)。

关键代码讲解

  • loopx/authority.py:381 _commit_authority_entry 与 loopx/authority.py:220 _render_authority_markdown:分别收拢 register_authority_source(L428)与 import_doc_registry_authority(L472)的 dry-run/mutate_project_registry 提交分支与回执拼接,以及 render_authority_source_markdown(L248)与 render_doc_registry_authority_import_markdown(L328)的 Markdown 输出框架。关键不变量在于 dry-run 分支依然直接调用 load_project_registry 与 require_runtime_compatible_project_registry,且输出字段顺序与文案与修改前逐字一致。
  • loopx/authority.py:631 compact_authority_registry:复用 _INT_SUMMARY_FIELDS 合并 if not raw 与常规路径的 17 项摘要字典初始化,使用 _int_value 将 object 安全转为整数,避免直接对 object | None 调用 int(...) 引发类型错误,同时保留缺省 0 与 "unknown" 语义。
  • loopx/upgrade.py:127 goal_heartbeat_prompt 与 loopx/upgrade.py:763 _summarize_managed_heartbeats:goal_heartbeat_prompt 改从 .control_plane.heartbeat.builder 导入类型化 build_heartbeat_prompt 并规范化 Sequence[str] | None 能力参数与 execution_profile 字典;_summarize_managed_heartbeats 将 build_upgrade_plan(L790)原先 9 次独立列表推导式合并为单次遍历聚合,消除了局部同名变量覆盖(not_installed 在 bool 与 int 间的复用)导致的严格 mypy 报错。
  • loopx/upgrade.py:984 render_upgrade_plan_markdown:借助 _bullet_fields(L119)批量渲染 summary、manifest、propagation 与 migration 的项目符号列表,并在单次 installed.items() 循环中同步收集状态串与 prompt_policy_warnings,保持输出文本与段落顺序完全不变。

对主干的风险 / Risks

  • 调用方类型兼容性与输入窄化回退:下游调用方中 history.py、registry.py、global_registry.py、project_map.py、external_connector_provider.py、cli_commands/registry_authority.py、cli_commands/support_control_promotion.py、cli_commands/quota_scheduler_followup.py、entrypoint.py 等均已在真实工作区代码库校验。只读参数采用 PayloadView(Mapping[str, object])可同时接受 dict[str, Any] 与 dict[str, object];返回值保持 Payload(dict[str, object])可满足 PrintPayload 与 HostObservationResolver 的协变/不变要求。_int_value 对空值返回 0,_dict_view/_dict_list 对非预期类型回退空集合,与原 isinstance(..., dict) 行为一致;唯一潜在触发点为向整数字段传入非数字且非字符串对象,此时同样会在 int(...) 抛出异常。
  • 独立验证与远端 CI 归因:
    • module_metrics:PASS(authority.py 686 行 / 0 Any / 0 dict_any;upgrade.py 1062 行 / 0 Any / 0 dict_any)。
    • mypy --strict --follow-imports=silent loopx/authority.py loopx/upgrade.py:PASS(0 errors);全仓 uv run --extra test mypy(17 个文件):PASS(0 errors);ruff check loopx/authority.py loopx/upgrade.py:PASS。
    • pytest(15 个 authority、upgrade、棘轮与语义词表测试文件):PASS(943 passed, 2 skipped in 97.26s);4 个相关示例 smoke(register-authority-source-smoke.py、import-doc-registry-authority-smoke.py、upgrade-plan-smoke.py、peer-agent-migration-smoke.py):PASS;canary premerge --tier quick:PASS(6 direct checks 含 module_ceiling_colocation + 3 catalog canaries,failures=0, manual_holds=0);loopx check --scan-path ...:PASS(errors=0, public boundary scan clean: 3 files)。
    • 预存基线与远端诊断说明(非本 PR 引入):tests/architecture/test_source_session_registry_denial.py 在 loopx/authority.py 通过允许清单校验,但因 origin/main(a79e781340)已存在的 loopx/presentation/goal_storage_api.py 漂移而失败;远端 CI 中 Sign-off、inspect-pr-diff、dependency-review、changes、loopx-codex-provider-routing、loopx-repo-health、loopx-obelisk 与 Summary 已完成并 SUCCESS,kernel-static-checks 仅因 origin/main 预存的 tests/test_chat_manager_model_adoption.py:416:67 F811 Redefinition of unused steward 失败(已用 git show origin/main:tests/test_chat_manager_model_adoption.py 与本地 ruff check 复核为基线问题,直接触发同 workflow 下游 stage2c-correctness-e2e、checks、pytest 与 merge-gate 失败),loopx-core 与 prepare 仍在运行中。

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 彻底消除 loopx/authority.py(45 处)与 loopx/upgrade.py(46 处)共 91 处 Any、大幅精简两模块(共减少 230 行代码)并写入 module_metric_baseline.json 零 Any 棘轮基线,防止后续迭代重新引入类型松散与重复样板。
  • User-experience 影响:not_applicable — 内部 Python 静态类型收敛与样板去重,不改变任何 CLI 参数、JSON 输出结构、错误文案或前端界面,visual_review 为 not_applicable。
  • 可观测语义 / 复用 / 词表:observable_semantics 为 equivalent,repository_reuse 为 reused,authority_semantics 与 semantic_alignment 均为 aligned(candidate_decision="reuse_existing",未新增或更改任何语义词表)。

代码改动边界克制、局部与跨调用方静态检查及 943 条单测全部通过,未发现 P0/P1/P2 问题;本 PR 涉及 loopx/authority.py、loopx/upgrade.py 与控制面棘轮基线且当前为作者自有 PR,合并需遵循仓内维护者授权与 CI 门禁流程。

English verdict: APPROVE exact head 9e4da5e (author-owned COMMENTED approval review); eliminates all 91 Any usages across loopx/authority.py (800 -> 686 lines, 45 -> 0 Any) and loopx/upgrade.py (1178 -> 1062 lines, 46 -> 0 Any), consolidates duplicated markdown/commit/aggregation boilerplate, and locks zero-Any ceilings in loopx/canary/module_metric_baseline.json, verified by strict/repo mypy (0 errors), ruff (passed on changed files), 943 passed / 2 skipped pytest cases, 4 example smokes, loopx check (clean), and quick premerge canaries (0 failures); remote kernel-static-checks failed solely on an unchanged origin/main F811 lint in tests/test_chat_manager_model_adoption.py.

@huangruiteng
huangruiteng merged commit 2a36e09 into main Nov 18, 2026
31 of 36 checks passed
@huangruiteng
huangruiteng deleted the codex/authority-upgrade-slim-20261118 branch November 18, 2026 06:38
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.

2 participants