fix: separate dp1s home from Python prefix

Author: OutisLi

skills/deepmd-install/references/easy-install.md

@@ -117,7 +117,7 @@ to a shell:
 
 ```bash
 curl -fsSL https://dp1s.deepmodeling.com | env \
-    DP1S_HOME="<absolute-environment-prefix>" \
+    DP1S_HOME="<absolute-dp1s-home>" \
     DP1S_NO_PATH_UPDATE=1 \
     DEEPMD_VERSION="<deepmd-version>" \
     bash
@@ -126,8 +126,11 @@ curl -fsSL https://dp1s.deepmodeling.com | env \
 Omit the `DEEPMD_VERSION` assignment when `package.deepmd_version` is null.
 `DP1S_NO_PATH_UPDATE` prevents the installer from editing shell startup files.
 Apply only additional options selected from the official `dp1s` documentation.
-After installation, resolve the absolute interpreter from the installed `dp`
-entry point, record it in the plan, and re-run validation before verification.
+After installation, keep `environment.dp1s_home` unchanged. Resolve the absolute
+interpreter from the installed `dp` entry point, run that interpreter to obtain
+its `sys.prefix`, record both as `environment.python` and `environment.prefix`,
+and re-run validation before verification. The Python prefix normally differs
+from `dp1s_home`; pass only `environment.prefix` to `--expected-prefix`.
 
 ## Offline package
 

skills/deepmd-install/references/failure-modes.md

@@ -68,10 +68,15 @@ argument with `package.channels`. An empty list uses only the stable
 recorded order. A non-null `package.deepmd_version` produces the exact
 `deepmd-kit=<version>` package constraint.
 
-For `dp1s`, compare `DP1S_HOME` and the optional `DEEPMD_VERSION` with the plan,
-and require `DP1S_NO_PATH_UPDATE=1`. For JAX C/C++, two null TensorFlow roots
-select the Python-library route. A single root selects its corresponding
-external library route; setting both is ambiguous and invalid.
+For `dp1s`, compare `DP1S_HOME` with `environment.dp1s_home`, compare the
+optional `DEEPMD_VERSION` with the plan, and require
+`DP1S_NO_PATH_UPDATE=1`. Preserve `dp1s_home` after installation; record the
+installed interpreter's distinct `sys.prefix` as `environment.prefix` for the
+Python identity gate.
+
+For JAX C/C++, two null TensorFlow roots select the Python-library route. A
+single root selects its corresponding external library route; setting both is
+ambiguous and invalid.
 
 ## Wrong skill root
 

skills/deepmd-install/references/plan-schema.md

@@ -54,7 +54,8 @@ Use `null` for an inapplicable object. Do not add undeclared keys.
   "python": "/absolute/path/to/python",
   "manager": null,
   "name": null,
-  "prefix": "/absolute/environment/prefix"
+  "prefix": "/absolute/environment/prefix",
+  "dp1s_home": null
 }
 ```
 
@@ -63,9 +64,13 @@ Use `null` for an inapplicable object. Do not add undeclared keys.
   environment and before installing DeePMD-kit.
 - `manager` and `name`: required for `conda`; `manager` is the absolute
   `conda` or `mamba` executable.
-- `prefix`: required for `pip`, `source`, `venv`, `prefix`, `dp1s`, and offline
+- `prefix`: required for `pip`, `source`, `venv`, `prefix`, and offline
   installations. For conda, resolve and record both `sys.executable` and
   `sys.prefix` after creating the environment and before verification.
+- `dp1s_home`: required only for `dp1s`; it is the Pixi and exposed-binary root
+  passed as `DP1S_HOME`, not the installed Python prefix. Before installation,
+  keep `python` and `prefix` null. After installation, preserve `dp1s_home` and
+  record the resolved interpreter and its `sys.prefix` together.
 
 ### `package`
 
@@ -241,7 +246,8 @@ The validator enforces these invariants:
     "python": "/opt/conda/envs/deepmd/bin/python",
     "manager": null,
     "name": null,
