双境锁印，三版启航 · Prepare 0.3.0 release

.github/workflows/npm-release.yml

@@ -6,7 +6,7 @@ on:
       version:
         description: Lockstep version for all six packages
         required: true
-        default: 0.2.1
+        default: 0.3.0
         type: string
       publish_to_registry:
         description: Publish the fully gated candidate to npm after preflight
@@ -44,6 +44,9 @@ jobs:
             test -f contracts/tiled-platform-baselines.json
             test -f contracts/apple-provider-baselines.json
           fi
+          python tools/webgpu/review_reports.py \
+            --reports-root reports/webgpu-qualification \
+            --output "$RUNNER_TEMP/webgpu-release-evidence.json"
 
   build-native:
     needs: validate
@@ -55,15 +58,19 @@ jobs:
           - id: macos-arm64
             runner: macos-15
             executable_suffix: ""
+            runtime_flavor: cpu
           - id: macos-x64
             runner: macos-15-intel
             executable_suffix: ""
+            runtime_flavor: cpu
           - id: linux-x64
             runner: ubuntu-24.04
             executable_suffix: ""
+            runtime_flavor: webgpu
           - id: windows-x64
             runner: windows-2022
             executable_suffix: ".exe"
+            runtime_flavor: webgpu
     runs-on: ${{ matrix.runner }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
@@ -82,6 +89,16 @@ jobs:
           python tools/bootstrap_dependencies.py --cache-dir .cache/dependencies --offline
           python tools/bootstrap_models.py --cache-dir .cache/models
           python tools/package_model_bundle.py
+      - name: Assemble and revalidate the production WebGPU SDK
+        if: matrix.runtime_flavor == 'webgpu'
+        shell: bash
+        run: |
+          python tools/webgpu/build_runtime.py \
+            --platform "${{ matrix.id }}" \
+            --package-cache .cache/webgpu-packages \
+            --output-dir "dist/webgpu-sdk/${{ matrix.id }}"
+          python tools/webgpu/build_runtime.py \
+            --validate-sdk "dist/webgpu-sdk/${{ matrix.id }}"
       - name: Install verified Node development files (Unix)
         if: runner.os != 'Windows'
         shell: bash
@@ -116,6 +133,8 @@ jobs:
           cmake -S . -B build-npm -G Ninja
           -DCMAKE_BUILD_TYPE=Release
           -DLIGHT_OCR_DEPENDENCY_CACHE_DIR="$PWD/.cache/dependencies"
+          -DLIGHT_OCR_ONNXRUNTIME_FLAVOR=${{ matrix.runtime_flavor }}
+          -DLIGHT_OCR_WEBGPU_SDK_DIR="$PWD/dist/webgpu-sdk/${{ matrix.id }}"
           -DLIGHT_OCR_BUILD_NODE=ON
           -DLIGHT_OCR_BUILD_TESTS=ON
           -DLIGHT_OCR_BUILD_TOOLS=ON
@@ -129,6 +148,8 @@ jobs:
         run: >-
           cmake -S . -B build-npm -G "Visual Studio 17 2022" -A x64
           "-DLIGHT_OCR_DEPENDENCY_CACHE_DIR=$env:GITHUB_WORKSPACE/.cache/dependencies"
+          -DLIGHT_OCR_ONNXRUNTIME_FLAVOR=${{ matrix.runtime_flavor }}
+          "-DLIGHT_OCR_WEBGPU_SDK_DIR=$env:GITHUB_WORKSPACE/dist/webgpu-sdk/${{ matrix.id }}"
           -DLIGHT_OCR_BUILD_NODE=ON
           -DLIGHT_OCR_BUILD_TESTS=ON
           -DLIGHT_OCR_BUILD_TOOLS=ON
@@ -167,7 +188,10 @@ jobs:
             --build-dir build-npm \
             --configuration Release \
             --metadata-dir "reports/npm/${{ matrix.id }}" \
-            --output-dir "dist/native-input/${{ matrix.id }}"
+            --output-dir "dist/native-input/${{ matrix.id }}" \
+            --runtime-flavor "${{ matrix.runtime_flavor }}" \
+            --webgpu-artifact-manifest \
+              "dist/webgpu-sdk/${{ matrix.id }}/artifact-manifest.json"
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: native-${{ matrix.id }}

.github/workflows/webgpu-native.yml

@@ -86,6 +86,22 @@ jobs:
             --offline \
             --package-cache .cache/webgpu-packages \
             --output-dir "dist/webgpu-sdk-offline/${{ matrix.id }}"
+      - name: Resolve the locked WebGPU build mode
+        shell: bash
+        run: |
+          qualification_status="$(python -c 'import json; print(json.load(open("tools/webgpu/runtime-lock.json", encoding="utf-8"))["qualification"]["status"])')"
+          case "$qualification_status" in
+            development-pending-device-validation)
+              echo "WEBGPU_QUALIFICATION_BUILD=ON" >> "$GITHUB_ENV"
+              ;;
+            production-qualified)
+              echo "WEBGPU_QUALIFICATION_BUILD=OFF" >> "$GITHUB_ENV"
+              ;;
+            *)
+              echo "Unsupported WebGPU qualification status: $qualification_status" >&2
+              exit 1
+              ;;
+          esac
       - name: Install Node development files (Linux)
         if: runner.os != 'Windows'
         shell: bash
