instance-repo 1.4.1.dev0__tar.gz → 1.6.0.dev2__tar.gz

{instance_repo-1.4.1.dev0 → instance_repo-1.6.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.4.1.dev0
+Version: 1.6.0.dev2
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.4.1.dev0 → instance_repo-1.6.0.dev2}/instance_repo/__init__.py

@@ -20,7 +20,7 @@ from .errors import (
     RegistrationFailed, TransportError,
 )
 
-__version__ = "1.4.1.dev0"
+__version__ = "1.6.0.dev2"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.4.1.dev0 → instance_repo-1.6.0.dev2}/instance_repo/_site_defaults.py

@@ -37,3 +37,11 @@ ARTIFACT_PREFIX_ROOT = ""
 #: 注入。运行时也可经环境变量 AP_ARTIFACT_BUCKET_MAP（JSON）覆盖，优先级：
 #: 环境变量 > 本模块注入值 > 空（空则 artifact 下载报错并引导配置）。
 ARTIFACT_BUCKET_MAP_JSON = ""
+
+#: 期望 replica policy（canonical 双桶对）的 JSON 串。**源码恒为空**；
+#: 内网构建时由发布脚本注入（与 API_BASE 同模式——静态可审计、无
+#: envvar 通道）。运行时解析为 ``ReplicasPolicy``（严格 JSON/拒重复
+#: keys/构造验证）；公共包通过显式构造参数传入有效 policy 亦可运行。
+#: 优先级：显式构造参数 > 本模块注入值 > 缺失（缺失=新客户端零 IO
+#: typed error）。
+EXPECTED_REPLICA_POLICY_JSON = ""

instance_repo-1.6.0.dev2/instance_repo/clients/_rfc3339.py

@@ -0,0 +1,41 @@
+"""Private RFC3339 calendar parser with Python 3.10+ fraction behavior.
+
+Wire values remain untouched at the call sites. Python datetime arithmetic uses
+microseconds, matching 3.11+ fromisoformat truncation of finer fractions; expiry
+is never rounded up. The original wire precision is not an integrity anchor.
+"""
+from datetime import datetime, timedelta, timezone
+import re
+
+_UTC = re.compile(
+    r'([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})'
+    r'(?:\.([0-9]+))?(Z|[+-][0-9]{2}:[0-9]{2})\Z')
+
+
+def parse_utc(value: str, *, allow_offset: bool = False) -> datetime:
+    """Validate calendar fields without version-specific ISO parsing.
+
+    Fraction processing is bounded to six digits, including arbitrarily precise
+    values permitted by existing read/write callers. Entries keeps its existing
+    one-to-nine-digit and byte bounds before invoking this helper.
+    """
+    match = _UTC.fullmatch(value) if type(value) is str and type(allow_offset) is bool else None
+    if match is None:
+        raise ValueError('invalid RFC3339 UTC datetime')
+    fraction = match.group(7) or ''
+    microsecond = int((fraction[:6] + '000000')[:6])
+    suffix = match.group(8)
+    hours, minutes = (0, 0) if suffix == 'Z' else (int(suffix[1:3]), int(suffix[4:6]))
+    if hours > 23 or minutes > 59 or (not allow_offset and (hours or minutes)):
+        raise ValueError('invalid RFC3339 datetime offset')
+    offset = (hours * 60 + minutes) * (-1 if suffix.startswith('-') else 1)
+    parsed = None
+    try:
+        parsed = datetime(*(int(match.group(n)) for n in range(1, 7)),
+                          microsecond=microsecond, tzinfo=timezone(timedelta(minutes=offset)))
+    except ValueError:
+        pass
+    if parsed is None:
+        # Do not attach a calendar exception or raw wire string to the error.
+        raise ValueError('invalid RFC3339 UTC calendar datetime')
+    return parsed

instance_repo-1.6.0.dev2/instance_repo/clients/ap_tool.py

