diff --git a/docs/product/release-readiness.md b/docs/product/release-readiness.md index cc11f1419a..f4df1be532 100644 --- a/docs/product/release-readiness.md +++ b/docs/product/release-readiness.md @@ -61,6 +61,18 @@ backup if older code cannot read the current data. Use `loopx update plan qualification. Re-running the curl installer remains a repair path when an archive wrapper is too broken to run its own updater. +Installing or updating to a `main` runtime snapshot requires a supported +`default_contract` in its descriptor, including when a preview revision is pinned. +If that evidence is missing, the update plan reports a blocked target and the +public installer stops before downloading the archive. Historical descriptors +remain readable. Legacy `stable` releases remain installable with matching +archive metadata, and rollback continues to use the existing local release. + +安装或更新到 `main` 运行时快照时,描述符必须包含受支持的 `default_contract`, +指定预览提交时也适用。缺少此证据时,更新计划会标明目标受阻,公开安装器会在下载 +归档前停止。历史描述符仍可读取,归档元数据一致的旧版 `stable` 仍可安装,回退仍 +使用已有本地发行版。 + For contributors, keep the clone-plus-canary path: ```bash diff --git a/loopx/cli_commands/update_artifact.py b/loopx/cli_commands/update_artifact.py index d4546b50f9..44ed64b507 100644 --- a/loopx/cli_commands/update_artifact.py +++ b/loopx/cli_commands/update_artifact.py @@ -114,7 +114,9 @@ def validate_default_contract(value: object) -> dict[str, Any]: return dict(value) -def validate_manifest(value: dict[str, Any], *, revision: str | None = None) -> dict[str, Any]: +def validate_manifest( + value: dict[str, Any], *, revision: str | None = None, for_activation: bool = False, +) -> dict[str, Any]: if value.get("schema_version") != RUNTIME_ARTIFACT_SCHEMA_VERSION: raise ValueError("Unsupported runtime artifact metadata") if not SHA.fullmatch(str(value.get("source_revision", ""))): @@ -132,14 +134,17 @@ def validate_manifest(value: dict[str, Any], *, revision: str | None = None) -> raise ValueError("Runtime artifact has no bounded download sources") for url in urls: safe_url(url) - # Historical v1 snapshots remain readable. Newly produced artifacts and - # the publisher require the observed contract; absence is not qualification. - if "default_contract" in value: - validate_default_contract(value["default_contract"]) + channel = value.get("channel") + if for_activation and channel not in ("main", "stable"): + raise ValueError("Runtime artifact has no supported installation channel") + # Published legacy stable releases remain installable. Historical preview + # metadata can still be read, but installing it requires a qualified default. + if "default_contract" in value or (for_activation and channel == "main"): + validate_default_contract(value.get("default_contract")) return dict(value) -def resolve_artifact(repo: str, ref: str) -> dict[str, Any]: +def resolve_artifact(repo: str, ref: str, *, for_activation: bool = False) -> dict[str, Any]: if not REPOSITORY_PATTERN.fullmatch(repo): raise ValueError("Update repo must use GitHub owner/name syntax") if ref == "stable": @@ -160,7 +165,9 @@ def resolve_artifact(repo: str, ref: str) -> dict[str, Any]: if not (SHA.fullmatch(ref) and isinstance(exc.__cause__, HTTPError) and exc.__cause__.code == 404): raise metadata = read_json(f"https://github.com/{repo}/releases/download/runtime-main/loopx-runtime-{ref}.json") - artifact = validate_manifest(metadata, revision=ref if SHA.fullmatch(ref) else None) + artifact = validate_manifest( + metadata, revision=ref if SHA.fullmatch(ref) else None, for_activation=for_activation, + ) if ref in {"main", "stable"} and artifact.get("channel") != ref: raise ValueError("Runtime artifact belongs to another channel") return artifact @@ -407,7 +414,7 @@ def consume(name, stream): def install_artifact(manifest: dict[str, Any], *, env: dict[str, str], timeout_seconds: int, progress=lambda _event: None): - manifest = validate_manifest(manifest) + manifest = validate_manifest(manifest, for_activation=True) started = time.monotonic() archive = download_artifact(manifest, progress=progress, timeout=timeout_seconds) progress({"stage": "verify"}) @@ -416,7 +423,7 @@ def install_artifact(manifest: dict[str, Any], *, env: dict[str, str], timeout_s identity = json.loads((root / "runtime-artifact.json").read_text(encoding="utf-8")) if identity.get("source_revision") != manifest["source_revision"] or identity.get("package_version") != manifest["package_version"]: raise ValueError("Runtime identity disagrees with its release metadata") - if "default_contract" in manifest and identity.get("default_contract") != manifest["default_contract"]: + if identity.get("default_contract") != manifest.get("default_contract"): raise ValueError("Runtime default contract disagrees with its release metadata") selected = dict(env) selected.update({"LOOPX_RESOLVED_SOURCE_GIT_COMMIT": manifest["source_revision"], @@ -449,7 +456,7 @@ def report(event): raise ValueError("An existing CLI has another or unknown owner; use its `loopx upgrade` or original package manager") selected_repo = args.repo or (os.environ.get("LOOPX_REPO") if os.environ.get("LOOPX_UPDATE_REPO_EXPLICIT") == "1" else None) or installed.get("repo") or "loopx-project/loopx" selected_ref = args.ref or (os.environ.get("LOOPX_REF") if os.environ.get("LOOPX_UPDATE_REF_EXPLICIT") == "1" else None) or installed.get("ref") or "stable" - manifest = resolve_artifact(selected_repo, selected_ref) + manifest = resolve_artifact(selected_repo, selected_ref, for_activation=True) if installed and target_direction(selected_repo, installed.get("git_commit"), manifest["source_revision"]) not in {"ahead", "identical"} and os.environ.get("LOOPX_ALLOW_DOWNGRADE") != "1": raise ValueError("Older, diverged or unverified target; inspect it before explicitly setting LOOPX_ALLOW_DOWNGRADE=1") env = dict(os.environ, LOOPX_REPO=selected_repo, LOOPX_REF=selected_ref, LOOPX_UPDATE_CHANNEL=selected_ref, LOOPX_UPDATE_EVENTS="1") diff --git a/loopx/cli_commands/update_source.py b/loopx/cli_commands/update_source.py index 4112c81bb7..d22d398734 100644 --- a/loopx/cli_commands/update_source.py +++ b/loopx/cli_commands/update_source.py @@ -23,7 +23,7 @@ def prepare_target(payload: dict[str, Any], *, freshness: dict, resolve_remote: if source["distribution"] == "runtime": if resolve_remote: try: - artifact = resolve_artifact(source["repo"], source["ref"]) + artifact = resolve_artifact(source["repo"], source["ref"], for_activation=True) source["artifact"] = artifact target = artifact["source_revision"] version = artifact["package_version"] diff --git a/tests/test_update_artifact.py b/tests/test_update_artifact.py index 936072fdd6..379f171416 100644 --- a/tests/test_update_artifact.py +++ b/tests/test_update_artifact.py @@ -117,7 +117,20 @@ def test_qualified_scope_and_historical_metadata_remain_readable(): assert update.validate_manifest(current) == current -def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch): +def test_markerless_preview_remains_readable_but_stops_before_download(monkeypatch): + descriptor = manifest(b"runtime", "https://publisher.invalid/runtime") + assert update.validate_manifest(descriptor) == descriptor + + def unexpected_download(*_args, **_kwargs): + pytest.fail("Unqualified runtime reached archive download") + + monkeypatch.setattr(update, "download_artifact", unexpected_download) + with pytest.raises(ValueError, match="unqualified for public adoption"): + update.install_artifact(descriptor, env={}, timeout_seconds=10) + + +@pytest.mark.parametrize("channel", ["main", "stable"]) +def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch, channel): archive = tmp_path / "runtime.tar.gz" identity = json.dumps({"source_revision": "a" * 40, "package_version": "1.2.3", "default_contract": {"surface": "complete_turn"}}).encode() @@ -126,8 +139,9 @@ def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch) member = tarfile.TarInfo(name) member.size = len(content) target.addfile(member, io.BytesIO(content)) - descriptor = {**manifest(archive.read_bytes(), "https://publisher.invalid/runtime"), - "default_contract": dict(update.PUBLIC_DEFAULT_CONTRACT)} + descriptor = {**manifest(archive.read_bytes(), "https://publisher.invalid/runtime"), "channel": channel} + if channel == "main": + descriptor["default_contract"] = dict(update.PUBLIC_DEFAULT_CONTRACT) monkeypatch.setattr(update, "download_artifact", lambda *_a, **_kw: archive) calls = [] monkeypatch.setattr(update, "run_installer", lambda *_a, **_kw: calls.append("activate")) @@ -373,10 +387,13 @@ def test_bootstrap_inherits_snapshot_choice_without_taking_over_a_package_owner( monkeypatch.setenv("LOOPX_UPDATE_REPO_EXPLICIT", "0") monkeypatch.setattr(sys, "argv", ["update-artifact.py"]) selected = [] - monkeypatch.setattr(update, "resolve_artifact", lambda repo, ref: selected.append((repo, ref)) or manifest(b"x", "https://example.com/runtime")) + def resolve(repo, ref, *, for_activation=False): + selected.append((repo, ref, for_activation)) + return manifest(b"x", "https://example.com/runtime") + monkeypatch.setattr(update, "resolve_artifact", resolve) monkeypatch.setattr(update, "install_artifact", lambda *_a, **_kw: (subprocess.CompletedProcess([], 0, "", ""), {})) assert update.main() == 0 - assert selected == [("example/fork", "main")] + assert selected == [("example/fork", "main", True)] entry.unlink() entry.touch() # pip/another installer owns a regular console entry. assert update.main() == 1 diff --git a/tests/test_update_operation.py b/tests/test_update_operation.py index 316e6ee5da..214f2b669a 100644 --- a/tests/test_update_operation.py +++ b/tests/test_update_operation.py @@ -34,7 +34,7 @@ def test_runtime_check_uses_one_qualified_version_and_revision(monkeypatch): def no_branch_probe(*_args): raise AssertionError("The mutable branch version must not describe a qualified artifact") monkeypatch.setattr("loopx.self_update._source_version_check", no_branch_probe) - monkeypatch.setattr(update_source, "resolve_artifact", lambda *_: { + monkeypatch.setattr(update_source, "resolve_artifact", lambda *_, **kwargs: { "source_revision": "2" * 40, "package_version": "1.2.3"}) monkeypatch.setattr(update_source, "target_direction", lambda *_: "ahead") plan = build_update_plan(action="check", doctor_payload=doctor_payload(), resolve_remote=True) @@ -46,7 +46,7 @@ def no_branch_probe(*_args): def test_target_is_resolved_before_any_mutation_and_downgrade_needs_intent(monkeypatch, direction, accepted): from loopx.cli_commands import update_source artifact = {"source_revision": "2" * 40, "package_version": "1.0.0"} - monkeypatch.setattr(update_source, "resolve_artifact", lambda *_: artifact) + monkeypatch.setattr(update_source, "resolve_artifact", lambda *_, **kwargs: artifact) monkeypatch.setattr(update_source, "target_direction", lambda *_: direction) plan = build_update_plan(action="apply", doctor_payload=doctor_payload(), resolve_remote=True) assert plan["source"]["resolved_revision"] == artifact["source_revision"] @@ -55,6 +55,29 @@ def test_target_is_resolved_before_any_mutation_and_downgrade_needs_intent(monke assert override["plan"]["apply_supported"] is True +@pytest.mark.parametrize("ref", ["main", "2" * 40]) +def test_update_plan_blocks_unqualified_preview_even_if_downgrade_is_allowed(monkeypatch, ref): + from loopx.cli_commands import update_artifact, update_source + + descriptor = { + "schema_version": update_artifact.RUNTIME_ARTIFACT_SCHEMA_VERSION, + "source_revision": "2" * 40, + "package_version": "1.2.3", + "channel": "main", + "size": 7, + "sha256": "a" * 64, + "urls": ["https://publisher.invalid/runtime.tar.gz"], + } + monkeypatch.setattr(update_artifact, "read_json", lambda _url: descriptor) + monkeypatch.setattr(update_source, "target_direction", lambda *_: "ahead") + plan = build_update_plan(ref=ref, action="apply", doctor_payload=doctor_payload(), + resolve_remote=True, allow_downgrade=True) + assert plan["source"]["target_status"] == "blocked" + assert plan["plan"]["apply_supported"] is False + assert not plan["plan"]["mutates_release_install"] + assert "unqualified for public adoption" in plan["plan"]["blocked_reason"] + + def test_installer_uses_frozen_revision_but_persists_channel_and_proxy(monkeypatch): monkeypatch.setenv("HTTPS_PROXY", "http://operator-proxy.invalid:8080") source = _source_config(repo=None, ref="main", archive_url=None, build_from_source=True)