docs: record STEP-079 V4 fixture API blocker

docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v1.md

@@ -0,0 +1,41 @@
+# STEP-079 — 真实 QBIN Golden Fixture 接入 RN Test Host v1
+
+状态：阻塞
+
+日期：2026-09-13
+
+## 目标
+
+把 WeatherV2 冻结的 QBIN V2 Golden Fixture 通过 STEP-078 的 V4 public API 接入 `MapLibreParticleRNTestHost`；本 Step 不执行 Android Gradle、APK、安装或 ADB。
+
+## 起始基线
+
+- `HEAD`：`2ea8f03064b2379d5220ce67806e3543e9cba0a7`
+- `origin/particle/main`：`2ea8f03064b2379d5220ce67806e3543e9cba0a7`
+- 开始前存在 STEP-062 dirty、历史 untracked、`.codex-build-logs/`、Test Host generated Android/Expo/modules 与 package tgz；均未清理、暂存或提交。
+
+## 已完成的只读核对
+
+- [x] 核对冻结来源 `/root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/`、说明、原始 manifest、profile/semantic/unit registry。
+- [x] 核对 8 个 raw `.qbin` 的目标（Wind/Wave/Current/Rain，各 T0/T1）及 descriptor：Wind/Current U/V 都是 `VELOCITY_COMPONENT`，semantic `1/2`、group `1`、unit `1`。
+- [x] 核对 STEP-078 V4 TypeScript、TurboModule/Kotlin bridge 与 Core ColorBinding resolver。
+- [x] 确认不存在可在不改变冻结 public API 语义的前提下为 Wind/Current 提交正确 ColorBinding 的路径。
+
+## 阻塞
+
+Wind/Current 的任务合同要求选择 U 或 V 做 ColorBinding；其正确 `expectedValueClass` 是 `VELOCITY_COMPONENT`。然而冻结的 RN public API 在 `FieldRuntime.setEncodedColorBinding` 只接受 `SCALAR` 或 `DIRECTION_ANGLE`，Kotlin bridge 同样只映射这两者。将 U/V 伪装为 `SCALAR` 虽能通过 JS/Kotlin 参数白名单，但 Core resolver 会以 `PlaneClassMismatch` 拒绝真实 velocity plane。
+
+因此无法同时满足“所有 dataset 至少有 ColorBinding”“所有 binding 仅通过冻结 V4 public API”“不得改变 STEP-078 public API 语义”。按任务的接口阻塞条款，未创建 Test Host wrapper、未修改 package/Core/Renderer，也未保留半成品 fixture 复制。
+
+完整证据与解阻条件见 `docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md`。
+
+## 构建与验证
+
+- 未执行 TypeScript/codegen/C++ build 或测试：在实现开始前已得到不可绕过的 public-API 合同矛盾，继续执行不会验证一个可交付实现。
+- 未执行 Android Gradle、APK、install、ADB、模拟器、实体机或 iOS/Metal 操作。
+- `git diff --check`：待本 Step 的文档收尾后执行。
+
+## 允许/禁止范围结果
+
+- 未修改 Renderer/GPU/shader、Core/QBIN/Binding/Host API、Android bridge、RN package public API、NavSea、网络、下载或 gzip。
+- 未进入下一 Step；等待具备明确授权的 STEP-078 API 补充/修订后重新开始本 Step。

docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md

