starforge-core 0.3.2__tar.gz → 0.3.4__tar.gz

{starforge_core-0.3.2 → starforge_core-0.3.4}/.gitignore

@@ -14,6 +14,8 @@ venv/
 # 前端
 web/node_modules/
 web/dist/
+mintlify/scripts/node_modules/
+mintlify/scripts/console-shots.local.json
 
 # 本地数据库 / 凭据 / 台账
 .forge/

starforge_core-0.3.4/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: starforge-core
+Version: 0.3.4
+Summary: StarForge client: JobSpec / recipe contract, job-side runner, and sf CLI.
+Project-URL: Homepage, https://github.com/wccdev/starforge
+Project-URL: Documentation, https://github.com/wccdev/starforge
+Project-URL: Repository, https://github.com/wccdev/starforge
+Keywords: grpo,llm,post-training,rlhf,sft,starforge
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: packaging>=24
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Provides-Extra: data
+Requires-Dist: datasets>=2.18; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# starforge-core
+
+Client for StarForge. You get the `sf` command and a Python package named `starforge`.
+
+Use this to scaffold a lab, lock a post-training method, and submit jobs to a StarForge console. The control plane is a separate install, `starforge-server`. Training images do not need this whole package; the server injects a runner that carries the kernel only.
+
+## Install
+
+```bash
+pip install starforge-core
+# or
+uv tool install starforge-core
+
+sf --help
+```
+
+Python 3.10 or newer. Import name is `starforge`, not `starforge_core`.
+
+`pip install starforge-core[data]` adds HuggingFace `datasets` for local prepare scripts.
+
+## Start a lab
+
+Do not clone the platform repo. This package writes a project for you:
+
+```bash
+sf init my-lab --yes
+cd my-lab
+sf login --server https://<your-console>
+sf new my-grpo --method nemo-rl/grpo
+sf validate my-grpo
+sf submit my-grpo --profile h200:8
+sf job logs
+```
+
+`sf methods` lists the catalog on the server you logged into. Methods look like `nemo-rl/grpo`, `verl/sft`, `trl/kto`, `openrlhf/ppo`, `evalkit/benchmark`, `custom/custom`.
+
+Examples live in `starforge-tutorial`. Day-to-day work should be your own `sf init` tree.
+
+## Python
+
+Catalog methods already forward framework logs. Custom `train.sh` jobs that want console curves call:
+
+```python
+from starforge.report import init, log, finish
+
+init()
+log({"loss": 0.12}, step=1)
+finish()
+```
+
+`starforge.spec_to_env` is the JobSpec to environment mapping used on both the client and the job. `starforge.get_recipe` / `starforge.recipe_names` read the bundled catalog.
+
+## What this package contains
+
+- `sf` CLI: init, login, experiments, submit, sweep, jobs, datasets, plugins, bench, serve
+- JobSpec types and `spec_to_env`
+- Recipe catalog and framework adapters (NeMo-RL, verl, TRL, OpenRLHF, evalkit, custom)
+- Job-side reporter (`starforge.report`)
+
+Cluster credentials stay on the server. Your laptop keeps an access token under `~/.forge/`.
+
+## Docs and source
+
+- Platform repo: https://github.com/wccdev/starforge
+- User docs: `mintlify/` in that repo (English and 简体中文)

starforge_core-0.3.4/README.md

@@ -0,0 +1,65 @@
+# starforge-core
+
+Client for StarForge. You get the `sf` command and a Python package named `starforge`.
+
+Use this to scaffold a lab, lock a post-training method, and submit jobs to a StarForge console. The control plane is a separate install, `starforge-server`. Training images do not need this whole package; the server injects a runner that carries the kernel only.
+
+## Install
+
+```bash
+pip install starforge-core
+# or
+uv tool install starforge-core
+
+sf --help
+```
+
+Python 3.10 or newer. Import name is `starforge`, not `starforge_core`.
+
+`pip install starforge-core[data]` adds HuggingFace `datasets` for local prepare scripts.
+
+## Start a lab
+
+Do not clone the platform repo. This package writes a project for you:
+
+```bash
+sf init my-lab --yes
+cd my-lab
+sf login --server https://<your-console>
+sf new my-grpo --method nemo-rl/grpo
+sf validate my-grpo
+sf submit my-grpo --profile h200:8
+sf job logs
+```
+
+`sf methods` lists the catalog on the server you logged into. Methods look like `nemo-rl/grpo`, `verl/sft`, `trl/kto`, `openrlhf/ppo`, `evalkit/benchmark`, `custom/custom`.
+
+Examples live in `starforge-tutorial`. Day-to-day work should be your own `sf init` tree.
+
+## Python
+
+Catalog methods already forward framework logs. Custom `train.sh` jobs that want console curves call:
+
+```python
+from starforge.report import init, log, finish
+
+init()
+log({"loss": 0.12}, step=1)
+finish()
+```
+
+`starforge.spec_to_env` is the JobSpec to environment mapping used on both the client and the job. `starforge.get_recipe` / `starforge.recipe_names` read the bundled catalog.
+
+## What this package contains
+
+- `sf` CLI: init, login, experiments, submit, sweep, jobs, datasets, plugins, bench, serve
+- JobSpec types and `spec_to_env`
+- Recipe catalog and framework adapters (NeMo-RL, verl, TRL, OpenRLHF, evalkit, custom)
+- Job-side reporter (`starforge.report`)
+
+Cluster credentials stay on the server. Your laptop keeps an access token under `~/.forge/`.
+
+## Docs and source
+
+- Platform repo: https://github.com/wccdev/starforge
+- User docs: `mintlify/` in that repo (English and 简体中文)