@@ -110,7 +126,7 @@ jobs:
           }
           "NODE_INCLUDE_DIR=$headers" | Out-File -FilePath $env:GITHUB_ENV -Append
           "NODE_LIBRARY=$($library.FullName)" | Out-File -FilePath $env:GITHUB_ENV -Append
-      - name: Configure WebGPU qualification build (Linux)
+      - name: Configure WebGPU contract build (Linux)
         if: runner.os != 'Windows'
         shell: bash
         run: >-
@@ -119,21 +135,21 @@ jobs:
           -DLIGHT_OCR_DEPENDENCY_CACHE_DIR="$PWD/.cache/dependencies"
           -DLIGHT_OCR_ONNXRUNTIME_FLAVOR=webgpu
           -DLIGHT_OCR_WEBGPU_SDK_DIR="$PWD/dist/webgpu-sdk/${{ matrix.id }}"
-          -DLIGHT_OCR_WEBGPU_QUALIFICATION_BUILD=ON
+          -DLIGHT_OCR_WEBGPU_QUALIFICATION_BUILD="$WEBGPU_QUALIFICATION_BUILD"
           -DLIGHT_OCR_BUILD_NODE=ON
           -DLIGHT_OCR_BUILD_TESTS=ON
           -DLIGHT_OCR_BUILD_TOOLS=ON
           -DLIGHT_OCR_NODE_INCLUDE_DIR="$NODE_INCLUDE_DIR"
           -DLIGHT_OCR_NODE_EXECUTABLE="$(command -v node)"
-      - name: Configure WebGPU qualification build (Windows)
+      - name: Configure WebGPU contract build (Windows)
         if: runner.os == 'Windows'
         shell: pwsh
         run: >-
           cmake -S . -B build-webgpu -G "Visual Studio 17 2022" -A x64
           "-DLIGHT_OCR_DEPENDENCY_CACHE_DIR=$env:GITHUB_WORKSPACE/.cache/dependencies"
           -DLIGHT_OCR_ONNXRUNTIME_FLAVOR=webgpu
           "-DLIGHT_OCR_WEBGPU_SDK_DIR=$env:GITHUB_WORKSPACE/dist/webgpu-sdk/${{ matrix.id }}"
-          -DLIGHT_OCR_WEBGPU_QUALIFICATION_BUILD=ON
+          "-DLIGHT_OCR_WEBGPU_QUALIFICATION_BUILD=$env:WEBGPU_QUALIFICATION_BUILD"
           -DLIGHT_OCR_BUILD_NODE=ON
           -DLIGHT_OCR_BUILD_TESTS=ON
           -DLIGHT_OCR_BUILD_TOOLS=ON
@@ -162,6 +178,10 @@ jobs:
             --configuration Release \
             --platform-id "${{ matrix.id }}" \
             --output-dir "reports/webgpu/${{ matrix.id }}"
+          qualification_args=()
+          if [[ "$WEBGPU_QUALIFICATION_BUILD" == "ON" ]]; then
+            qualification_args+=(--qualification-build)
+          fi
           python tools/npm_release.py stage-native \
             --platform-id "${{ matrix.id }}" \
             --build-dir build-webgpu \
@@ -170,7 +190,7 @@ jobs:
             --output-dir "dist/webgpu-native/${{ matrix.id }}" \
             --runtime-flavor webgpu \
             --webgpu-artifact-manifest "dist/webgpu-sdk/${{ matrix.id }}/artifact-manifest.json" \
-            --qualification-build
+            "${qualification_args[@]}"
           LIGHT_OCR_NODE_BINARY="$PWD/dist/webgpu-native/${{ matrix.id }}/native/light_ocr_node.node" \
           LIGHT_OCR_RUNTIME_DESCRIPTOR="$PWD/dist/webgpu-native/${{ matrix.id }}/native/runtime-descriptor.json" \
           node -e "const x=require('./bindings/node/js/load-native.cjs').loadNative(); console.log(JSON.stringify(x.runtimePolicy))"

