DaoyuanLi2816 · Aug 14, 2026 · Aug 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,19 @@ All notable changes to miniVERL are recorded here. The format follows
 
 ## [Unreleased]
 
+### Versioned compatibility profiles
+
+- Added a closed, typed compatibility-profile registry with independent
+  identity over the upstream pin, field-rule digest, native compiler, loss
+  conformance and export versions. New plans, native runs, teacher caches,
+  checkpoints and scale-out reports carry that identity.
+- Added torch-free `profiles list/show/schema` and `compat explain/check`
+  commands. They distinguish accepted, effective, locally reinterpreted,
+  informational, unsupported and non-applicable fields without loading
+  third-party entry points.
+- Began the CLI domain split by moving profile and compatibility commands out
+  of the root module without changing existing command names.
+
 ## [0.9.1] - 2026-08-13
 
 ### Semantic contract repair

diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md
@@ -31,6 +31,12 @@ Executable compatibility claims are mutation-tested and recorded in
 unknown-size quantized roles require proof instead of receiving an executable
 plan.
 
+Development `0.10.0.dev0` now has a closed typed profile registry and
+torch-free compatibility introspection. New profile-scoped plans, caches,
+checkpoints and exports bind an independent identity; the only registered
+executable profile remains the measured direct-GKD path until PG-k1 conformance
+and runtime work is complete.
+
 Arbitrary verl YAML, policy-gradient OPD, rewards, PPO/GRPO, Ray, FSDP,
 Megatron, multi-GPU and distributed execution remain unsupported. The legacy
 environment/PPO artifact bridge is migration-only.

diff --git a/PYPI.md b/PYPI.md
@@ -125,6 +125,11 @@ data, role and error mappings.
 
 ## Tested profile boundary
 
+Use `miniverl profiles list`, `profiles show/schema`, and `compat
+explain/check` to inspect the closed built-in registry and distinguish an
+accepted field from one with a demonstrated native effect. New plans, caches,
+checkpoints and exports bind the complete independent profile identity.
+
 `verl-opd-v0.8-single-gpu-v1` pins official verl `v0.8.0` at commit
 `7aed6b230776f963fa09509c10d9c3a767d1102c`. Its executable path is intentionally
 narrow:

diff --git a/README.md b/README.md
@@ -125,6 +125,11 @@ data, role and error mappings.
 
 ## Tested profile boundary
 
