refactor: move matrix tooling into infx / 将矩阵工具迁移到 infx 包

[adibarra]

Description / 说明

Matrix tooling currently loads its schemas as both validation and matrix_logic.validation, creating distinct Python classes. Move the shared implementation into the repository-root infx package so callers share one implementation and one set of schema types.

矩阵工具目前分别通过 validation 和 matrix_logic.validation 加载模式，导致 Python 创建不同的类。将共享实现迁移到仓库根目录的 infx 包，让调用方共用同一套实现和模式类型。

• infx.matrix.generate owns generation; infx.matrix.validation owns schemas. The validator is byte-identical to the original, and the generator only changes its imports.

• Existing script paths, CLI flags, defaults, relative input paths, recipes, and dependencies remain unchanged. Thin compatibility modules preserve old imports, including shared class identity and monkeypatch behavior. No package installation is required to run existing commands from a checkout.

• Historical changelog comparisons extract infx from the requested Git revision when present; older revisions retain their standalone generator. Tests run extracted code with poisoned working-tree source and inputs to catch accidental fallback.

• Update matrix/changelog CI path filters, point the Claude line-count report at the canonical generator (with a legacy base-path fallback), and synchronize English/Chinese architecture documentation. Net production growth is 30 lines for package setup and compatibility; generation algorithms are unchanged.

• infx.matrix.generate 负责生成，infx.matrix.validation 负责模式校验。校验器与原文件逐字节一致，生成器仅调整导入。

• 现有脚本路径、CLI 参数、默认值、相对输入路径、配方和依赖保持不变。轻量兼容模块保留旧导入路径，包括类身份和 monkeypatch 行为。从检出目录运行现有命令无需安装包。

• 历史变更日志比较从指定 Git 修订提取 infx（若存在）；更早的修订继续运行独立生成器。测试故意破坏工作区源码和输入，再运行提取的代码，以发现错误回退。

• 更新矩阵和变更日志 CI 路径过滤器，将 Claude 行数报告指向规范生成器路径（对旧基准修订保留路径回退），并同步中英文架构文档。生产代码净增 30 行，用于包初始化和兼容；生成算法不变。

Related Issue / 关联事项

Next internal-cleanup PR after #2897, #2901, and #2903.

继 #2897、#2901 和 #2903 之后的下一项内部清理。

Validation / 验证

• Full CPU suite: 1,140 tests + 219 subtests passed in 52.81s.

• The exact same 403 behavior tests pass on frozen main (5056e9415, 2.41s) and the refactor (2.46s). Two additional tests verify schema interoperability across old/new import paths in either import order.

• 457 real CLI comparisons: 379 successful cases have byte-identical stdout/stderr; 78 rejected cases have equivalent exit codes and diagnostics, ignoring traceback source locations. Includes controlled topologies and filters plus current-catalog generation.

• 9 additional help/error comparisons across the generator, changelog processor, and changelog validator match exactly when run outside the checkout.

• Negative controls: omitting historical package extraction and restoring duplicate schema definitions each cause two regression tests to fail.

• actionlint -shellcheck= -pyflakes= passes for all three changed workflows. Copy-aware git diff --check passes; existing whitespace in relocated implementation files is preserved.

• 完整 CPU 测试集：1,140 项测试和 219 项子测试全部通过，用时 52.81 秒。

• 完全相同的 403 项行为测试在冻结的 main（5056e9415，2.41 秒）和重构后（2.46 秒）均通过。另有两项测试验证不同导入顺序下新旧路径的模式互操作性。

• 457 组真实 CLI 对比：379 组成功输出的 stdout/stderr 逐字节一致；78 组拒绝用例的退出码和诊断等价，仅忽略 traceback 源码位置。覆盖受控拓扑、筛选条件和当前配置目录。

• 在检出目录外执行生成器、变更日志处理器和校验器的 9 组帮助/错误输出对比，结果完全一致。

• 负向验证：遗漏历史包提取和恢复重复模式定义，分别使两项回归测试失败。

• 三个工作流均通过 actionlint -shellcheck= -pyflakes=；识别文件复制后的 git diff --check 通过，迁移文件保留原有空白。