CHANGELOG.md

@@ -49,7 +49,7 @@ This file records user-visible changes to `light-ocr`. Published artifact detail
 - Heavy model conversion, Compute Plan placement, performance, cache, and lifecycle qualification remain local real-device work. Ordinary CI stays limited to cross-platform builds, contracts, and lightweight tests and does not require paid runners.
 - The Core ML provider is merged on `main` but is not included in the published `0.2.0` npm packages. The planned `0.3.0` distribution keeps the existing six-package installation shape.
 - Native WebGPU compatibility and performance are evidenced on the named NVIDIA/Linux and AMD/Windows systems. Other devices may use the open compatibility path but do not inherit these performance numbers.
-- The Linux and Windows qualification reports both passed 164/164 mechanical Gates. Production release staging remains closed until the reviewed report and artifact hashes are bound into the runtime lock.
+- The Linux and Windows qualification reports both passed 164/164 mechanical Gates. Their reviewed report and artifact-set hashes are bound into the production runtime lock, so ordinary `0.3.0` release staging now accepts the exact qualified payloads.
 
 Full evidence and methodology: [Apple device acceleration](docs/apple-device-acceleration.md), [Linux device acceleration](docs/linux-device-acceleration.md), [Windows device acceleration](docs/windows-device-acceleration.md), [implementation status](docs/implementation-status.md), the accepted Apple baseline [`apple-fp16-mixed-20260715.2`](contracts/apple-provider-baselines.json), and the checked-in WebGPU qualification reports.
 

README.md

@@ -229,7 +229,7 @@ The npm distribution installs one facade, one required model package, and the na
 
 Direct Core ML acceleration is merged on `main` for the `0.3.0` candidate but is not part of the published `0.2.0` package set. Its release keeps the same six-package installation shape; no extra provider package or runtime download is planned.
 
-PR #11 also carries the Linux x64 and Windows x64 Native WebGPU source candidate. Explicit WebGPU accepts `auto`/`fp32`; Auto also selects FP32. The three required CPU-partition operators are reported and bounded. Both real-device reports passed 164/164 Gates; release packaging remains gated until their immutable hashes are bound into the production lock. Published `0.2.0` packages remain unchanged and CPU-only on those platforms.
+PR #11 also carries the Linux x64 and Windows x64 Native WebGPU source candidate. Explicit WebGPU accepts `auto`/`fp32`; Auto also selects FP32. The three required CPU-partition operators are reported and bounded. Both real-device reports passed 164/164 Gates, and their immutable report/artifact hashes are now bound into the production lock for the `0.3.0` release workflow. Published `0.2.0` packages remain unchanged and CPU-only on those platforms.
 
 ## Project status
 

README.zh-CN.md

@@ -229,7 +229,7 @@ npm 分发会安装一个统一入口、一个必需的模型包，以及与当
 
 Direct Core ML 加速已经合并到 `main`，目标版本为 `0.3.0`，但尚未进入已发布的 `0.2.0` package set。它会继续复用现有六包安装结构，不计划新增 provider package 或运行时下载。
 
-PR #11 同时包含 Linux x64 与 Windows x64 Native WebGPU 源码候选。显式 WebGPU 接受 `auto/fp32`，Auto 同样选择 FP32；三个必要 CPU partition 算子会被显式报告并限制范围。两份真机报告均已通过 164/164 Gate，release package 仍需先把报告与产物的不可变哈希绑定进 production lock。已发布的 `0.2.0` packages 保持不变，并在这两个平台继续仅使用 CPU。
+PR #11 同时包含 Linux x64 与 Windows x64 Native WebGPU 源码候选。显式 WebGPU 接受 `auto/fp32`，Auto 同样选择 FP32；三个必要 CPU partition 算子会被显式报告并限制范围。两份真机报告均已通过 164/164 Gate，其报告与产物的不可变哈希现已绑定进 production lock，供 `0.3.0` 发布流程使用。已发布的 `0.2.0` packages 保持不变，并在这两个平台继续仅使用 CPU。
 
 ## 项目状态
 

cmake/WebGpuRuntime.cmake

@@ -227,12 +227,21 @@ function(light_ocr_configure_webgpu_runtime)
       qualification qualificationReportSha256 windows-x64)
     string(JSON _qualified_sha GET "${_json}"
       qualification qualifiedArtifactSetSha256 ${_platform})