@@ -0,0 +1,35 @@
+# STEP-079 真实 QBIN Golden Fixture 接入 RN Test Host 接口阻塞报告 v1
+
+状态：阻塞（未实现，未执行 Android 验收）
+
+## 结论
+
+STEP-078 的冻结 V4 RN public API 无法表达真实 Wind/Current U 或 V plane 的正确 ColorBinding。因此本 Step 依照任务的停止条款退出，没有以 Test Host wrapper、错误 enum 或 Core/API 修改绕过。
+
+## 可复核证据
+
+冻结 WeatherV2 fixture manifest/profile registry 规定：
+
+| 数据集 | 要提交的 Color plane | fixture descriptor |
+| --- | --- | --- |
+| Wind `wind/1` | U 或 V | semantic `1`/`2`，group `1`，unit `1`，`VELOCITY_COMPONENT` |
+| Current `current/1` | U 或 V | semantic `1`/`2`，group `1`，unit `1`，`VELOCITY_COMPONENT` |
+
+冻结 RN API `packages/maplibre-particle-rn/src/FieldRuntime.ts` 的 `setEncodedColorBinding` 只接受 `SCALAR`、`DIRECTION_ANGLE`；Android `WeatherRuntimeBridgeModule.kt` 也只将这两个字符串映射为 native value class。它没有 `VELOCITY_COMPONENT` 的 public enum 通路。
+
+Core 并非可以安全忽略该差异：`src/mbgl/particle/field/field_binding.cpp` 会对 ColorBinding 的 selected T0/T1 plane 验证 value class。以 `SCALAR` 提交真实 U/V 必返回 `PlaneClassMismatch`。把 value class 伪造为 scalar 既不是 fixture-derived binding，也不会形成有效 V4 bridge 验证。
+
+Wave（scalar Height）与 Rain（scalar precipitation）没有此问题；Wave 的 DirectionAngle particle binding 与 Wind/Current 的 VectorComponents particle binding 也均有冻结 public API 表达。但任务要求同一 Test Host V4 dataset contract 至少包含 ColorBinding，且固定规则特别允许 Wind/Current U/V 的 ColorBinding；缺少该 enum 使四组完整合同无法成立。
+
+## 未执行的内容
+
+- 未保留或提交 8 个 copied raw QBIN fixture，避免仓库出现无法被完整 Test Host contract 使用的半成品。
+- 未创建 V4 dataset/materialize/UI；未修改 V3 UI 或 Test Host Metro。
+- 未运行 TypeScript、TurboModule codegen、C++ rebuild/回归、Android Gradle/APK/ADB，因没有可验证的合规实现。
+- 未创建 commit、未 push；`particle/main` 仍指向起始基线，除本阻塞文档收尾外没有 task implementation。
+
+## 最小解阻条件
+
+需要新的、显式授权的 API 修订 Step：令 `EncodedColorBindingInput.expectedValueClass`、RN validation、TurboModule spec、Kotlin enum mapping 以同一冻结 ABI 支持 `VELOCITY_COMPONENT`，并增加相应的 Core/bridge contract tests。该 Step 必须单独决定 Renderer 是否仅 bridge-only；本报告不建议把 vector magnitude 伪造为 color input，也不建议在 Test Host 绕过 public API。
+
+在该修订完成且稳定后，应重新从本任务指定 fixture source materialize 8 个 `.qbin`，进行完整 source/size/SHA-256 审计，并执行本任务要求的 Linux static validation。Windows 11 Android 验收目前没有可交付的 V4 Test Host，因此不能提供安装/ADB 验收步骤或宣称 Android PASS。

粒子开发记录.md

@@ -786,3 +786,9 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2`
 - fieldKey、runtime fieldID、profileID 统一按 UTF-8 byte length 1..64 验证：RN `TextEncoder`、Kotlin `toByteArray(Charsets.UTF_8)`、Java `StandardCharsets.UTF_8`。多字节 33 CJK（99 bytes）输入在 RN/Java guard tests 中拒绝。
 - `particle-codex` 内所有限流验证均 PASS：package tsc、TS directed test、TurboModule schema、JDK-only Java guard、Linux runner rebuild、V4/V3 指定 filter、JNI name-set 与 `git diff --check`。Android Gradle/APK/ADB/JNI 真实编译、设备、Jest、iOS/Metal 仍未运行；未改 Renderer/GPU/shader/Test Host/NavSea，不进入 STEP-079。
 - 实现 scoped commit `75a974e77503c56ec5bd2823ac1b689225ed80a7`（`fix: close STEP-078 V4 bridge guard audit`）已成功 push：`73779b89b..75a974e77 particle/main -> particle/main`；仅文档 Git 收尾 commit 随后推送并停止。
+
+### 2026-09-13 STEP-079 真实 QBIN Golden Fixture RN Test Host 接入阻塞
+
+- 在复制/接入前核对冻结 fixture contract 与 STEP-078 V4 public API：Wind/Current U/V 是 `VELOCITY_COMPONENT`（semantic 1/2、group 1、MPS），而 `setEncodedColorBinding` 的 RN/Android public contract 仅允许 `SCALAR` 或 `DIRECTION_ANGLE`。
+- 用 scalar 伪装 U/V 会被 Core ColorBinding resolver 以 `PlaneClassMismatch` fail-closed；扩 public enum 则改变 STEP-078 冻结 public API。本 Step 未堆叠 Test Host wrapper、未改 Core/Renderer/bridge，也未保留半成品 fixture。
+- 已按任务的接口阻塞停止条款生成 STEP/阻塞报告；未运行 TypeScript/codegen/C++/Android 验证，等待独立 API 修订 Step。