python3 -m pytest utils/ runners/ experimental/CollectiveX/tests/ -q -o addopts= --tb=short
python3 -m pytest utils/matrix_logic/ utils/test_process_changelog.py utils/changelog_gate_tests/test_validate_perf_changelog.py -q -o addopts= --tb=short

Type of Change / 变更类型

• Other: internal package refactor / 其他：内部包重构
• Documentation update / 文档更新

Checklist / 检查清单

• Tested locally / 已完成本地测试
• Updated English and Chinese documentation / 已同步更新中英文文档
• Performance changelog: no benchmark policy, runtime, recipe, or generated-output changes; no entry appended. No GPU sweep was run. / 性能变更日志：未修改基准策略、运行时、配方或生成输出，因此未追加条目；未运行 GPU 扫描。
• Sweep reuse: not requested; this draft has not been merged. / 扫描复用：未请求；此草稿尚未合并。

---

Note

Medium Risk
Refactors central sweep matrix generation and validation used by changelog gating and CI; behavior is intended to be unchanged but any import or historical-revision extraction bug could alter generated benchmark matrices.

Overview
Moves benchmark matrix generation and Pydantic validation from utils/matrix_logic/ into a new repository-root infx package (infx.matrix.generate, infx.matrix.validation). process_changelog.py and validate_perf_changelog.py now import the canonical modules directly.

utils/matrix_logic/generate_sweep_configs.py and validation.py become thin compatibility shims: they add the repo root to sys.path, delegate to infx, and register themselves in sys.modules so legacy import paths and monkeypatches still hit the same module objects (avoiding duplicate schema classes).

CI path filters and synchronized English/Chinese architecture docs point at the new locations. The Claude PR review workflow’s matrix generator line-count rule targets infx/matrix/generate.py, with a fallback to the old path for pre-migration diffs. Append-only changelog handling is documented to extract infx from the requested Git revision when present.

Tests add coverage for running the legacy script from another working directory and for schema/type identity across mixed legacy and package import orders.

^{Reviewed by Cursor Bugbot for commit 6536a90. Bugbot is set up for automated code reviews on this repo. Configure here.}

[claude]

Claude finished @adibarra's task in 4m 42s —— View job

---

Review of PR #2911 / PR #2911 审查

• Gather context (AGENTS.md, diff vs origin/main)
• Verify moved code is identical to originals (validation.py, generate_sweep_configs.py)
• Review compatibility shims (class identity / monkeypatch behavior)
• Review historical infx extraction in process_changelog.py
• Review CI path filters and docs updates
• Post line count report for generate_sweep_configs.py
• Post review summary

LGTM - no blocking issues found.

Independently verified the PR's core claims: infx/matrix/validation.py is byte-identical to the original utils/matrix_logic/validation.py, and infx/matrix/generate.py differs from the original generator only in its import block (relative from .validation import replacing the sys.path sibling-import hack). The sys.modules[__name__] = ... shim pattern correctly unifies module identity across all four legacy import paths, preserving Pydantic/Enum class identity and monkeypatch behavior. The Path(__file__).resolve().parents[2] repo-root computation in generate.py:226 resolves to the same directory at the new package depth, both in a checkout and in the generation_inputs_at_ref extraction temp dir (where the recipe-lookup fallback behavior is unchanged from main). The historical extraction correctly adds infx to git ls-tree so post-refactor revisions run their own package code, and the legacy-layout test confirms pre-refactor revisions still work. All external callers (profile.yml, e2e-tests.yml, experimental/operatorx) invoke the script by unchanged path and are unaffected.

独立验证了核心声明：校验器逐字节一致，生成器仅改动导入；兼容模块通过 sys.modules 替换保证四条导入路径共享同一模块对象；历史提取逻辑对迁移前后的修订均正确。未发现阻塞性问题。

Note: I could not run the pytest suites in this environment (command approval not granted for pytest/python3 execution), so runtime verification relies on the PR's reported results and CI; my verification above is from static diff analysis.

注：本环境无法执行 pytest（命令未获批准），运行时验证依赖 PR 报告的结果和 CI；以上结论基于静态差异分析。

--- · Branch

[claude]

📊 Line Count Report

• Total Lines: 14
• Base Lines: 1574
• Change: 📉 -1560 lines

(Implementation moved to infx/matrix/generate.py; this file is now a compatibility shim.)

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.