+    set(_qualification_hashes_valid TRUE)
+    foreach(_qualification_hash IN ITEMS
+        _linux_qualified_sha
+        _windows_qualified_sha
+        _linux_report_sha
+        _windows_report_sha)
+      string(LENGTH "${${_qualification_hash}}" _qualification_hash_length)
+      if(NOT _qualification_hash_length EQUAL 64 OR
+         NOT "${${_qualification_hash}}" MATCHES "^[0-9a-f]+$")
+        set(_qualification_hashes_valid FALSE)
+      endif()
+    endforeach()
     if(NOT _qualification_status STREQUAL "production-qualified" OR
        NOT _provider_gate OR NOT _artifact_qualified OR
-       NOT _linux_qualified_sha MATCHES "^[0-9a-f]{64}$" OR
-       NOT _windows_qualified_sha MATCHES "^[0-9a-f]{64}$" OR
-       NOT _linux_report_sha MATCHES "^[0-9a-f]{64}$" OR
-       NOT _windows_report_sha MATCHES "^[0-9a-f]{64}$" OR
+       NOT _qualification_hashes_valid OR
        NOT _qualified_sha STREQUAL _artifact_set_sha)
       message(FATAL_ERROR
         "WebGPU release SDK requires accepted Linux and Windows Provider Gates bound to this artifact set")

docs/build-and-release.md

@@ -118,7 +118,7 @@ cmake -S . -B build-webgpu -G Ninja \
   -DLIGHT_OCR_WEBGPU_QUALIFICATION_BUILD=ON
 ```
 
-pending lock 只能用于 qualification build；普通 release configure 要求双平台 Provider Gate 已接受，且 lock 中本平台 `qualifiedArtifactSetSha256` 与 SDK 完全一致。真实 Linux/Windows GPU 的完整构建、npm staging、14-fixture placement/质量/性能/生命周期和报告回收统一执行：
+pending lock 只能用于 qualification build；当前 production lock 已接受双平台 Provider Gate，普通 release configure 要求 lock 中本平台 `qualifiedArtifactSetSha256` 与 SDK 完全一致。真实 Linux/Windows GPU 的完整构建、npm staging、14-fixture placement/质量/性能/生命周期和报告回收统一执行：
 
 ```bash
 python3 tools/webgpu/qualify.py
@@ -226,11 +226,11 @@ macOS arm64 高分辨率绝对 RSS gates 由 `light_ocr_memory_gate` 独立进
 - 六个 tarball 先发布到一次性 Verdaccio registry，只安装 facade 后停止 registry，再执行真实 bounded 与 tiled OCR，证明没有运行时下载依赖。
 - 只有以上功能/制品 gates、需要时已经单独完成的受审 baseline，以及 `publish_to_registry=true` 同时满足时，`npm-release` GitHub environment 才能读取 `NPM_TOKEN`；先发布五个依赖到 `next`，通过 registry facade 安装后再发布主包，最终禁网运行并可显式提升到 `latest`。
 
-首个版本的触发命令为：
+`0.3.0` 发布前 dry-run 的触发命令为：
 
 ```bash
 gh workflow run "npm release" --ref main \
-  -f version=0.2.0 \
+  -f version=0.3.0 \
   -f publish_to_registry=false \
   -f promote_latest=false
 ```

docs/implementation-status.md

@@ -1,7 +1,7 @@
 # C++ Core 与 Node-API 实施状态
 
 更新时间：2026-07-19<br>
-结论：`@arcships/light-ocr@0.2.0` 已发布并提升为 npm `latest`。当前 0.3.0 源码候选已实现 Direct Core ML Apple provider，以及 Linux x64 glibc/Windows x64 official Native WebGPU Plugin EP 的产品 runtime、D112 Auto、自包含 npm payload 与资格工具。Apple M4 已有审阅证据；WebGPU 的 Linux/Windows 真实设备报告均为 164/164 Gate 通过，production lock 仍需在发布前绑定已审阅报告和产物哈希。
+结论：`@arcships/light-ocr@0.2.0` 已发布并提升为 npm `latest`。当前 0.3.0 发布候选已实现 Direct Core ML Apple provider，以及 Linux x64 glibc/Windows x64 official Native WebGPU Plugin EP 的产品 runtime、D112 Auto、自包含 npm payload 与资格工具。Apple M4 已有审阅证据；WebGPU 的 Linux/Windows 真实设备报告均为 164/164 Gate 通过，已审阅报告和产物哈希已绑定 production lock。
 
 状态含义：
 