+Use `miniverl profiles list`, `profiles show/schema`, and `compat
+explain/check` to inspect the closed built-in registry and distinguish an
+accepted field from one with a demonstrated native effect. New plans, caches,
+checkpoints and exports bind the complete independent profile identity.
+
 `verl-opd-v0.8-single-gpu-v1` pins official verl `v0.8.0` at commit
 `7aed6b230776f963fa09509c10d9c3a767d1102c`. Its executable path is intentionally
 narrow:

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -104,6 +104,11 @@ config、data、role 与错误映射见[面向 verl 用户的指南](docs/for-ve
 
 ## 已测试的 profile 边界
 
+可用 `miniverl profiles list`、`profiles show/schema` 和 `compat
+explain/check` 查看封闭的内置 registry，并区分“字段可接受”和“字段确实对本地运行时
+生效”。新生成的 plan、cache、checkpoint 与 export 都绑定完整且独立版本化的 profile
+identity。
+
 `verl-opd-v0.8-single-gpu-v1` 固定官方 verl `v0.8.0` 与 commit
 `7aed6b230776f963fa09509c10d9c3a767d1102c`。可执行边界有意保持狭窄：
 

diff --git a/docs/for-verl-users.md b/docs/for-verl-users.md
@@ -5,6 +5,11 @@ keeps familiar field names and Parquet data, then compiles distributed resource
 intent into sequential phases on one CUDA GPU. It is an independent project;
 the mapping is explicit and does not imply endorsement or full compatibility.
 
+Inspect the closed, versioned registry with `miniverl profiles list`; use
+`miniverl compat explain` before assuming that an accepted field is effective.
+The [profile registry guide](profiles/index.md) documents the identity carried
+by plans, caches, checkpoints and exports.
+
 <picture>
   <source media="(max-width: 640px)" srcset="../verl-local-runtime-mobile.svg">
   <img src="../verl-local-runtime.svg" alt="verl-shaped YAML, overrides and Parquet prompts pass through a typed compiler; one CUDA GPU runs actor rollout, teacher scoring and actor update; portable artifacts can be handed to pinned verl while distributed execution remains outside miniVERL.">

diff --git a/docs/profiles/index.md b/docs/profiles/index.md
@@ -0,0 +1,44 @@
+# Compatibility profiles
+
+A miniVERL compatibility profile is a closed, versioned contract—not a claim
+that arbitrary verl YAML works locally. Each built-in profile binds its accepted
+schema and field rules to the upstream repository, tag and commit, plus explicit
+native-compiler, loss-conformance and export versions.
+
+```bash
+miniverl profiles list
+miniverl profiles show verl-opd-v0.8-single-gpu-v1
+miniverl profiles schema verl-opd-v0.8-single-gpu-v1 --json
+```
+
+`profiles show` includes a copyable resolved YAML example and override command.
+No entry points or third-party profile code are loaded.
+
+## Check a resolved profile
+
+```bash
+miniverl compat explain \
+  --profile verl-opd-v0.8-single-gpu-v1 \
+  actor_rollout_ref.actor.ppo_mini_batch_size
+
+miniverl compat check \
+  --profile verl-opd-v0.8-single-gpu-v1 \
+  --config verl-opd.yaml \
+  --accept-local-reinterpretations --json
+```
+
+The report distinguishes the supported algorithm, accepted and effective
+fields, local reinterpretations, informational fields, unsupported fields and
+profiles that do not apply. A field being parsed is not evidence that it changes
+the native runtime.
+
+## Independent artifact identity
+
+New immutable plans, native run manifests, teacher caches, checkpoints and
+scale-out reports carry the complete profile identity. Changing any version
+axis produces a new digest. Existing profile names cannot silently acquire new
+semantics; a later algorithm path is registered under a different name.
+
+Currently measured: `verl-opd-v0.8-single-gpu-v1`, the reward-free direct-GKD
+`forward_kl_topk` path. See [For verl users](../for-verl-users.md) for the
+algorithm and execution boundary.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -42,6 +42,7 @@ plugins:
 nav:
   - Home: index.md
   - For verl users: for-verl-users.md
+  - Compatibility profiles: profiles/index.md
   - Config overrides: config-overrides.md
   - Immutable plans: immutable-plans.md
   - Hardware planning: hardware-planning.md

diff --git a/src/miniverl/bridge/__init__.py b/src/miniverl/bridge/__init__.py
@@ -11,11 +11,15 @@
     VERL_TAG,
 )
 from miniverl.bridge.opd_v08 import VERL_OPD_V08_PROFILE
+from miniverl.bridge.profiles import ProfileIdentity, get_profile, list_profiles
 
 __all__ = [
     "BRIDGE_PROFILE",
     "VERL_COMMIT",
     "VERL_OPD_V08_PROFILE",
     "VERL_REPOSITORY",
     "VERL_TAG",
+    "ProfileIdentity",
+    "get_profile",
+    "list_profiles",
 ]