@@ -0,0 +1,265 @@
+"""Exact key builder/parser for the currently registered RewardKit profile.
+
+Only pyz/tf-rewardkit/rewardkit-VERSION-linux-x86_64.pyz is supported under
+swe/user-data/ap-tool/. VERSION uses the approved verbatim PEP440 subset;
+component/version128bytes, full key512bytes. No hash/fileID/version directory,
+normalization, percent decoding, extra tool registration or platform expansion.
+"""
+from __future__ import annotations
+
+import re
+
+from ..errors import SchemaError
+
+#: ap-tool 域根（不可变；层级含义=ap-tool/包类型/工具名/文件名）。
+TOOL_KEY_ROOT = "swe/user-data/ap-tool/"
+
+#: 默认包类型（当前唯一正式类型；新类型须用户明确同意后扩展）。
+DEFAULT_TOOL_KIND = "pyz"
+
+#: tf-rewardkit 的文件名 stem（发布名=工具名去 ``tf-`` 前缀，H1 逐字节锚定）。
+
+#: 工具名：小写字母开头，小写/数字/连字符（tf-rewardkit、t-rewardkit-2 等）。
+# fullmatch：``tf-rewardkit.``/``tf rewardkit``/``tf\u2044rewardkit`` 全部拒收。
+_TOOL_NAME_RE = re.compile(r"[a-z](?:[a-z0-9-]*[a-z0-9])?")
+
+#: 包类型：纯小写字母（pyz；类型层不是自由命名空间）。
+_KIND_RE = re.compile(r"[a-z]+")
+
+#: 版本串：PEP440 **canonical** 形态（与真实 RewardKit publisher 对齐，
+# Codex 退修 2026-10-30：已发版 1.1.0.dev2 必须支持；rc/post/local 支持）。
+# canonical = N(.N)*[{a|b|rc}N][.postN][.devN][+local]——全部小写、无空白；
+# local 段限定小写字母/数字/点（**禁连字符**：``-`` 是文件名中 version 与
+# platform 的唯一分隔符，local 含 ``-`` 会造成 parse 歧义——``1.2.3+a-b`` 
+# 无法区分 local 边界与 platform 开头，fail-closed 拒绝；PEP440 允许更宽的
+# local 字符集，本协议收窄到文件名无歧义子集）；大写/下划线等非 canonical
+# 形态直接拒绝——不做归一化，调用方必须传 canonical（零静默改写，
+# "No silent normalization"）。
+# 版本中的点属于版本语法本身——段字符白名单不适用于 version（单独校验）。
+_VERSION_EPOCH = r"(?:0|[1-9][0-9]*)"
+_VERSION_PRE = r"(?:(?:a|b|rc)(?:0|[1-9][0-9]*))?"
+_VERSION_POST = r"(?:\.(?:post|rev|r)(?:0|[1-9][0-9]*))?"
+_VERSION_DEV = r"(?:\.dev(?:0|[1-9][0-9]*))?"
+_VERSION_LOCAL = r"(?:\+[a-z0-9]+(?:\.[a-z0-9]+)*)?"
+_VERSION_RE = re.compile(
+    _VERSION_EPOCH + r"(?:\." + _VERSION_EPOCH + r")*"
+    + _VERSION_PRE + _VERSION_POST + _VERSION_DEV + _VERSION_LOCAL)
+
+#: 平台串：小写/数字/连字符/下划线（linux-x86_64、linux-aarch64）。
+_PLATFORM_RE = re.compile(r"[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?")
+
+#: 文件名整体（stem-version-platform.pyz）：自右锚定，version 段为 PEP440
+#: canonical 形态（含 dev/rc/post/local；点与 ``+`` 属版本语法，不与
+#: stem 的 ``-`` 分隔混淆——分隔符仍为 ``-``，platform 无点无 ``+``）。
+_FILENAME_RE = re.compile(
+    r"(?P<stem>[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)"
+    r"-(?P<version>" + _VERSION_EPOCH + r"(?:\." + _VERSION_EPOCH + r")*"
+    + _VERSION_PRE + _VERSION_POST + _VERSION_DEV + _VERSION_LOCAL + r")"
+    r"-(?P<platform>[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)"
+    r"\.pyz")
+
+#: 组件段长上限（字节）：tool_name/kind/platform 等段共用——与 API 侧
+#: shared component 界限同值（128；Codex 03:30 统一裁定，替代先前的
+#: 先行值 256）。防御异常超长输入（对齐 shared 路径安全风格）。
+_MAX_SEGMENT_BYTES = 128
+
+#: 最大版本串长度（字节，=A 侧 sharedNameVersionMaxLen=128；Codex 03:30
+#: 统一裁定：64→128 放开——此前 64 是 B 侧先行值非约定，**勿任意收窄已
+#: 约定有效版本**）。
+MAX_VERSION_BYTES = 128
+
+#: 最大文件名长度（字节）：'pyz'+'-'+tool_name(≤128)+'-'+filename(≤388)
+#: 的组成上界 ≈ 496，与整 key 界限 512 严格相容（不出现"filename 合法
+#: 但 key 必然越界"的死区）；生成侧与 parse 侧共用同一界限。
+MAX_FILENAME_BYTES = 388
+
+#: 整 key 长度（字节，=A/API 既有 key 上限 512；parse 前置检查——超长
+#: key 在任何正则/切分前拒绝。Codex 03:30 统一裁定：1024→512）。
+MAX_KEY_BYTES = 512
+
+
+def _validate_segment(value: str, what: str, regex: re.Pattern) -> str:
+    """通用段校验：非空、长度有界、无首尾空白、白名单 fullmatch。
+
+    **不解码不变式**：``%`` 不在任何白名单字符集内——``%2e%2e``/``%2F``/
+    ``%252e`` 在此被字面拒绝；控制符/空白/反斜杠/非 ASCII（含 Unicode
+    斜杠变体）同理（字符集仅 ASCII 小写字母/数字/连字符/点/下划线子集）。
+    """
+    if not isinstance(value, str):
+        raise SchemaError("ap-tool key component must be a string")
+    v = value
+    if not v:
+        raise SchemaError(f"ap-tool key segment {what!r} must not be empty")
+    if len(v.encode("utf-8")) > _MAX_SEGMENT_BYTES:
+        raise SchemaError(
+            f"ap-tool key segment {what!r} exceeds "
+            f"{_MAX_SEGMENT_BYTES} bytes: {v!r}")
+    if v != v.strip():
+        raise SchemaError(
+            f"ap-tool key segment {what!r} has leading/trailing "
+            f"whitespace: {v!r}")
+    if regex.fullmatch(v) is None:
+        raise SchemaError(
+            f"invalid ap-tool key segment {what!r}: {v!r} (allowed charset "
+            "is a restrictive ASCII subset; percent-encodings, uppercase, "
+            "whitespace, slashes and unicode variants are rejected "
+            "literally without decoding)")
+    return v
+
+
+def validate_tool_version(version: str) -> str:
+    """校验版本串：PEP440 **canonical** 形态（与 RewardKit publisher 对齐）。
+
+    合法：``1.2.3``、``1.1.0.dev2``（已发版）、``1.2.3rc1``、``1.2.3.post1``、
+    ``1.0a1``、``1.2.3+local.7``（local 限定小写/数字/点/连字符子集）。
+    拒绝：非 canonical（``1.2.3.RC1`` 大写、``1.2.3-rc1`` 连字符分隔、
+    ``1.02.3`` 前导零、``v1.2`` 前缀、``1.2.3..post1`` 空段）、斜杠/点段
+    路径形态、编码逃逸（``%`` 不在字符集）、控制符、空白。
+    **零静默归一化**：版本原样进入 key（canonical 要求由调用方保证——
+    非 canonical 输入被拒而非被改写；validate 返回值恒等于输入原串）。
+    """
+    if not isinstance(version, str):
+        raise SchemaError("ap-tool version must be a string")
+    v = version
+    if not v:
+        raise SchemaError("ap-tool version must not be empty")
+    # 长度界限先于任何正则（Codex 边界 review：超长数字版本曾通过）。
+    if len(v.encode("utf-8")) > MAX_VERSION_BYTES:
+        raise SchemaError(
+            f"ap-tool version exceeds {MAX_VERSION_BYTES} bytes: "
+            f"{len(v.encode('utf-8'))} bytes")
+    if v != v.strip():
+        raise SchemaError(
+            f"invalid ap-tool version {v!r}: leading/trailing whitespace")
+    if _VERSION_RE.fullmatch(v) is None:
+        raise SchemaError(
+            f"invalid ap-tool version {v!r}: must be PEP440 canonical "
+            "(e.g. 1.2.3, 1.1.0.dev2, 1.2.3rc1, 1.2.3.post1, "
+            "1.2.3+local; no leading zeros, uppercase, hyphen separators, "
+            "prefix letters or escapes)")
+    return v
+
+
+def validate_tool_platform(platform: str) -> str:
+    """校验平台串：小写字母/数字/连字符/下划线（linux-x86_64 等）。"""
+    return _validate_segment(platform, "platform", _PLATFORM_RE)
+
+
+def validate_tool_name(tool_name: str) -> str:
+    """校验工具名：小写字母开头的小写/数字/连字符段（tf-rewardkit 等）。"""
+    return _validate_segment(tool_name, "tool_name", _TOOL_NAME_RE)
+
+
+def validate_tool_kind(kind: str) -> str:
+    """校验包类型段：纯小写字母（pyz）。新类型须用户明确同意后扩展。"""
+    return _validate_segment(kind, "kind", _KIND_RE)
+
+
+def tool_filename(tool_name: str, version: str, *,
+                  platform: str = "linux-x86_64") -> str:
+    """version→文件名映射（协议锚定；version **verbatim** 原样入名）。
+
+    tf-rewardkit + 1.1.0.dev2 → ``rewardkit-1.1.0.dev2-linux-x86_64.pyz``；
+    tf-rewardkit + 1.2.3 → ``rewardkit-1.2.3-linux-x86_64.pyz``：
+    Registered tool identity maps tf-rewardkit directory to rewardkit artifact.版本串不做任何
+    归一化改写（canonical 由 validate 保证，文件名所见即调用方所传）。
+    """
+    name = validate_tool_name(tool_name)
+    ver = validate_tool_version(version)
+    plat = validate_tool_platform(platform)
+    if name != "tf-rewardkit" or plat != "linux-x86_64":
+        raise SchemaError("unsupported tool profile; only tf-rewardkit/linux-x86_64 is registered")
+    stem = "rewardkit"
+    if not stem:
+        raise SchemaError(
+            f"invalid ap-tool tool_name {tool_name!r}: 'tf-' alone has no "
+            "file stem")
+    filename = f"{stem}-{ver}-{plat}.pyz"
+    # 生成侧界限（Codex 边界 review 2026-10-31）：合成文件名超过上限拒绝。
+    if len(filename.encode("utf-8")) > MAX_FILENAME_BYTES:
+        raise SchemaError(
+            f"ap-tool filename exceeds {MAX_FILENAME_BYTES} bytes: "
+            f"{len(filename.encode('utf-8'))} bytes")
+    return filename
+
+
+def tool_object_key(tool_name: str, version: str, *,
+                    kind: str = DEFAULT_TOOL_KIND,
+                    platform: str = "linux-x86_64") -> str:
+    """正式工具对象 key（唯一入口；两桶同 key 的单一来源）。
+
+    例：``tool_object_key("tf-rewardkit", "1.2.3")`` 逐字节返回
+    ``swe/user-data/ap-tool/pyz/tf-rewardkit/rewardkit-1.2.3-linux-x86_64.pyz``；
+    ``tool_object_key("tf-rewardkit", "1.1.0.dev2")`` 逐字节返回
+    ``swe/user-data/ap-tool/pyz/tf-rewardkit/rewardkit-1.1.0.dev2-linux-x86_64.pyz``
+    （实际已发版 key，roundtrip 锚点；A 报告 §8.4 H1-H5 同构）。
+
+    设计约束（差异B §6.2）：SHA/size/generation 不入路径；调用方对主/从桶
+    复用**同一返回值**（结构上杜绝两桶 key 分叉）。
+    """
+    name = validate_tool_name(tool_name)
+    k = validate_tool_kind(kind)
+    if k != "pyz":
+        raise SchemaError("unsupported tool package; only pyz is registered")
+    filename = tool_filename(tool_name, version, platform=platform)
+    key = f"{TOOL_KEY_ROOT}{k}/{name}/{filename}"
+    # 整 key 界限（生成侧；parse 侧同界限前置——两侧同一常量）。
+    if len(key.encode("utf-8")) > MAX_KEY_BYTES:
+        raise SchemaError(
+            f"ap-tool key exceeds {MAX_KEY_BYTES} bytes: "
+            f"{len(key.encode('utf-8'))} bytes")
+    return key
+
+
+def parse_tool_object_key(key: str) -> dict:
+    """解析正式 key 为协议字段（消费侧对账/下载 URL 校验用，H2 同口径）。
+
+    返回 ``{tool_name, kind, version, platform, filename}``；任何偏离协议
+    模板的 key（域根下段数≠3、非 pyz 扩展、文件名不匹配
+    ``stem-version-platform.pyz``、stem 与 tool_name 不一致）拒绝——用于把
+    download URL / 回执 final_key 与正式协议三方对账（A 报告 H2/H3）。
+    """
+    v = str(key or "")
+    # parse 前置整 key 界限（Codex 边界 review 2026-10-31：先于任何正则/
+    # 切分——超长 key 在最前面拒绝，不进入解析路径）。
+    if len(v.encode("utf-8")) > MAX_KEY_BYTES:
+        raise SchemaError(
+            f"ap-tool key exceeds {MAX_KEY_BYTES} bytes: "
+            f"{len(v.encode('utf-8'))} bytes")
+    if not v.startswith(TOOL_KEY_ROOT):
+        raise SchemaError(
+            f"key {v!r} is not under ap-tool root {TOOL_KEY_ROOT!r}")
+    rest = v[len(TOOL_KEY_ROOT):]
+    segs = rest.split("/")
+    if len(segs) != 3:
+        raise SchemaError(
+            f"ap-tool key must have exactly 3 segments under the root "
+            f"(kind/tool_name/filename), got {len(segs)}: {v!r}")
+    kind, name, filename = segs
+    validate_tool_kind(kind)
+    validate_tool_name(name)
+    # parse 侧文件名界限（先于 _FILENAME_RE——与生成侧同常量）。
+    if len(filename.encode("utf-8")) > MAX_FILENAME_BYTES:
+        raise SchemaError(
+            f"ap-tool key filename exceeds {MAX_FILENAME_BYTES} bytes: "
+            f"{len(filename.encode('utf-8'))} bytes")
+    if not filename.endswith(".pyz"):
+        raise SchemaError(
+            f"ap-tool key filename must end with .pyz: {filename!r}")
+    m = _FILENAME_RE.fullmatch(filename)
+    if m is None:
+        raise SchemaError(
+            f"ap-tool key filename malformed (expected "
+            f"stem-version-platform.pyz): {filename!r}")
+    stem = m.group("stem")
+    expected_stem = name[len("tf-"):] if name.startswith("tf-") else name
+    if stem != expected_stem:
+        raise SchemaError(
+            f"ap-tool key filename stem {stem!r} does not match tool_name "
+            f"{name!r} (expected {expected_stem!r})")
+    validate_tool_version(m.group("version"))
+    validate_tool_platform(m.group("platform"))
+    if tool_object_key(name, m.group("version"), kind=kind, platform=m.group("platform")) != v:
+        raise SchemaError("ap-tool key does not match registered tool profile")
+    return {"tool_name": name, "kind": kind, "version": m.group("version"),
+            "platform": m.group("platform"), "filename": filename}

{instance_repo-1.4.1.dev0 → instance_repo-1.6.0.dev2}/instance_repo/clients/config.py

@@ -26,6 +26,7 @@ OSS bucket/endpoint/region 或 ACR registry/namespace，这些一律运行时取
 """
 from __future__ import annotations
 
+import contextlib
 import logging
 import os
 import warnings
@@ -230,6 +231,12 @@ class Profile:
     #: 内网时置 True，配合 ``acr_public_host``（repo-config 的 public_registry）
     #: 生效；公网值缺失时静默回落到 ``acr_host``。
     prefer_public_registry: bool = False
+    #: user-data 域独立 OSS bucket（F2-R1）：显式配置优先于 scope=user-data
+    #: 自动发现（零发现网络调用）。空 = 走发现。
+    user_data_bucket: str = ""
+    #: user-data 域独立 OSS endpoint（F2-R1）：显式配置优先（须与 user_data_bucket
+    #: 配套使用——bucket 走发现时该字段忽略，endpoint 以发现结果为准）。空=不覆盖。
+    user_data_endpoint: str = ""
 
     @property
     def effective_acr_host(self) -> str:
@@ -311,7 +318,8 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         # 只接受已知字段，避免把 api_env 之类误当数据面字段；
         # prefer_public_registry 单独取（非寻址字段，不进 **cfg 传 Profile）。
         for k in ("oss_bucket", "acr_host", "acr_namespace", "acr_public_host",
-                  "oss_prefix", "scaffold_bucket", "scaffold_root", "api_base"):
+                  "oss_prefix", "scaffold_bucket", "scaffold_root", "api_base",
+                  "user_data_bucket", "user_data_endpoint"):
             if k in overrides and overrides[k] is not None:
                 cfg[k] = overrides[k]
                 sources[k] = "explicit"
@@ -324,6 +332,8 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         prefer_public = os.environ.get(ENV_ACR_PREFER_PUBLIC, "").strip().lower() \
             in ("1", "true", "on")
     return Profile(name=name, api_env=env,
+                   user_data_bucket=str(cfg.pop("user_data_bucket", "") or "").strip(),
+                   user_data_endpoint=str(cfg.pop("user_data_endpoint", "") or "").strip(),
                    cluster=str(cluster_value).strip(),
                    storage_env=normalize_storage_env(storage_value),
                    metadata_model=requested_model,
@@ -486,3 +496,197 @@ def clear_cluster_map_cache() -> None:
     global _cluster_map_cache, _cluster_map_expiry
     _cluster_map_cache = {}
     _cluster_map_expiry = {}
+
+
+# ── scope=user-data 独立配置发现（T-SDK-USERDATA，对齐 apiserver F1 schema1）────
+
+#: user-data scope 的合法取值（apiserver repo_config_handler.repoConfigScopeUserData）。
+USER_DATA_SCOPE = "user-data"
+
+#: user-data 响应契约版本（apiserver userDataSchemaVersion；SDK 只认 1）。
+USER_DATA_SCHEMA_VERSION = 1
+
+#: user-data 域根前缀锚（apiserver userDataPrefixRoot / Repo.USER_DATA_ROOT）。
+USER_DATA_PREFIX_ROOT = "swe/user-data/users/"
+
+
+@dataclass(frozen=True)
+class UserDataConfig:
+    """scope=user-data 的解析结果：仅 OSS 寻址 + 能力声明，**不含任何密钥**。
+
+    ``production_read_enabled`` / ``production_write_enabled`` 只是当前部署的
+    gate **能力声明**，不构成授权——真实 STS 每次按认证主体与 RBAC 重新判定，
+    调用方不得据此假定签发结果。旧服务（不认识 scope）经 ``allow_fallback``
+    兼容时，这两个字段恒为 False（能力未知 → 关闭，不猜生产开启）。
+    """
+
+    schema_version: int = USER_DATA_SCHEMA_VERSION
+    storage_env: str = ""
+    prefix_root: str = USER_DATA_PREFIX_ROOT
+    production_read_enabled: bool = False
+    production_write_enabled: bool = False
+    oss_bucket: str = ""
+    oss_prefix: str = ""
+    oss_endpoint: str = ""
+    oss_region: str = ""
+
+    def to_profile_overrides(self) -> dict:
+        """转成 user-data **独立** profile overrides（只含 OSS 寻址 + storage_env）。
+
+        独立性：不含任何 acr_*（user-data 域只用 OSS、不要求 ACR）、不含 cluster。
+        用于为 user-data 上下文单独构造 Store/Content；**不要**并入 Dataset/
+        artifact 的 profile——会污染其寻址。"""
+        ov = {"storage_env": self.storage_env,
+              "oss_bucket": self.oss_bucket,
+              "oss_prefix": self.oss_prefix}
+        if self.oss_endpoint:
+            ov["oss_endpoint"] = self.oss_endpoint
+        if self.oss_region:
+            ov["oss_region"] = self.oss_region
+        return ov
+
+
+def _parse_user_data_config(data: dict, *, storage_env: str) -> "UserDataConfig":
+    """校验并解析 scope=user-data 响应体（schema_version=1 契约，fail-closed）。
+
+    P2-③ 严格校验：schema_version 必须是**精确整数 1**（bool 是 int 子类须显式排除，
+    True==1 陷阱）；能力字段必须是真 bool（"false" 字符串不得被 truthy）；oss 必须
+    dict 且 bucket 非空；storage_env 缺失拒绝（不默默取调用方 env 变 dev）。
+    """
+    from ..errors import SchemaError
+    if not isinstance(data, dict):
+        raise SchemaError("unexpected user-data repo-config response shape")
+    v = data.get("schema_version")
+    if isinstance(v, bool) or not isinstance(v, int) or v != USER_DATA_SCHEMA_VERSION:
+        raise SchemaError(
+            f"unsupported user-data repo-config schema_version: {v!r} "
+            f"(supported: exact int {USER_DATA_SCHEMA_VERSION})")
+    prefix_root = str(data.get("prefix_root") or "")
+    if prefix_root != USER_DATA_PREFIX_ROOT:
+        raise SchemaError(
+            f"user-data prefix_root mismatch: {prefix_root!r} "
+            f"(expected {USER_DATA_PREFIX_ROOT!r}; server/SDK 常量须一致)")
+    for key in ("production_read_enabled", "production_write_enabled"):
+        flag = data.get(key)
+        if not isinstance(flag, bool):
+            raise SchemaError(
+                f"user-data {key} must be a boolean, got {flag!r}")
+    oss = data.get("oss")
+    if not isinstance(oss, dict) or not str(oss.get("bucket") or "").strip():
+        raise SchemaError(
+            "user-data repo-config oss must be an object with non-empty bucket "
+            f"(fail-closed), got {oss!r}")
+    env_raw = data.get("storage_env")
+    if not isinstance(env_raw, str) or not env_raw.strip():
+        raise SchemaError(
+            "user-data repo-config storage_env is required (missing/empty; "
+            "refusing to silently default)")
+    env = normalize_storage_env(env_raw)
+    return UserDataConfig(
+        schema_version=USER_DATA_SCHEMA_VERSION,
+        storage_env=env,
+        prefix_root=prefix_root,
+        production_read_enabled=data["production_read_enabled"],
+        production_write_enabled=data["production_write_enabled"],
+        oss_bucket=str(oss.get("bucket") or ""),
+        oss_prefix=str(oss.get("prefix") or ""),
+        oss_endpoint=str(oss.get("endpoint") or ""),
+        oss_region=str(oss.get("region") or ""),
+    )
+
+
+def fetch_user_data_config(transport, *, cluster: str = "", storage_env: str = "",
+                           allow_fallback: bool = False) -> "UserDataConfig":
+    """从 apiserver ``GET /apis/v1/repo-config?…&scope=user-data`` 拉取 user-data
+    独立配置（schema1：仅 OSS 寻址 + 生产读写能力声明，无密钥）。
+
+    * ``cluster`` / ``storage_env`` 二选一；**同时给出时两个键都下发服务端**
+      （P1-①：不得丢显式 env——服务端按 cluster 解析并做同语义冲突 400）。
+    * **客户端预检**：cluster→storage_env 映射表（真实形状 ``{"clusters": {name:
+      env}}`` 封套）与显式 env 冲突 → SchemaError（对齐 apiserver 400
+      cluster_env_conflict：不静默换环境）。映射请求 401/403/5xx 等故障**原样
+      抛出**（不得吞成"查不到"继续——那会在权限故障时静默跳过冲突检查）；
+      仅"200 但封套里无该 cluster"（新集群未配）才跳过预检交服务端兜底。
+    * **响应 env 核对**（P1-①）：scope 响应的 storage_env 与显式 env 不一致 →
+      SchemaError（防服务端映射变更后的静默换环境）。
+    * **旧服务兼容**（``allow_fallback=True``）：400 invalid scope 时回退一次
+      **无 scope 旧 repo-config（保留 cluster 与显式 env 双键）**；旧响应的
+      storage_env 与显式 env 也不一致 → SchemaError。能力字段恒 False。
+    * 认证(401)/权限(403)/5xx/404 等不当版本 fallback，原样抛出。
+    """
+    from ..errors import SchemaError
+    explicit_env = str(storage_env or "").strip()
+    resolved_env = ""
+    if cluster:
+        cluster = resolve_cluster(transport, cluster)
+        # 客户端预检：cluster→env 映射（真实封套 {"clusters": {name: env}}）。
+        # 请求失败（401/403/DB 故障等异常）原样抛——不得吞成兼容继续。
+        m = transport.get("/apis/v1/repo-config/cluster-storage-env-map")
+        if not isinstance(m, dict):
+            raise SchemaError("unexpected cluster-storage-env-map response shape")
+        entries = m.get("clusters") if isinstance(m.get("clusters"), dict) else m
+        if isinstance(entries, dict):
+            resolved_env = str(entries.get(cluster) or "").strip()
+        if resolved_env and explicit_env and explicit_env != resolved_env:
+            raise SchemaError(
+                f"cluster {cluster!r} maps to storage_env {resolved_env!r}; "
+                f"conflicts with storage_env {explicit_env!r}")
+        query = {"cluster": cluster, "scope": USER_DATA_SCOPE}
+        if explicit_env:
+            query["storage_env"] = explicit_env      # P1-①：双键一起下发
+    elif explicit_env:
+        query = {"storage_env": explicit_env, "scope": USER_DATA_SCOPE}
+    else:
+        raise SchemaError("fetch_user_data_config requires 'cluster' or 'storage_env'")
+    try:
+        data = transport.get("/apis/v1/repo-config?" + urlencode(query))
+    except Exception as exc:
+        status = getattr(exc, "status", None)
+        msg = str(getattr(exc, "message", "") or exc)
+        is_invalid_scope = (status == 400 and "invalid scope" in msg.lower())
+        if allow_fallback and is_invalid_scope:
+            # 旧服务不认识 scope：回退旧 repo-config（保留 cluster + 显式 env 双键）。
+            if cluster:
+                old_query = {"cluster": cluster}
+                if explicit_env:
+                    old_query["storage_env"] = explicit_env
+            elif explicit_env:
+                old_query = {"storage_env": explicit_env}
+            else:
+                raise SchemaError(
+                    "fallback requires cluster or storage_env") from exc
+            old = transport.get("/apis/v1/repo-config?" + urlencode(old_query))
+            if not isinstance(old, dict):
+                raise SchemaError(
+                    "unexpected legacy repo-config response shape") from exc
+            oss = old.get("oss")
+            if not isinstance(oss, dict) or not str(oss.get("bucket") or "").strip():
+                raise SchemaError(
+                    "legacy repo-config oss must be an object with "
+                    "non-empty bucket") from exc
+            env_raw = str(old.get("storage_env") or "").strip()
+            # P1-①：旧响应 env 与显式 env 不一致 → 拒绝（不静默换环境）。
+            if env_raw and explicit_env and env_raw != explicit_env:
+                raise SchemaError(
+                    f"legacy repo-config resolved storage_env {env_raw!r} "
+                    f"conflicts with explicit storage_env {explicit_env!r}")
+            env = normalize_storage_env(env_raw or explicit_env)
+            return UserDataConfig(
+                schema_version=USER_DATA_SCHEMA_VERSION,
+                storage_env=env,
+                production_read_enabled=False,   # 能力未知 → 关闭，不猜
+                production_write_enabled=False,
+                oss_bucket=str(oss.get("bucket") or ""),
+                oss_prefix=str(oss.get("prefix") or ""),
+                oss_endpoint=str(oss.get("endpoint") or ""),
+                oss_region=str(oss.get("region") or ""),
+            )
+        raise
+    cfg = _parse_user_data_config(data, storage_env=explicit_env)
+    # P1-①：响应 env 与显式 env 不一致 → 拒绝（不静默换环境）。
+    if explicit_env and cfg.storage_env and \
+            cfg.storage_env != normalize_storage_env(explicit_env):
+        raise SchemaError(
+            f"repo-config resolved storage_env {cfg.storage_env!r} conflicts "
+            f"with explicit storage_env {explicit_env!r}")
+    return cfg