{starforge_core-0.3.2 → starforge_core-0.3.4}/pyproject.toml

@@ -1,8 +1,9 @@
 # Researcher client: contract kernel + sf CLI. Control plane is starforge-server.
 [project]
 name = "starforge-core"
-version = "0.3.2"
+version = "0.3.4"
 description = "StarForge client: JobSpec / recipe contract, job-side runner, and sf CLI."
+readme = "README.md"
 requires-python = ">=3.10"
 keywords = ["llm", "post-training", "rlhf", "grpo", "sft", "starforge"]
 classifiers = [

{starforge_core-0.3.2 → starforge_core-0.3.4}/starforge/__init__.py

@@ -5,7 +5,7 @@
 """
 from __future__ import annotations
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 from .contract import (
     API_VERSION,

{starforge_core-0.3.2 → starforge_core-0.3.4}/starforge/cli/commands/exp.py

@@ -114,11 +114,10 @@ def _validate_exp_contents(exp_dir, recipe, *, repo_root=None) -> tuple[list[str
 
 def _validate_exp(exp_path: str, recipe_override: str = "") -> tuple[list[str], list[str]]:
     """锁必须是当前 bundle，再跑 recipe 所属框架的 validator。"""
-    from starforge.contract import SpecError
-    from starforge.recipes import get_recipe
-
     from starforge.cli.recipe_lock import validate_recipe_lock
     from starforge.cli.spec_builder import infer_recipe
+    from starforge.contract import SpecError
+    from starforge.recipes import get_recipe
 
     exp_dir = common.ROOT / exp_path
     recipe_name = recipe_override.strip() or infer_recipe(exp_dir)

{starforge_core-0.3.2 → starforge_core-0.3.4}/starforge/cli/commands/submit.py

@@ -174,9 +174,8 @@ def _materialize_profile_or_exit(exprs: list[str]) -> tuple[str, list[str], list
     series 与默认形状查服务端注册表——用户只说「哪种卡、几张」，
     拓扑细节由注册表补齐，两边不可能写出互相矛盾的资源声明。
     """
-    from starforge.contract import SpecError
-
     from starforge.cli import spec_builder
+    from starforge.contract import SpecError
 
     try:
         return spec_builder.materialize_pools(exprs, common.profile_registry())
@@ -229,9 +228,8 @@ def _build_spec_or_exit(exp_path: str, *, method, project, sets, pools, roles,
                         framework_version=None, image=None, provenance=None,
                         validate: bool):
     """构建强 JobSpec；缺少显式 recipe 时立即退出。"""
-    from starforge.contract import SpecError
-
     from starforge.cli import spec_builder
+    from starforge.contract import SpecError
 
     recipe = (method or "").strip() or spec_builder.infer_recipe(common.ROOT / exp_path)
     if not recipe:
@@ -342,11 +340,10 @@ def _echo_upload_summary(res: dict) -> None:
 def _submit_post(action: str, exp_path: str, profile: Optional[str], flags: list[str],
                  dry_run: bool, allow_dirty: bool) -> int:
     """构建并预编译训练后强契约，再通过统一 launcher 提交。"""
-    from starforge.frameworks import CompileRequest, compile_launch_plan
-    from starforge.recipes import get_recipe
-
     from starforge.cli import spec_builder
     from starforge.cli.recipe_lock import validate_recipe_lock
+    from starforge.frameworks import CompileRequest, compile_launch_plan
+    from starforge.recipes import get_recipe
 
     recipe_name = spec_builder.infer_recipe(common.ROOT / exp_path)
     if not recipe_name:

{starforge_core-0.3.2 → starforge_core-0.3.4}/starforge/recipes/model.py

@@ -542,6 +542,77 @@ class Entrypoint:
         return cls(kind=kind, value=value, experiment_override=override)
 
 
+#: 指标方向：higher = 越高越好，lower = 越低越好，neutral = 两头都不好 / 无优劣。
+METRIC_DIRECTIONS = ("higher", "lower", "neutral")
+#: 展示形态：ratio = 0–1 的占比（展示为百分比，差值展示为百分点），number = 裸数值。
+METRIC_DISPLAYS = ("ratio", "number")
+
+
+@dataclass(frozen=True)
+class MetricSemantics:
+    """一个 canonical 指标「怎么读」：方向与展示形态。
+
+    这两件事此前只存在于 console 的键名正则里，而且是三份互不相同的正则 ——
+    `train/clip_frac` 在图表页按百分比画、在对比页按裸小数显示，同一个数字两种读法。
+    根因是契约声明了指标的**名字**却没声明它的**含义**，前端只能按名字猜。
+    """
+
+    direction: str = "higher"
+    display: str = "number"
+
+    def to_dict(self) -> dict[str, str]:
+        return {"direction": self.direction, "display": self.display}
+
+
+#: canonical 词表的内置语义。与 MetricContract docstring 里的词表逐条对应 ——
+#: 新增 canonical 名时在这里补一行，recipe 无须逐个声明。
+#:
+#: 策略熵是 neutral 而不是 lower：RL 里熵归零就是策略塌缩、停止探索，判成 lower
+#: 会让对比页把塌缩掉的那次训练标成最优；判成 higher 又会奖励纯随机策略。两头
+#: 都不好的量就该说自己两头都不好，而不是被塞进一个二选一里。
+CANONICAL_METRIC_SEMANTICS: dict[str, MetricSemantics] = {
+    "train/reward": MetricSemantics("higher", "number"),
+    "train/score": MetricSemantics("higher", "number"),
+    "train/loss": MetricSemantics("lower", "number"),
+    "train/kl_penalty": MetricSemantics("lower", "number"),
+    "train/entropy": MetricSemantics("neutral", "number"),
+    "train/grad_norm": MetricSemantics("lower", "number"),
+    "train/lr": MetricSemantics("neutral", "number"),
+    "train/response_length": MetricSemantics("neutral", "number"),
+    "train/clip_frac": MetricSemantics("lower", "ratio"),
+    "train/truncated_ratio": MetricSemantics("lower", "ratio"),
+    "train/reward_zero_std_frac": MetricSemantics("lower", "ratio"),
+    "train/value_loss": MetricSemantics("lower", "number"),
+    "train/value_explained_var": MetricSemantics("higher", "number"),
+    "train/accuracy": MetricSemantics("higher", "ratio"),
+    "train/token_accuracy": MetricSemantics("higher", "ratio"),
+    "train/margin": MetricSemantics("higher", "number"),
+    # 偏好对两侧的隐式奖励：绝对值无意义（看的是间隔 train/margin），
+    # 单独判优劣会把「两边一起涨」误读成进步。
+    "train/reward_chosen": MetricSemantics("neutral", "number"),
+    "train/reward_rejected": MetricSemantics("neutral", "number"),
+    "validation/accuracy": MetricSemantics("higher", "ratio"),
+    "validation/token_accuracy": MetricSemantics("higher", "ratio"),
+    "validation/loss": MetricSemantics("lower", "number"),
+    "validation/reward": MetricSemantics("higher", "number"),
+    "validation/margin": MetricSemantics("higher", "number"),
+    "validation/kl_penalty": MetricSemantics("lower", "number"),
+    "train/return": MetricSemantics("higher", "number"),
+    "train/token_mult_prob_error": MetricSemantics("lower", "number"),
+    # 优势/价值/长度这类量没有「越大越好」：优势均值应当在 0 附近（GAE 已中心化），
+    # critic 的 value 是对回报的估计而非目标，生成长度长短各有代价。
+    "train/advantages/mean": MetricSemantics("neutral", "number"),
+    "train/value": MetricSemantics("neutral", "number"),
+    "train/opsd_hint_len_mean": MetricSemantics("neutral", "number"),
+    "train/opsd_response_len_mean": MetricSemantics("neutral", "number"),
+    "train/opsd_kl_clip_frac": MetricSemantics("lower", "ratio"),
+    # 组内奖励标准差：归零是 GRPO 的失效信号（组内全同分，梯度为零），
+    # 过大则说明采样噪声压过了信号。同 entropy，两头都不好。
+    "train/reward_std": MetricSemantics("neutral", "number"),
+    "bench/score": MetricSemantics("higher", "number"),
+}
+
+
 @dataclass(frozen=True)
 class MetricContract:
     """指标契约：把各框架的原生键名收敛到一套跨框架可比的 canonical 名字。
@@ -585,6 +656,23 @@ class MetricContract:
 
     primary: tuple[str, ...]
     aliases: dict[str, tuple[str, ...]]
+    #: 对 CANONICAL_METRIC_SEMANTICS 的按 recipe 覆写。绝大多数 recipe 用不上 ——
+    #: canonical 名字一样，含义就一样，那正是收敛到 canonical 词表的意义。
+    semantics: dict[str, MetricSemantics] = field(default_factory=dict)
+
+    def semantics_for(self, key: str) -> MetricSemantics:
+        """该指标怎么读。未知键（含 `raw/` 前缀的未声明键）落到默认值。"""
+        if (own := self.semantics.get(key)) is not None:
+            return own
+        return CANONICAL_METRIC_SEMANTICS.get(key, MetricSemantics())
+
+    def semantics_map(self) -> dict[str, dict[str, str]]:
+        """本契约全部 canonical 名的语义表 —— 服务端据此下发给 console。
+
+        canonical 名 = primary ∪ aliases 的键，与 starforge.metrics 的归一化口径同源。
+        """
+        names = list(self.primary) + [k for k in self.aliases if k not in self.primary]
+        return {name: self.semantics_for(name).to_dict() for name in names}
 
     @classmethod
     def from_dict(cls, data: Mapping[str, Any] | None, *, recipe: str) -> MetricContract:
@@ -601,7 +689,26 @@ class MetricContract:
             if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
                 raise SpecError("应为字符串数组", field=f"metrics.aliases.{canonical}")
             aliases[str(canonical)] = tuple(str(v) for v in values)
-        return cls(primary=tuple(str(v) for v in primary_raw), aliases=aliases)
+        semantics: dict[str, MetricSemantics] = {}
+        for canonical, raw in (data.get("semantics") or {}).items():
+            if not isinstance(raw, Mapping):
+                raise SpecError("应为对象（direction / display）", field=f"metrics.semantics.{canonical}")
+            direction = str(raw.get("direction", "higher"))
+            display = str(raw.get("display", "number"))
+            if direction not in METRIC_DIRECTIONS:
+                raise SpecError(
+                    f"direction 必须是 {'/'.join(METRIC_DIRECTIONS)} 之一，得到 {direction!r}",
+                    field=f"metrics.semantics.{canonical}.direction",
+                )
+            if display not in METRIC_DISPLAYS:
+                raise SpecError(
+                    f"display 必须是 {'/'.join(METRIC_DISPLAYS)} 之一，得到 {display!r}",
+                    field=f"metrics.semantics.{canonical}.display",
+                )
+            semantics[str(canonical)] = MetricSemantics(direction, display)
+        return cls(
+            primary=tuple(str(v) for v in primary_raw), aliases=aliases, semantics=semantics
+        )
 
 
 #: 验证样本形态：conversation（RL 对话+奖励）/ preference（DPO 偏好对）/
@@ -924,6 +1031,11 @@ class Recipe:
     def metric_aliases(self) -> dict[str, tuple[str, ...]]:
         return dict(self.metrics.aliases)
 
+    @property
+    def metric_semantics(self) -> dict[str, dict[str, str]]:
+        """本方法全部 canonical 指标的「怎么读」。服务端随 runtime_contract 下发。"""
+        return self.metrics.semantics_map()
+
     @property
     def max_steps_path(self) -> str | None:
         """训练步数上限超参在配置树里的落点（如 grpo.max_num_steps / max_steps）。

starforge_core-0.3.4/tests/cli/conftest.py

@@ -0,0 +1,19 @@
+"""CLI 单测默认在临时 StarForge 项目内运行（不再依赖 dogfood 仓里的 experiments/）。"""
+from __future__ import annotations
+
+import pytest
+
+from starforge.cli.commands import common
+from starforge.cli.repo import init_repo
+
+
+@pytest.fixture(autouse=True)
+def cli_project(tmp_path, monkeypatch):
+    root = init_repo(tmp_path / "sf-project", name="cli-tests", git=False)
+    (root / "experiments" / "demo").mkdir(exist_ok=True)
+    # ROOT 由 __getattr__ 惰性提供；setattr 会先 getattr 触发 project_root()。
+    # 必须写进模块字典，后续测试的 monkeypatch.setattr 才能覆盖。
+    monkeypatch.setitem(common.__dict__, "ROOT", root)
+    monkeypatch.setenv("SF_REPO_ROOT", str(root))
+    monkeypatch.chdir(root)
+    return root

starforge_core-0.3.4/tests/cli/test_bench.py

@@ -0,0 +1,78 @@
+"""sf bench：模型引用解析与评测提交参数翻译。"""
+from __future__ import annotations
+
+import io
+import json
+
+from typer.testing import CliRunner
+
+from starforge.cli import cli
+from starforge.cli.commands import bench as bench_cmd
+
+runner = CliRunner()
+
+
+def test_run_ref_resolves_hf_export(monkeypatch):
+    class _Resp(io.BytesIO):
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    def fake_bearer(srv, method, path):
+        assert path == "/api/jobs/run-42/artifacts"
+        return _Resp(json.dumps({"artifacts": [
+            {"kind": "checkpoint", "path": "/out/step_100"},
+            {"kind": "hf_export", "path": "/out/hf_export"},
+        ]}).encode())
+
+    monkeypatch.setattr(bench_cmd.api_client, "current_server", lambda *a: "http://srv")
+    monkeypatch.setattr(bench_cmd.api_client, "_bearer_request", fake_bearer)
+    assert bench_cmd._resolve_model_ref("run:run-42") == "/out/hf_export"
+    # 非 run: 引用原样返回
+    assert bench_cmd._resolve_model_ref("Qwen/Qwen3-0.6B") == "Qwen/Qwen3-0.6B"
+
+
+def test_bench_submits_evalkit_spec(monkeypatch, tmp_path):
+    (tmp_path / "experiments" / "bench-demo").mkdir(parents=True)
+    calls = {}
+
+    monkeypatch.setattr(bench_cmd.common, "ROOT", tmp_path)
+    monkeypatch.setattr(bench_cmd.common, "project_name", lambda: "test")
+    monkeypatch.setattr(bench_cmd, "gate", lambda: None)
+    monkeypatch.setattr(bench_cmd.common, "resolve_profile", lambda *a, **k: "h200")
+    monkeypatch.setattr(
+        bench_cmd, "_materialize_profile_or_exit",
+        lambda exprs: ("h200", ["eval:h200:1:1"], []),
+    )
+    monkeypatch.setattr(
+        bench_cmd.packing, "git_provenance",
+        lambda *a, **k: {"git_commit": "cafe", "git_dirty": False, "config_sha": "x"},
+    )
+
+    def fake_build_spec(exp_path, **kw):
+        calls["method"] = kw["method"]
+        calls["sets"] = kw["sets"]
+        calls["model"] = kw["model"]
+        calls["validate"] = kw["validate"]
+        return {"spec": True}
+
+    monkeypatch.setattr(bench_cmd, "_build_spec_or_exit", fake_build_spec)
+    monkeypatch.setattr(
+        bench_cmd.api_client, "submit_via_server",
+        lambda *a, **k: {"queued": False, "job_id": "ray-1", "run_id": "r1"},
+    )
+
+    res = runner.invoke(cli.app, [
+        "bench", "experiments/bench-demo",
+        "--model", "Qwen/Qwen3-0.6B",
+        "--suites", "gsm8k,mmlu",
+        "--runner", "evalscope",
+        "--limit", "20",
+    ])
+    assert res.exit_code == 0, res.stdout
+    assert calls["method"] == "evalkit/benchmark"
+    assert calls["model"] == "Qwen/Qwen3-0.6B"
+    assert calls["sets"] == ["runner=evalscope", "suites=gsm8k,mmlu", "limit=20"]
+    assert calls["validate"] is False

starforge_core-0.3.4/tests/cli/test_catalog_handshake.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+import pytest
+
+from starforge import __version__ as CORE_VERSION
+from starforge.cli.catalog import CatalogCompatibilityError, verify_catalog_compatibility
+from starforge.cli.spec_builder import build_spec
+from starforge.recipes import get_recipe
+
+
+def _payload(spec, **recipe_overrides):
+    recipe = get_recipe(spec.recipe_name)
+    item = {
+        "name": recipe.id,
+        "version": recipe.version,
+        "digest": recipe.digest,
+        "framework": recipe.framework,
+        "adapter": recipe.framework,
+        "framework_version": recipe.runtime.default_version,
+        "supported_framework_versions": list(recipe.runtime.supported_versions),
+        "runtime": recipe.runtime.to_dict(),
+    }
+    item.update(recipe_overrides)
+    canonical = [{"name": item["name"], "version": item["version"], "digest": item["digest"]}]
+    digest = hashlib.sha256(
+        json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    return {
+        "apiVersion": "forge/recipe-catalog/v2",
+        "contract": {"versions": ["forge/v2"]},
+        "core": {"version": "0.1.0", "requirement": ">=0.1,<1"},
+        "catalog_digest": f"sha256:{digest}",
+        "recipes": [item],
+    }
+
+
+def _spec():
+    return build_spec("experiments/demo", recipe="nemo-rl/grpo", pools=["all:h100:1:1"])
+
+
+def test_exact_catalog_handshake_accepts_matching_recipe():
+    verify_catalog_compatibility(_spec(), _payload(_spec()))
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [("version", "0.0.0"), ("digest", "sha256:wrong"), ("framework", "verl"), ("adapter", "verl")],
+)
+def test_catalog_handshake_rejects_recipe_drift(field, value):
+    spec = _spec()
+    with pytest.raises(CatalogCompatibilityError):
+        verify_catalog_compatibility(spec, _payload(spec, **{field: value}))
+
+
+def test_catalog_handshake_rejects_core_drift():
+    spec = _spec()
+    payload = _payload(spec)
+    payload["core"] = {"version": "9.0.0", "requirement": ">=9,<10"}
+    with pytest.raises(CatalogCompatibilityError, match="core"):
+        verify_catalog_compatibility(spec, payload)
+
+
+def test_catalog_handshake_accepts_compatible_core_range():
+    spec = _spec()
+    payload = _payload(spec)
+    payload["core"] = {"version": "0.2.0", "requirement": ">=0.1,<1"}
+    verify_catalog_compatibility(spec, payload)
+
+
+def test_catalog_handshake_still_accepts_legacy_v1_exact_match():
+    spec = _spec()
+    payload = _payload(spec)
+    payload["apiVersion"] = "forge/recipe-catalog/v1"
+    payload["core"] = {"version": CORE_VERSION, "requirement": f"=={CORE_VERSION}"}
+    verify_catalog_compatibility(spec, payload)
+
+
+def test_catalog_handshake_rejects_tampered_catalog_digest():
+    spec = _spec()
+    payload = _payload(spec)
+    payload["catalog_digest"] = "sha256:tampered"
+    with pytest.raises(CatalogCompatibilityError, match="catalog digest"):
+        verify_catalog_compatibility(spec, payload)
+
+
+def test_catalog_handshake_rejects_framework_version_or_runtime_id_drift():
+    spec = _spec()
+    payload = _payload(spec, supported_framework_versions=["9.9.9"])
+    with pytest.raises(CatalogCompatibilityError, match="未发布"):
+        verify_catalog_compatibility(spec, payload)
+
+    payload = _payload(spec)
+    payload["recipes"][0]["runtime"]["versions"]["0.7.0"]["runtime_id"] = "wrong-runtime"
+    with pytest.raises(CatalogCompatibilityError, match="runtime_id"):
+        verify_catalog_compatibility(spec, payload)
+
+
+def test_submit_does_not_package_when_handshake_fails(tmp_path, monkeypatch):
+    from starforge.cli import api_client
+
+    spec = _spec()
+    packed = []
+
+    monkeypatch.setattr(api_client, "current_server", lambda _server=None: "https://lab.example")
+    monkeypatch.setattr(
+        api_client,
+        "verify_server_compatibility",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(CatalogCompatibilityError("drift")),
+    )
+    monkeypatch.setattr(
+        api_client,
+        "pack_working_dir",
+        lambda *_args, **_kwargs: packed.append(True),
+    )
+
+    with pytest.raises(CatalogCompatibilityError, match="drift"):
+        api_client.submit_via_server(
+            "experiments/demo", "h100", tmp_path, spec=spec
+        )
+    assert packed == []
+
+
+def test_submit_requires_explicit_profile(tmp_path):
+    from starforge.cli import api_client
+
+    with pytest.raises(ValueError, match="profile"):
+        api_client.submit_via_server("experiments/demo", "", tmp_path, spec=_spec())