diff --git a/src/miniverl/bridge/export.py b/src/miniverl/bridge/export.py
@@ -663,6 +663,7 @@ def _export_opd_bundle(
         report: dict[str, Any] = {
             "schema_version": 2,
             "profile": _OPD_PROFILE,
+            "profile_identity": read_json(manifest_path).get("profile_identity") or {},
             "target_verl": {
                 "repository": VERL_REPOSITORY,
                 "tag": VERL_TAG,

diff --git a/src/miniverl/bridge/opd_plan.py b/src/miniverl/bridge/opd_plan.py
@@ -9,7 +9,7 @@
 from pathlib import Path
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
 from miniverl import __version__
 from miniverl.bridge.opd_runtime import OPDSystemPlan, build_system_plan, compile_native_run_config
@@ -38,6 +38,7 @@ class ImmutableOPDPlan(BaseModel):
     artifact_type: Literal["miniverl_immutable_opd_plan"] = "miniverl_immutable_opd_plan"
     miniverl_version: str
     profile: str
+    profile_identity: dict[str, Any] = Field(default_factory=dict)
     pinned_verl: dict[str, str]
     source_config: dict[str, Any]
     overrides: list[dict[str, Any]]
@@ -179,11 +180,15 @@ def build_immutable_opd_plan(
         native.models.teacher.revision,
         role="teacher",
     )
+    from miniverl.bridge.profiles import get_profile
+
+    profile_identity = get_profile(compiled.profile).identity.model_dump(mode="json")
     payload: dict[str, Any] = {
         "schema_version": 1,
         "artifact_type": "miniverl_immutable_opd_plan",
         "miniverl_version": __version__,
         "profile": compiled.profile,
+        "profile_identity": profile_identity,
         "pinned_verl": compiled.upstream,
         "source_config": source_identity,
         "overrides": [item.model_dump(mode="json") for item in compiled.overrides],

diff --git a/src/miniverl/bridge/opd_runtime.py b/src/miniverl/bridge/opd_runtime.py
@@ -291,6 +291,9 @@ def compile_native_run_config(
             "path": source.actor_rollout_ref.model.lora_adapter_path,
             **source.miniverl.student_adapter.model_dump(mode="json"),
         }
+    from miniverl.bridge.profiles import get_profile
+
+    profile_identity = get_profile(compiled.profile).identity.model_dump(mode="json")
     payload = {
         "schema_version": 1,
         "run": {
@@ -300,6 +303,7 @@ def compile_native_run_config(
             "output_dir": "runs",
             "deterministic": True,
             "tags": [compiled.profile, "verl-v0.8.0", "pure-opd"],
+            "profile_identity": profile_identity,
         },
         "models": {
             "backend": "hf",

diff --git a/src/miniverl/bridge/opd_v08.py b/src/miniverl/bridge/opd_v08.py
@@ -26,7 +26,9 @@
     "CompiledLocalExecutionPlan",
    "VERL_OPD_V08_PROFILE",
     "VerlOPDV08Profile",
+    "compatibility_rule",
     "compile_verl_opd_v08",
+    "field_rules_digest",
     "load_verl_opd_v08",
     "load_verl_opd_v08_source",
     "parse_overrides",
@@ -731,6 +733,30 @@ def _rule(
 }
 
 
+def compatibility_rule(field: str) -> dict[str, Any]:
+    """Return one immutable-profile rule without exposing the mutable registry."""
+    try:
+        rule = _FIELD_RULES[field]
+    except KeyError as exc:
+        raise ConfigError(
+            f"field {field!r} is not part of profile {VERL_OPD_V08_PROFILE!r}"
+        ) from exc
+    return {
+        "upstream_field": field,
+        "local_target": rule.target,
+        "classification": rule.classification,
+        "reason": rule.reason,
+        "semantic_risk": rule.risk,
+        "user_confirmation_required": rule.confirmation,
+    }
+
+
+def field_rules_digest() -> str:
+    """Bind profile identity to the complete canonical field-rule table."""
+    payload = [compatibility_rule(field) for field in sorted(_FIELD_RULES)]
+    return _canonical_digest(payload)
+
+
 def _flatten(value: Mapping[str, Any], prefix: str = "") -> dict[str, Any]:
     result: dict[str, Any] = {}
     for key, item in value.items():