Repository navigation
fix(update): require qualified defaults for runtime previews - #9026
loopx-agent wants to merge 1 commit into
Conversation
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google (self_reported; host runtime observation unavailable)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
本次针对 PR #9026 的精确提交 6a9894c6909da64c97f4da39ad15ee343b344514 完成源码走读、双版本(基线 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 与当前 HEAD 6a9894c6909da64c97f4da39ad15ee343b344514)反事实对比探针、单元测试、架构测试及 premerge 门禁验证。结论:无阻断性问题(no blocking findings),建议 APPROVE(因作者与当前登录审查账号同为 PR 所属方,按规则以 COMMENTED 评审发布批准结论,且不执行合并或删分支操作)。
动机 / Motivation
通过独立引导脚本 scripts/install-from-github.sh(下载 update-artifact.py)安装预览运行时,或运行 loopx update check、loopx update plan、loopx update apply、loopx upgrade 更新 release snapshot(含 --ref main 与固定 40 位提交 SHA)的维护者与开发者。
此前虽然 PR #9018 已拦截新构建的未达标 main 快照发布,但此前已发布的 runtime-main 历史描述符(对应提交 65ae1d6)缺少 default_contract 字段。改动前 validate_manifest 与 install_artifact 仅在 default_contract 键存在时才校验,导致引导安装脚本与 loopx update 都会下载并激活该无标记预览包,随后在默认配额 CLI 暴露未定型完整的 complete_turn writer。改动后,凡是在激活或更新解析路径选择 channel 为 main 的描述符,即使缺少 default_contract,也会在下载任何归档字节之前被统一拦截,而只读历史元数据校验和既有 stable 旧版发行版安装保持兼容。
对无 default_contract 或声明不合格 default_contract 的 main 预览(无论移动标签 main 还是固定提交 SHA),loopx update check 与 update plan 会返回 target_status=blocked 与 apply_supported=false,update apply 与独立引导脚本会在下载压缩包或触发本地安装器之前失败退出,同时不改写已有软链接与下载缓存;历史元数据读取与元数据一致的旧版 stable 发行版仍可正常完成校验与安装。
本 PR 不改变 C1 complete_turn 默认切换的资格门,不修改已发布的远端 runtime-main 资产内容,不替显式 --source/--archive-url 开发者源码构建路径或 pip/pipx/源码检出分支增加预览拦截,也不在本 PR 中部署 GitHub Pages 导出产物或扩展非 macOS 平台的实机安装覆盖。
从工程必要性来看,仅仅依靠 PR #9018 修补发布端无法阻断早已发布到 runtime-main 的历史无标记预览描述符;若不做消费者侧激活校验,任何运行 loopx update apply --ref main 或公开引导安装脚本的机器仍会静默拉取并激活不合格运行时,使默认配额接口在未满足 C1 单会话成果与全成本门槛前提前切换。
改动思路 / Approach
把激活门控放回既有的元数据边界 validate_manifest 与 resolve_artifact(通过显式参数 for_activation 控制),由 CLI 目标解析 prepare_target、直调入口 install_artifact 以及 Pages 引导脚本 main 共同复用,避免新增平行开关、旁路缓存或第二套契约校验器;历史元数据读取保留 for_activation=False 默认兼容,已发布的旧版 stable 发行版在归档 runtime-artifact.json 与描述符一致时继续放行。
当前 PR 只收口消费者侧的运行时快照激活门控(update_artifact.py、update_source.py 及其单测与 release-readiness.md 说明),与已合入的发布端探测 PR #9018 形成闭环;Pages 站点的构建发布与 Linux/Windows 实机引导运行留待现有发布流水线推进。
控制流与入口收口对比如下(基于精确提交 6a9894c6909da64c97f4da39ad15ee343b344514 的源码走读与基线/HEAD 双版本执行对照):
| 场景 / 调用路径 | for_activation |
描述符 channel / default_contract |
归档 runtime-artifact.json |
基线 4a0188c1ca |
当前 HEAD 6a9894c690 |
|---|---|---|---|---|---|
历史只读校验 validate_manifest(v) |
False(默认) |
main(缺 default_contract) |
未读取 | 允许读取 | 允许读取(兼容保留) |
CLI update check/plan/apply --ref main 或 --ref <SHA> |
True(prepare_target) |
main(缺 default_contract) |
不进入下载 | 解析成功并允许 apply | target_status=blocked,apply_supported=false |
引导脚本 update-artifact.py(main 或 <SHA>) |
True(main()) |
main(缺 default_contract) |
不进入下载 | 尝试下载激活 | 下载前报错退出(rc=1),缓存与软链不变 |
直调 install_artifact 传入缓存 plan |
True |
main(缺 default_contract) |
不进入下载 | 下载并激活 | 下载前抛 ValueError,不触达安装器 |
旧版 stable 发行版(如 2.3.0) |
True |
stable(缺 default_contract) |
同样无 default_contract |
允许安装 | 允许安装(保持旧版可用) |
旧版 stable 描述符伪装新归档 |
True |
stable(缺 default_contract) |
含 complete_turn |
忽略归档内契约差异并激活 | 解压校验拦截:default contract disagrees |
不支持或缺失 channel 的激活请求 |
True |
channel 非 main/stable |
不进入下载 | 未拦截未知 channel | 下载前拒绝:no supported installation channel |
所有持久化或远端元数据均未新增字段、开关或状态机枚举;for_activation 仅是激活路径传入 validate_manifest 与 resolve_artifact 的调用期布尔参数,可逆性与隔离边界清晰。
具体改动 / Changes
对照已接受规范文档 docs/product/release-readiness.md(评审基准提交 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 第 49–63 行与第 284–308 行),各验收条目的映射如下(本次 PR 同时在 docs/product/release-readiness.md 第 64–75 行以中英双语补充了 main 预览快照需携带受支持 default_contract 的说明,与原第 284–308 行契约一致):
- RR-1(更新入口在下载或激活前拒绝未获资格的默认契约声明):
implemented——loopx/cli_commands/update_artifact.py的validate_manifest(..., for_activation=True)、resolve_artifact(..., for_activation=True)、install_artifact、main()与loopx/cli_commands/update_source.py的prepare_target共同覆盖 CLI、独立引导与直调执行边界,并在下载前中止。 - RR-2(校验归档内
runtime-artifact.json的default_contract与发行元数据一致):implemented——install_artifact将比对条件从仅在manifest含该键时检查收紧为identity.get("default_contract") != manifest.get("default_contract"),防止无标记stable描述符夹带含complete_turn的归档。 - RR-3(保留历史 v1 描述符只读兼容性,以及元数据匹配的旧版
stable安装路径):implemented——validate_manifest与resolve_artifact默认for_activation=False,且for_activation=True仅对channel == "main"强制要求default_contract,stable无该字段且与归档一致时仍可安装。 - RR-4(保留既有
--rollback回退、--source源码构建及python_distribution/source_checkout既有所有者路径):implemented——build_rollback_plan、execute_rollback_plan、distribution == "source"与非loopx_release_snapshot所有者分支均未受影响。
关键代码讲解
loopx/cli_commands/update_artifact.py:117—validate_manifest(value, *, revision=None, for_activation=False)- 新增
for_activation关键字参数:当for_activation=True时,先校验channel in ("main", "stable"),并在"default_contract" in value or (for_activation and channel == "main")时调用validate_default_contract(value.get("default_contract"))。历史只读调用保持for_activation=False,因此无该字段的旧预览元数据仍可被反序列化或审计,而一旦进入安装激活流程就必须持有合法的PUBLIC_DEFAULT_CONTRACT。
- 新增
loopx/cli_commands/update_artifact.py:147—resolve_artifact(repo, ref, *, for_activation=False)- 将
for_activation透传给validate_manifest;保留既有 URL 路由(stable、main、40 位 SHA 的runtime-main-{ref}及其仅在 404 时回退旧runtime-main、版本 tagv*)及ref in {"main", "stable"}的 channel 一致性校验。
- 将
loopx/cli_commands/update_artifact.py:415—install_artifact(manifest, *, env, timeout_seconds, progress=...)- 在
download_artifact之前调用validate_manifest(manifest, for_activation=True),阻断任何跳过resolve_artifact(例如复用缓存或预先构造的 update plan)的直接安装调用;并在解压runtime-artifact.json后把比对收紧为identity.get("default_contract") != manifest.get("default_contract"),从而同步拦截“旧stable描述符指向带complete_turn归档”的错配情形。
- 在
loopx/cli_commands/update_artifact.py:439—main()- 公开引导脚本入口(由
standalone_source()导出至 Pagesupdate-artifact.py)在检查本地loopx所有权之后、调用target_direction与install_artifact之前,显式以for_activation=True调用resolve_artifact,确保 curl 引导在无已安装loopx包的纯标准库环境下同样提前拒绝未达标预览。
- 公开引导脚本入口(由
loopx/cli_commands/update_source.py:16—prepare_target(payload, *, freshness, resolve_remote, allow_downgrade)- 当
install_lifecycle.owner == "loopx_release_snapshot"且source.distribution == "runtime"时,第 26 行以for_activation=True调用resolve_artifact。捕获到的ValueError会写入reason并触发第 63–70 行的统一阻塞投影:source.target_status = "blocked"、plan.apply_supported = false、plan.mutates_release_install = false、next_action.kind = "review_update_target",且即使传入--allow-downgrade也不会绕过。
- 当
测试同步更新情况:tests/test_update_artifact.py(+22/-5)新增缺标记 main 预览仍可读但在 install_artifact 下载前中止的测试,以及 stable 与 main 双通道的 runtime-artifact.json 契约不一致拦截测试,并校验 main() 传入 for_activation=True;tests/test_update_operation.py(+25/-2)新增参数化测试验证 ref="main" 与 ref="2"*40 在 allow_downgrade=True 下依然在 build_update_plan 阶段被阻塞。
对主干的风险 / Risks
综合失败路径推演、非适用边界检查与实测验证,本次改动对 main 回归风险可控,无 P0/P1 阻断项:
- 非激活路径与兼容性:未触及
python_package_manager(pip/pipx)、source_checkout、--source源码构建以及loopx update --rollback。validate_manifest默认保持for_activation=False,且我们在tests/architecture/test_content_digest_single_owner.py验证了standalone_source()与单点摘要绑定未被破坏(244/244 通过)。 - 已执行的实测验证:
- 变更聚焦测试与更新激活测试:
pytest -q -rs tests/test_update_artifact.py tests/test_update_operation.py68 passed(0 skipped);tests/test_self_upgrade.py、tests/test_self_update_runtime_activation.py、tests/test_runtime_snapshot_publication.py、tests/test_archive_installer_commit_response.py156 passed, 5 skipped(2 项需显式LOOPX_TEST_NATIVE_APP_RESTART=1的 macOS AppKit 测试、3 项仅限 Windows 原生环境的测试,均属预期环境跳过)。 - 静态与边界检查:
ruff check(4 个变更 Python 文件)PASS;仓级mypy(17 个配置受控文件)PASS;mypy --follow-imports=silent检查两份变更源码仅见既有未标注预存行报错,本 PR 变更行 0 新增报错;loopx check --scan-path ...5 文件公开/隐私边界扫描 PASS(0 errors, 0 warnings);scripts/check_rfc_bilingual.py与git diff --checkPASS。 - 双版本反事实与隔离
python -I引导对照:已实测基线4a0188c1ca会接受无default_contract的main/<SHA>预览并放行带complete_turn的stable归档,而精确提交6a9894c690全部在下载或安装器调用前拦截;同时实测standalone_source()导出脚本在python -I(无loopx包)下会拒绝无标记main与<SHA>(downloads=[],installs=0, rc=1)并成功安装匹配的旧版stable包(installs=1, rc=0)。 loopx canary premerge --from-git-diff --git-diff-base origin/main:在独立 worktree 安装npm ci --ignore-scripts依赖后,direct checks 4/4 PASS、python_compile PASS、risk_profile_smokes 8/8 PASS、public_boundary PASS、catalog_canaries 9/10 PASS(含install-local-smoke、loopx-update-smoke、semantic-vocabulary-drift-smoke、cli-output-budget-regression-smoke);唯一失败的control-plane-maintainability-ratchet-smoke.py --format=json为advisory_failure,已在不可变基线4a0188c1ca复现完全一致的预存报错签名(oversized_decision_function:loopx.control_plane.work_items.interaction_contract:_admitted_interaction_next_cli_actions,statements=96 > 90,本 PR 未修改该文件)。
- 变更聚焦测试与更新激活测试:
- 非阻断性观察与遗留项:
resolve_artifact在ref为 40 位提交 SHA 时仅从runtime-main-{ref}或runtime-main拉取元数据,但第 171 行仅校验了ref in {"main", "stable"}的channel == ref,未对固定 SHA 显式断言channel == "main";尽管现有runtime-snapshots.yml发布器固定写入channel="main"且install_artifact仍会核对归档内default_contract,后续可考虑在SHA.fullmatch(ref)分支补强channel == "main"检查。tests/test_update_artifact.py的test_exported_bootstrap_validates_metadata_without_an_installed_package暂未直接覆盖导出脚本中的for_activation=True与匹配的旧版stable正向安装用例(本次审查已通过独立python -I探针补足验证);此外 PR #9036 同样在docs/product/release-readiness.md第 64 行附近相邻位置增补 pip/pipx 说明,合入顺序先后时需留意常规文本上下文合并。
我的整体评价 / Verdict
- 长程与用户体验影响:
long_horizon为improved,防止无标记历史预览包在维护者或自动化执行update apply --ref main时将运行环境悄悄切换到未达标的complete_turnwriter;user_experience为improved,update check/plan/apply与独立引导在下载前即给出明确的资格阻塞提示且保留旧版stable与回退可用。视觉评审结论:本次改动仅涉及 CLI 更新计划(update_artifact.py / update_source.py)、独立引导脚本导出边界与 release-readiness.md 文档说明,不修改任何渲染 UI、前端页面或桌面视图(已检查 diff 的 5 个变更文件)。,未验证范围(unverified_scope):none。 - 代码体量、兼容性与架构评价:生产改动仅 +18/-11 行,测试 +47/-7 行,文档 +12 行,属于最小且高度内聚的修复(
code_volume=necessary、change_proportionality=proportionate、compatibility_assessment=retain、architecture_assessment=retain)。机制均落在既有的update_artifact.py与update_source.py所有者内,未引入新词汇或平行状态(semantic_alignment=aligned,candidate_decision=reuse_existing,复用PUBLIC_DEFAULT_CONTRACT与loopx_runtime_artifact_v1)。 - 残留风险与待完成验证:Pages 工作流重新导出
update-artifact.py后的线上部署与 Linux/Windows 平台实机执行仍需依赖现有 CI/发布通道完成;精确提交6a9894c6909da64c97f4da39ad15ee343b344514仍处于最新状态且可安全批准合入(本审查按指令保持 PR 开启,不执行合并)。
English Verdict: APPROVE — exact head 6a9894c closes the prebuilt main-preview adoption gap before archive download while preserving historical reads, legacy stable installs, and rollback paths; no blocking findings remain (targeted update/activation pytest, architecture checks, ruff, mypy, public boundary check, and counterfactual probes pass; pre-existing maintainability ratchet failure verified unchanged on base).
Problem
The published
runtime-maindescriptor for65ae1d6ec05d0594947a7a47e1e2fc7d7b304e86lacks adefault_contract. The hosted bootstrap installed its verified archive into an isolated environment. The installed quota CLI then reported thecomplete_turnwriter. Producer validation in #9018 covers new snapshots. The current installer also needs to handle already published preview descriptors. Published preview channelChange
The existing manifest validator requires a supported default contract when the CLI or website bootstrap selects a preview for installation. The installer repeats the same check for a previously resolved descriptor and compares the archived contract with the descriptor. Historical metadata stays readable. An archived stable release with matching legacy metadata remains installable, and installed releases retain their existing rollback path.
Validation
6a9894c6909da64c97f4da39ad15ee343b344514rejected the actual moving preview and its pinned revision before archive download. The preview attempts preserved the installed CLI and made no additions to the download cache.quota_packetwriter and installation Doctor passed after both preview rejections.update planandupdate apply. The apply attempt with explicit downgrade intent left the installed release in place.