@@ -26,7 +26,7 @@
 | manifest、hash、licenses、SBOM、parity、benchmark | Done | Release commit 已重新生成并保存四平台 metadata、六个 npm tarballs 的 hashes/integrity、parity、quality 与 benchmark 证据。 |
 | N-API/npm 非本 Core milestone | Done / `0.2.0` published | raw Node-API v8、CJS/ESM、`.d.ts`、内置模型解析、四平台 prebuild、双重背压、AbortSignal 与生命周期均已完成；[npm release run 29340467784](https://github.com/arcships/light-ocr/actions/runs/29340467784) 与 [promotion run 29342178842](https://github.com/arcships/light-ocr/actions/runs/29342178842) 保存六包发布、registry 和禁网证据。 |
 | Perf-1A / Apple execution | Done locally / open macOS | provider-neutral `InferenceSession` 已加入 Objective-C++ Direct Core ML；公开 union 与 D112 Auto 创建状态机已接线。detector 使用 FP16 range model，recognizer 使用 91-function FP16 MLProgram 和 20 个加权宽度桶；Apple Silicon interactive 为 ANE + 宽文本 GPU，strict 为 GPU，Intel 为 CPU+GPU。schema 1.1 provider contract 使用 `open-macos`、arm64/x86_64、`validatedDeviceFamilies` 和 `deviceValidated`；显式 provider 严格失败，只有 Auto 可按 typed reason 在创建期继续。哈希锁模型、离线编译缓存、跨进程锁、LRU≤20 与 Node 映射均已完成。M4 有正式证据，其他 Mac 直接开放实验兼容。 |
-| Perf-2 / Native WebGPU | Implemented / two device Gates passed | Linux x64 glibc/Vulkan 与 Windows x64/D3D12 使用 official ORT Core 1.24.4 + WebGPU Plugin EP 0.1.0。NuGet bytes/SHA-512、headers、runtime/plugin/companions、license 和 session options 已锁定；assembler 支持在线取得、离线复装和 exact SDK 校验。C++/Node plugin registration、D112 `webgpu → cpu`、typed/fatal failure、FP32 allow/strict、真实 provider chain、profiling、schema 2 descriptor、sterile loader、self-contained npm staging、license/SBOM 和双平台 CI 已实现。Linux RTX 5060 Ti/Vulkan 与 Windows Radeon 780M/D3D12 报告均为 164/164 Gate 通过、14/14 FP32 字节级质量对齐；聚合 P50 分别加速 5.698× 与 2.436×。Release configure 继续 fail closed，直到已审阅 report/artifact hashes 绑定进 production lock。 |
+| Perf-2 / Native WebGPU | Production-qualified / two device Gates passed | Linux x64 glibc/Vulkan 与 Windows x64/D3D12 使用 official ORT Core 1.24.4 + WebGPU Plugin EP 0.1.0。NuGet bytes/SHA-512、headers、runtime/plugin/companions、license 和 session options 已锁定；assembler 支持在线取得、离线复装和 exact SDK 校验。C++/Node plugin registration、D112 `webgpu → cpu`、typed/fatal failure、FP32 allow/strict、真实 provider chain、profiling、schema 2 descriptor、sterile loader、self-contained npm staging、license/SBOM 和双平台 CI 已实现。Linux RTX 5060 Ti/Vulkan 与 Windows Radeon 780M/D3D12 报告均为 164/164 Gate 通过、14/14 FP32 字节级质量对齐；聚合 P50 分别加速 5.698× 与 2.436×。已审阅 report/artifact hashes 已绑定 production lock，release configure 仅接受精确匹配的 SDK。 |
 | Node.js JPEG/PNG 内存输入 | Done / `0.2.0` published | `recognizeEncoded(Uint8Array)` 在 engine worker 上使用固定 stb revision 解码，保持 Core raw-pixel 边界；格式、尺寸、pixels、临时内存、queue/snapshot budget、AbortSignal 与 `timingUs.decode` 均有四平台 Node 22/24 package 测试。 |
 | 高分辨率峰值内存 | Done | Release 原生独立进程本机参考：2048² 空白 `318.8 MiB ≤ 384 MiB`；xfund 密集表单 116 框 `400.5 MiB ≤ 640 MiB`。四平台 release jobs 的真实模型与 RSS gates 均通过。 |
 | Tiled 高分辨率准确模式 | Done / `0.2.0` published | 1280 tile、2048→4-pass row-major、全局 candidate ceiling、IoU/IOS greedy merge、原图 recognition、C++/Node contract、8-fixture/196-line corpus、独立 oracle、四平台 36-entry accepted baseline 与 package smoke 均已完成。 |