-    "prefix": "/opt/conda/envs/deepmd"
+    "prefix": "/opt/conda/envs/deepmd",
+    "dp1s_home": null
   },
   "package": {
     "deepmd_version": null,
@@ -289,7 +295,8 @@ before installing dependencies or building.
     "python": "/opt/conda/envs/deepmd/bin/python",
     "manager": null,
     "name": null,
-    "prefix": "/opt/conda/envs/deepmd"
+    "prefix": "/opt/conda/envs/deepmd",
+    "dp1s_home": null
   },
   "package": {
     "deepmd_version": null,

skills/deepmd-install/scripts/validate_plan.py

@@ -43,7 +43,7 @@
     "smoke_test",
 }
 OBJECT_KEYS = {
-    "environment": {"kind", "python", "manager", "name", "prefix"},
+    "environment": {"kind", "python", "manager", "name", "prefix", "dp1s_home"},
     "package": {
         "deepmd_version",
         "deepmd_index_url",
@@ -234,12 +234,36 @@ def _validate_environment(
                 errors.append(
                     f"environment.{key}: conda requires an absolute path or null"
                 )
-    if kind in {"venv", "prefix"} and not _is_absolute_path(environment.get("prefix")):
-        errors.append(f"environment.prefix: {kind} requires an absolute path")
-    if method in {"dp1s", "offline"} and not _is_absolute_path(
-        environment.get("prefix")
+    if method == "dp1s":
+        if not _is_absolute_path(environment.get("dp1s_home")):
+            errors.append("environment.dp1s_home: dp1s requires an absolute path")
+        python = environment.get("python")
+        prefix = environment.get("prefix")
+        unresolved = python is None and prefix is None
+        resolved = _is_absolute_path(python) and _is_absolute_path(prefix)
+        if not (unresolved or resolved):
+            errors.append(
+                "environment: dp1s python and prefix must both be null or absolute paths"
+            )
+        if (
+            resolved
+            and _is_absolute_path(environment.get("dp1s_home"))
+            and _canonical(environment["dp1s_home"]) == _canonical(prefix)
+        ):
+            errors.append(
+                "environment: dp1s_home and resolved Python prefix must be distinct"
+            )
+    elif environment.get("dp1s_home") is not None:
+        errors.append("environment.dp1s_home: allowed only for method 'dp1s'")
+    dp1s_prefix_pending = method == "dp1s" and environment.get("prefix") is None
+    if (
+        kind in {"venv", "prefix"}
+        and not dp1s_prefix_pending
+        and not _is_absolute_path(environment.get("prefix"))
     ):
-        errors.append(f"environment.prefix: {method} requires an absolute path")
+        errors.append(f"environment.prefix: {kind} requires an absolute path")
+    if method == "offline" and not _is_absolute_path(environment.get("prefix")):
+        errors.append("environment.prefix: offline requires an absolute path")
     if method == "docker" and kind != "container":
         errors.append("environment.kind: docker requires 'container'")
 

source/tests/test_deepmd_install_skill.py

@@ -55,6 +55,7 @@ def _source_plan() -> dict[str, object]:
             "manager": None,
             "name": None,
             "prefix": "/opt/deepmd",
+            "dp1s_home": None,
         },
         "package": {
             "deepmd_version": None,
@@ -117,6 +118,7 @@ def _easy_plan(method: str) -> dict[str, object]:
         "manager": None,
         "name": None,
         "prefix": "/opt/deepmd",
+        "dp1s_home": None,
     }
     package: dict[str, object] = {
         "deepmd_version": None,
@@ -137,6 +139,15 @@ def _easy_plan(method: str) -> dict[str, object]:
         environment.update(
             {"kind": "conda", "python": None, "manager": "/opt/conda", "name": "deepmd"}
         )
+    elif method == "dp1s":
+        environment.update(
+            {
+                "kind": "prefix",
+                "python": None,
+                "prefix": None,
+                "dp1s_home": "/opt/dp1s",
+            }
+        )
     elif method == "offline":
         environment.update({"kind": "prefix", "python": None})
         package.update(
@@ -237,7 +248,7 @@ def test_validate_jax_cpp_rejects_ambiguous_tensorflow_roots() -> None:
     assert any("mutually exclusive" in error for error in errors)
 
 
-@pytest.mark.parametrize("method", ["pip", "conda", "offline", "docker"])
+@pytest.mark.parametrize("method", ["pip", "conda", "dp1s", "offline", "docker"])
 def test_validate_easy_install_plans(method: str) -> None:
     """Accept the method-specific fields for each easy-install path."""
     assert PLAN.validate_plan(_easy_plan(method)) == []
@@ -272,6 +283,41 @@ def test_validate_conda_channels_are_method_specific() -> None:
     assert "package.channels: non-empty channels require method 'conda'" in errors
 
 
+def test_validate_dp1s_lifecycle_keeps_home_and_prefix_distinct(tmp_path: Path) -> None:
+    """Accept unresolved and resolved dp1s identities without conflating paths."""
+    plan = _easy_plan("dp1s")
+    environment = plan["environment"]
+    assert isinstance(environment, dict)
+    dp1s_home = tmp_path / "dp1s-home"
+    python_prefix = dp1s_home / "envs" / "dp1s"
+    environment["dp1s_home"] = str(dp1s_home)
+    assert PLAN.validate_plan(plan) == []
+
+    environment["python"] = str(python_prefix / "bin" / "python")
+    environment["prefix"] = str(python_prefix)
+    assert environment["dp1s_home"] != environment["prefix"]
+    assert PLAN.validate_plan(plan) == []
+
+    environment["prefix"] = environment["dp1s_home"]
+    errors = PLAN.validate_plan(plan)
+    assert any("must be distinct" in error for error in errors)
+
+    environment["prefix"] = str(python_prefix)
+    environment["python"] = None
+    errors = PLAN.validate_plan(plan)
+    assert any("must both be null or absolute paths" in error for error in errors)
+
+
+def test_validate_dp1s_home_is_method_specific() -> None:
+    """Reject a dp1s installer root that another method would ignore."""
+    plan = _easy_plan("pip")
+    environment = plan["environment"]
+    assert isinstance(environment, dict)
+    environment["dp1s_home"] = "/opt/dp1s"
+    errors = PLAN.validate_plan(plan)
+    assert "environment.dp1s_home: allowed only for method 'dp1s'" in errors
+
+
 @pytest.mark.parametrize("field", ["python", "prefix"])
 def test_validate_conda_resolved_paths_must_be_absolute(field: str) -> None:
     """Reject a relative Conda interpreter or prefix after environment creation."""
@@ -934,9 +980,10 @@ def test_dp1s_reference_preserves_planned_identity() -> None:
     reference = (
         REPOSITORY_ROOT / "skills" / "deepmd-install" / "references" / "easy-install.md"
     ).read_text(encoding="utf-8")
-    assert 'DP1S_HOME="<absolute-environment-prefix>"' in reference
+    assert 'DP1S_HOME="<absolute-dp1s-home>"' in reference
     assert 'DEEPMD_VERSION="<deepmd-version>"' in reference
     assert "DP1S_NO_PATH_UPDATE=1" in reference
+    assert '--expected-prefix "<absolute-environment-prefix>"' in reference
 
 
 def test_verify_lammps_dpa4c_cli(tmp_path: Path) -> None: