openroboto-protocol 0.1.0__tar.gz → 0.2.0__tar.gz

{openroboto_protocol-0.1.0 → openroboto_protocol-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openroboto-protocol
-Version: 0.1.0
+Version: 0.2.0
 Summary: Shared protocol contract for the OpenRoboto subnet on Bittensor (netuid 80): seed derivation, commitment codec, model hashing, status vocabulary and API schemas.
 Keywords: bittensor,openroboto,subnet,protocol
 Author: OpenRoboto
@@ -31,9 +31,9 @@ Pin the exact version. A floating range means two sides of the subnet can resolv
 to different code, which is the failure this package was created to prevent.
 
 ```bash
-uv add "openroboto-protocol==0.1.0"
+uv add "openroboto-protocol==0.2.0"
 # or
-pip install "openroboto-protocol==0.1.0"
+pip install "openroboto-protocol==0.2.0"
 ```
 
 ```python
@@ -51,7 +51,7 @@ seed and decode a commitment; that must not cost a `pydantic-core` wheel build o
 GPU box. Only `schemas.py` needs pydantic, and only the backend needs `schemas.py`:
 
 ```bash
-uv add "openroboto-protocol[schemas]==0.1.0"   # backend only
+uv add "openroboto-protocol[schemas]==0.2.0"   # backend only
 ```
 
 ## Why this package exists
@@ -121,7 +121,7 @@ The version number *is* the contract version.
 | `minor` | New optional field. Old data missing the key **must** have a default |
 | `major` | Breaking change. Requires an on-chain data migration plan and review |
 
-Consumers pin an exact version (`openroboto-protocol==0.1.0`). Floating versions are
+Consumers pin an exact version (`openroboto-protocol==0.2.0`). Floating versions are
 rejected in CI, as is any vendored copy of this code.
 
 ## What consumers must add to their own CI

{openroboto_protocol-0.1.0 → openroboto_protocol-0.2.0}/README.md

@@ -9,9 +9,9 @@ Pin the exact version. A floating range means two sides of the subnet can resolv
 to different code, which is the failure this package was created to prevent.
 
 ```bash
-uv add "openroboto-protocol==0.1.0"
+uv add "openroboto-protocol==0.2.0"
 # or
-pip install "openroboto-protocol==0.1.0"
+pip install "openroboto-protocol==0.2.0"
 ```
 
 ```python
@@ -29,7 +29,7 @@ seed and decode a commitment; that must not cost a `pydantic-core` wheel build o
 GPU box. Only `schemas.py` needs pydantic, and only the backend needs `schemas.py`:
 
 ```bash
-uv add "openroboto-protocol[schemas]==0.1.0"   # backend only
+uv add "openroboto-protocol[schemas]==0.2.0"   # backend only
 ```
 
 ## Why this package exists
@@ -99,7 +99,7 @@ The version number *is* the contract version.
 | `minor` | New optional field. Old data missing the key **must** have a default |
 | `major` | Breaking change. Requires an on-chain data migration plan and review |
 
-Consumers pin an exact version (`openroboto-protocol==0.1.0`). Floating versions are
+Consumers pin an exact version (`openroboto-protocol==0.2.0`). Floating versions are
 rejected in CI, as is any vendored copy of this code.
 
 ## What consumers must add to their own CI

{openroboto_protocol-0.1.0 → openroboto_protocol-0.2.0}/pyproject.toml

@@ -1,11 +1,16 @@
 [project]
 name = "openroboto-protocol"
-# 1.0.0，不是 0.1.0。版本号**就是**契约版本（README「Versioning is a promise」），
-# 而消费方钉死的是精确版本：`openroboto-protocol==1.0.0`。0.x 在 SemVer 下不承诺
-# 任何兼容性，等于对着「两边装的是同一份」这个唯一卖点说「不保证」。
-# 改这个数之前先看 README 的 Release 一节：patch / minor / major 各自意味着什么，
-# major 需要一份链上数据迁移方案。
-version = "0.1.0"
+# 版本号**就是**契约版本（README「Versioning is a promise」），消费方钉死的是精确
+# 版本：`openroboto-protocol==0.2.0`。README 和 AGENTS.md 必须同步改 ——
+# `tests/test_version.py` 双向守着（钉版一致 + 0.x 必须写明「不承诺兼容」）。
+#
+# **停在 0.x 是裁决，不是拖延**：backend 和 cli 都还没钉上线版本，也还没真正
+# import 过这个包，冻结版本号只会冻住它碰巧长成的形状。1.0.0 的四条前置条件
+# 写在 AGENTS.md §1② 的可勾清单里。0.x 阶段不承诺兼容，所以像本轮
+# （0.1.0 → 0.2.0）这样收紧 schemas 的哨兵默认值是允许的。
+#
+# ⚠️ 0.1.0 已经发到 PyPI（2026-08-19，OIDC）。PyPI 版本号不可重用，只能往前发。
+version = "0.2.0"
 description = "Shared protocol contract for the OpenRoboto subnet on Bittensor (netuid 80): seed derivation, commitment codec, model hashing, status vocabulary and API schemas."
 readme = "README.md"
 license = "MIT"
@@ -24,8 +29,10 @@ requires-python = ">=3.11"
 dependencies = []
 
 classifiers = [
-    # 1.0.0 = 契约已冻结，与 "3 - Alpha" 直接矛盾。矿工在 PyPI 页面上看到的
-    # 就是这一行，它不能和版本号讲两个故事。
+    # ⚠️ 未裁决：这一行是按"1.0.0 = 契约已冻结"写的，而版本停在了 0.x 且
+    # README / AGENTS.md 明写「不承诺兼容」—— 矿工在 PyPI 页面上看到的就是这一行，
+    # 它和版本号今天讲的是两个故事。要么随 1.0.0 一起坐实，要么先降成
+    # "4 - Beta"。**不要顺手改**：这是矿工侧的产品判断，需要人来定。
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.11",

{openroboto_protocol-0.1.0 → openroboto_protocol-0.2.0}/src/openroboto_protocol/schemas.py

@@ -363,9 +363,18 @@ class MinerRef(Contract):
 class ModelRef(Contract):
     name: str
     hf_repo: str
-    #: 得分那次任务的 `hf_commit`（不变量 6）。查不到就留空串，
+    #: 得分那次任务的 `hf_commit`（不变量 6）。
     #: **禁止回落到该矿工的其它提交** —— 那是事故 C 的形状。
-    revision: str = ""
+    #:
+    #: ⚠️ **查不到是 `null`，不是空串。** 唯一来源是 40 位 `hf_commit`
+    #: （CLI `preflight.py` 强制校验后才上链），所以 `""` 从来不是一个合法的
+    #: revision，它只可能表示「后端没查到」。而 `""` 在 HuggingFace 的 URL 语义里
+    #: 是「用默认分支」—— 拿它去拼 `.../tree/{revision}` 会静默跳到 main，
+    #: 审计方核对的就不是得分那次的 commit 了。`null` 让「没有值」无处可藏。
+    #: `None` = 没钉 commit。**空串不行**：前端拼
+    #: `huggingface.co/{repo}/tree/{revision}` 时 `""` 会静默落到默认分支
+    #: （看起来正常、指向的却是另一份代码），`None` 至少是个响亮的 404。
+    revision: Annotated[str, Field(min_length=1)] | None = None
 
 
 class ScoreStat(Contract):
@@ -996,7 +1005,13 @@ class QueueStatusTask(Contract):
     hf_commit: str
     submitted_at: datetime | None = None
     #: SQL 里已经查了但线上没放进响应，契约要求补上。
-    round_num: int = 0
+    #:
+    #: ⚠️ **没有默认值，必填。** 队列里的每一条任务**必然属于某一轮** ——
+    #: 「不知道是哪一轮」不是一个合法状态，`round_num=0` 更不是：第 0 轮不存在，
+    #: 而 0 会被前端和矿工的 curl 当成一个真实轮次去过滤，静默捞回空列表。
+    #: 生产列是 `NOT NULL`、后端恒填、2026-08-19 副本 119 行里 0 条为 0 ——
+    #: 这个默认值一行都触发不到，留着只会让「忘了填」变得可表达。
+    round_num: int
     reason: Reason | None = None
     #: 进度条数据。契约卡里管它叫 "progress"，但 history 里同一份数据叫 `detail` ——
     #: 同一件事两个名字正是本文件要消灭的东西，统一叫 `detail`。
@@ -1034,9 +1049,11 @@ class SubmissionHistoryItem(Contract):
     - 删 `legacy_task_id` / `repo_hash` / `hotkey_tag` / `worker_id`：内部字段。
       `repo_hash` 是**抄袭判定的模型指纹**，公开它等于把判定依据交出去。
     - 删 `eval_detail`：`detail` 已经是它的解析版，两份重复占了响应体一大截。
-    - **永不返回 `status`**（迁移前的遗留列）：前端 `normalizeHistoryStatus()` 写的是
-      `submission.status || submission.eval_status || …`，**先读 `status`**，
-      而两列有 52 行不一致 —— 95 条里 33 条状态显示错误的根因。旧实现是在出口
+    - **永不返回 `status`**：前端 `normalizeHistoryStatus()` 写的是
+      `submission.status || submission.eval_status || …`，**先读 `status`** ——
+      同一个响应里出现两个状态键，先读到的恰好是没归一的那个，
+      95 条里 33 条状态显示错误就是这么来的（生产两个来源 2026-08-19 副本实测
+      80 行不一致）。这个响应只许有**一个**状态键。旧实现是在出口
       `row.pop("status", None)` 才躲过一劫；这里靠「模型里没有这个字段」保证，
       并由 `tests/test_schemas.py` 钉死。
 
@@ -1071,9 +1088,35 @@ class SubmissionHistoryItem(Contract):
     detail: dict[str, Any] | None = None
     #: 原样保留 —— 矿工文档教的就是读它。`reason` 是加法，不是替换。
     reject_reason: str = ""
-    seed: int = 0
-    drand_random: str = ""
-    drand_round: int = 0
+    #: 派种子的三件套。⚠️ **没派过种子是 `null`，不是 0 / 空串**，三个字段
+    #: 必须一起有或一起没有 —— 否则会发出 `{seed: null, drand_random: "",
+    #: drand_round: 0}` 这种一个字段说「没有」、隔壁说「有」的响应。
+    #:
+    #: 为什么 0 不行，`drand_round` 是最锋利的那条：drand 官方 API 的
+    #: `/public/0` 返回 **HTTP 200**，内容是**当天最新的那一轮**（`latest` 的别名，
+    #: 2026-08-19 实测）。审计方拿着我们发布的 `drand_round: 0` 照着查，
+    #: 不报错、不 404，会拿到一份今天的信标，然后 `verify_seed()` 必然 False ——
+    #: 而他无从判断是我们作弊还是数据缺失。本包的 `seed.drand_round_url()`
+    #: 已经对 `<= 0` 直接 `raise`，这里再把 0 当默认值发出去就是自相矛盾。
+    #:
+    #: `seed` 同理且更隐蔽：0 是 `derive_seed()` 的**合法输出**
+    #: （`int.from_bytes(sha256[-4:])`，概率 1/2³²），靠「0 一定是假的」区分不了。
+    #: 生产 2026-08-19 副本里 20 条 `seed=0` 全部是「没派过种子」，其中 11 条
+    #: 已经出分进过榜单 —— 它们的评测结果不可复现，而响应里看不出来。
+    #:
+    #: 🔴 **约束只加在能加的两个上，`seed` 故意没有。**
+    #: 去掉默认值只改变「字段被省略时给什么」，**并不拒绝显式传进来的 0** ——
+    #: 而真正把 0 发上线的是生产方（后端仓储层曾写 `seed=m.seed or 0`，
+    #: 主动把 NULL 抹成 0）。所以这里必须是**约束**不是默认值，否则这一整段
+    #: 注释描述的失败全都拦不住，只是看起来拦住了。
+    #:
+    #: `seed` 不能加 `gt=0`：0 是 `derive_seed()` 的**合法输出**
+    #: （`int.from_bytes(sha256[-4:])` 值域含 0，概率 1/2³²）。给它加约束等于
+    #: 有朝一日拒绝一个真实的种子，而那条提交会因此永远进不了榜 —— 比它想防的更贵。
+    #: `seed` 靠的是下面那条三元组校验：单独出现 0 而另外两个是 None，会被拒。
+    seed: int | None = None
+    drand_random: Annotated[str, Field(min_length=1)] | None = None
+    drand_round: Annotated[int, Field(gt=0)] | None = None
     #: ⚠️ 抄袭指纹。是否该继续公开待产品判断（spec 06 §7 Q5），
     #: 在裁决之前保持线上现状（返回），**不要顺手删也不要顺手加 `repo_hash`**。
     model_hash: str = ""
@@ -1085,6 +1128,42 @@ class SubmissionHistoryItem(Contract):
     updated_at: datetime | None = None
     reason: Reason | None = None
 
+    @model_validator(mode="after")
+    def _seed_triple_is_all_or_nothing(self) -> SubmissionHistoryItem:
+        """种子三元组必须**一起有或一起没有**。
+
+        这是 `seed` 唯一的守法 —— 它不能像 `drand_round` 那样加 `gt=0`
+        （0 是 `derive_seed()` 的合法输出），所以只能靠它和同伴的一致性来判。
+
+        挡的是这个形状：`{seed: 0, drand_round: null, drand_random: null}`。
+        单看 `seed` 分不出「种子真的是 0」和「没派过种子」，但配上另外两个就能分：
+        **真派过种子的那次，三个字段必然同时有值**（`derive_seed` 的输入就是
+        block_hash + round + drand_random，缺一个都算不出来）。
+
+        生产 2026-08-19 副本里 20 条 `seed=0` 全部是这个形状，其中 11 条已经出分
+        进过榜单 —— 它们的评测结果不可复现，而响应里看不出来。这条校验让那 11 条
+        在序列化那一刻就炸，而不是等审计方去查 drand 才发现。
+        """
+        present = [
+            self.seed is not None,
+            self.drand_random is not None,
+            self.drand_round is not None,
+        ]
+        if any(present) and not all(present):
+            missing = [
+                name
+                for name, ok in zip(
+                    ("seed", "drand_random", "drand_round"), present, strict=True
+                )
+                if not ok
+            ]
+            raise ValueError(
+                f"种子三元组不完整：缺 {missing}。"
+                "有值的那几个说「派过种子」、缺的那几个说「没派过」，"
+                "而 derive_seed 的输入三者缺一不可 —— 这条记录不可复现"
+            )
+        return self
+
 
 class SubmissionHistoryResponse(Contract):
     """`{success, submissions, total, limit, offset}`。
@@ -1129,7 +1208,10 @@ class EvalEnvironment(Contract):
     #: 要么从元数据取、要么删字段 —— 未裁决，保持现状不要再硬编码一次。
     sim: str = ""
     eval_commit: str = ""
-    seed: int = 0
+    #: ⚠️ 与 `SubmissionHistoryItem.seed` 同一件事：没派过种子是 `null` 不是 0。
+    #: 这个字段是审计方复现评测的输入，`0` 会被照着跑出一份不一样的结果而不报错。
+    #: 外层 `SubmissionDetail.environment` 本来就是 `| None`，内层跟上才自洽。
+    seed: int | None = None
 
 
 class SubmissionArtifacts(Contract):
@@ -1302,7 +1384,13 @@ class Baseline(Contract):
     model_name: str
     hf_repo: str
     score: ScoreStat
-    revision: str = ""
+    #: ⚠️ 与 `ModelRef.revision` 同一件事：基线模型从没人钉过 commit，
+    #: 那是「没有值」不是「空串这个值」。`""` 拼进 HF URL 会跳默认分支 ——
+    #: 基线换了模型，历史榜单会安静地指向新的权重。
+    #: `None` = 没钉 commit。**空串不行**：前端拼
+    #: `huggingface.co/{repo}/tree/{revision}` 时 `""` 会静默落到默认分支
+    #: （看起来正常、指向的却是另一份代码），`None` 至少是个响亮的 404。
+    revision: Annotated[str, Field(min_length=1)] | None = None
 
 
 class LeaderboardResponse(Contract):

{openroboto_protocol-0.1.0 → openroboto_protocol-0.2.0}/src/openroboto_protocol/status.py

@@ -9,12 +9,18 @@
 
 **两套词表不是一回事，混用是事故本身**：
 
-- **status**（`submissions.eval_status` 这一列）：提交走到哪一步。生命周期状态。
-- **stage**（`submissions.stage` 这一列）：worker 认领任务后在干什么。进度明细，
+- **status**：提交走到哪一步。生命周期状态，取值见 `ALL_STATUSES`。
+- **stage**：worker 认领任务后在干什么。进度明细，取值见 `ALL_STAGES`，
   只在 status 为 `evaluating` 期间有意义。
 
 `evaluating` 是 **status**；`running` 是 **stage**。它们描述的是同一段时间，
-但不是同一个字段，任何一边写成另一边的词都会被对方判为非法。
+但不是同一套词表，任何一边写成另一边的词都会被对方判为非法。
+
+⚠️ 这里说的是**词表**，不是承载它的字段名，更不是数据库列名。
+携带生命周期状态的响应字段**逐端点不同** —— `SubmissionRecord` 叫 `status`，
+其余四个模型叫 `eval_status`。哪个端点是哪个，以 `schemas.py` 的
+`STATUS_VALUED_FIELDS` 为准（那张表由 `tests/test_schemas.py` 逐条核对，
+不会和代码漂开）。**不要在这里记第二份。**
 
 **线上事实**（2026-08-17 curl `GET /api/v1/submissions/history?limit=500`，117 条）：
 
@@ -23,7 +29,10 @@
 - `stage` 出现过：`running` 61 / `""` 47 / `downloading` 8 / `prechecking` 1。
   **没有出现过 `evaluating`** —— 对外的规范阶段词是 `running`，这条是裁决依据。
 
-**这个模块不负责**：状态怎么持久化、谁有权改状态、超时怎么判。那些是后端的事。
+**这个模块不负责**：状态怎么持久化（存哪张表哪一列、哪一列是权威）、谁有权改状态、
+超时怎么判。那些是后端的事 —— 而且权威列在数据迁移前后是**相反**的
+（迁移前 `eval_status`，迁移后 `status`），写进这个包等于让一个不可回收的版本号
+去承诺一件别的仓库随时会改的事。
 """
 
 from __future__ import annotations
@@ -34,7 +43,7 @@ from types import MappingProxyType
 from typing import Final
 
 # ─────────────────────────────────────────────────────────────────────────────
-# 提交状态（submissions.eval_status）
+# 提交状态（生命周期）
 # ─────────────────────────────────────────────────────────────────────────────
 
 # 扫链刚看到这条 commitment，还没做任何校验。建行时的默认值（schema.py 的 DEFAULT）。
@@ -103,7 +112,8 @@ FROZEN_STATUSES: Final[frozenset[str]] = frozenset({STATUS_REJECTED, STATUS_SUPE
 #                                            （CASE WHEN eval_status='pending'，单向）
 #   pending       → evaluated / eval_failed  历史真实路径：修复前 update_task_progress
 #                                            只写 stage 不推状态，全库 0 条 evaluating，
-#                                            65 条 evaluated 全部是从 pending 直接落的。
+#                                            几十条 evaluated 全部是从 pending 直接落的
+#                                            （2026-08-19 副本：evaluated 66 条）。
 #                                            **删掉这条边等于宣布线上历史非法。**
 #   pending       → superseded               submission_db.py:supersede_pending —— 它的
 #                                            WHERE 只有一条 eval_status='pending'
@@ -168,7 +178,7 @@ def can_transition(current: str, new: str) -> bool:
 
 
 # ─────────────────────────────────────────────────────────────────────────────
-# 评测阶段（submissions.stage）
+# 评测阶段（进度明细）
 # ─────────────────────────────────────────────────────────────────────────────
 
 
@@ -182,10 +192,16 @@ class Stage:
     """
 
     #: 对外的规范词。worker 该发这个，API 该返回这个，前端该按这个渲染。
-    #: 生产 `GET /api/v1/submissions/history` 返回的就是这一列（2026-08-17 实测）。
+    #: 生产 `GET /api/v1/submissions/history` 的 `stage` 字段返回的就是这个词
+    #: （2026-08-17 实测）。
     wire: str
-    #: 库里的历史存储值（带 `benchmark_` 前缀）。出口翻译前的样子，读老数据时会遇到；
-    #: **不要**把它吐给前端 —— 前端的 ACTIVE_STAGES 里没有带前缀的写法，认不出就不渲染。
+    #: 历史存储值（带 `benchmark_` 前缀）。出口翻译前的样子，读老数据时会遇到。
+    #: ⚠️ **两种写法是并存的**，不是「老数据全带前缀」：2026-08-19 的生产副本里
+    #: `running` 38 行、`benchmark_running` 24 行、`downloading` 8 行（裸）、
+    #: `benchmark_prechecking` 2 行（带前缀）。所以入口必须两种都收 —— 这正是
+    #: `_STAGE_LOOKUP` 把 wire / stored / aliases 三者并列的理由。
+    #: **不要**把带前缀的吐给前端 —— 前端的 ACTIVE_STAGES 里没有带前缀的写法，
+    #: 认不出就不渲染。
     stored: str
     #: 输入侧还接受的同义词。收下它们纯粹是加法：按公开文档或前端类型写的调用方
     #: 曾经因此收到 400（2026-08-14 实际发生）。
@@ -236,12 +252,15 @@ def normalize_stage(word: str) -> str | None:
 
 #: 老状态词 → 现行状态词。
 #:
-#: 生产库里这些值还在：`submissions` 有一列迁移前的遗留 `status`，与 `eval_status`
-#: 有 52 行不一致（`status='done'` 而 `eval_status='superseded'` 有 22 行）。
-#: 前端读的是 `submission.status || submission.eval_status`，先读到的是错的那个 ——
-#: 2026-08-14 队列页 95 条里 33 条状态显示错误，根因就是这两套词混在同一个响应里。
+#: 这些词今天还活在生产数据里（2026-08-19 副本实测：`done` 37 / `failed` 4 /
+#: `confirmed` 1 / `enqueued` 17），它们是同一件事在词表统一之前的四套写法。
+#:
+#: 出事的形状不是「有老词」，而是**两套词混进同一个响应**：前端按
+#: `submission.status || submission.eval_status` 读，先读到的恰好是没归一的那个 ——
+#: 2026-08-14 队列页 95 条里 33 条状态显示错误。所以归一必须发生在**一个**地方。
 #:
-#: **真相只有 eval_status 一个。** 这张表只用于读老数据，不要用它生成新值。
+#: **`ALL_STATUSES` 是唯一真源。** 这张表只用于读老数据，不要用它生成新值。
+#: 老词今天具体存在哪个存储位置、归一到哪一步为止，是后端的事，不在本模块的承诺范围内。
 LEGACY_STATUS_ALIASES: Final[Mapping[str, str]] = MappingProxyType(
     {
         "enqueued": STATUS_PENDING,