feat(studio-3d): 阶段 5 —— 发布保护（签名/可选加密/平台锁定）与性能长时报告

- What: 新增 `scene3d/protect.py`（封套 v2：Ed25519 签名 + 可选 AES-256-GCM，nonce/salt 每包唯一、
  元数据作 AAD、明文摘要进签名、KeyProvider 只问 get_content_key）与 `record/visualization3d.py`
  （session.json 的 visualization3d 块：写入版本化、读取时缺块=不支持）；`package.py` 支持 v2
  （payload=plain 仅签名 / aes-gcm 签名+加密）并继续读 v1，新增解压比上限与"写入后自读回"校验；
  `contracts.py` 新增 PlatformLock/PlatformInfo/check_platform_lock、Sealing、platform_mismatch 诊断码；
  `Scene3DView` 在装配前查 OS/架构、拿到 capabilities 后查图形半区，违反即撤下场景并在面板显示原因；
  工具 `compile_scene.py` 新增 --sign-key/--write-verify-key/--encrypt-key-id/--key-file/--lock-from-probe，
  `validate_scene.py` 新增 --key-file/--key-id/--verify-key/--require-signature（发布门禁），
  新增 `bench_scene.py`（p50/p95 分阶段 + --cpu-only + --vertices N + --package）与
  `soak_scene.py`（RSS 四分位速率 + 队列上界 + 抽稀采样）；两份报告落到 docs/architecture/。
- Why: 规格 §5.2 的保护目标是"提高复制成本"而不是"防提取"，所以要的是签名（来源）+ 可选认证加密（机密性）
  + 密钥隔离，而不是自制加密或把 ZIP 当加密；§12 的"包保护/性能/长时"三行需要可复现的数字与判定标准，
  而不是一次性的观感。平台锁定还必须只降级三维：锁定不通过时二维照常。
- Verification: shared 全量通过（新增 test_scene3d_protect.py 35 项：封套往返/篡改/密钥/锁定/记录块/
  compile→validate 端到端发布流程；test_scene3d_package.py 20 项含 v1↔v2 兼容）；apps/studio 全量通过
  （test_scene3d_view.py 30 项含锁定拒绝与 session.json 块）；ui_check 566 项 0 失败；locale_check 0 缺失；
  真实资产端到端：1032 顶点编译出 signed+sealed+locked 包（56 927 B 密文），validate --require-signature 退出 0，
  改一个字节退出 2；性能报告（perf-report-windows-dev.json）：1032 顶点 compose p50 0.50 ms（30 fps 上限内），
  20022 顶点/39480 三角形 compose p50 6.15 ms（约 33 ms 帧的 18%），采集线程 submit p95 < 0.4 ms（合成器被人为放慢到 50 ms）；
  长时报告（soak-report-windows-dev.json）：无窗口 10 min/60 fps 尾段 0.354 MB/min，GUI 4 min/30 fps 尾段 0.809 MB/min，
  队列上界（mailbox=1、单飞行合成）两者均成立。过程中修掉：GUI 进程里的合成器计时被 GIL/vsync 污染（98.8 ms vs 真值 6.1 ms）、
  跨线程读 last_stats 撕裂、key id 无 provider 时会静默写明文包、soak 工具自身记时间列表会无界增长、RSS 读取失败伪装成零增长、
  平台锁定不是终态诊断。
- Not in this change: ARM 板卡的能力报告与 2 小时门禁运行（按用户要求暂缓；命令与判定标准已写入阶段 5 文档）；
  GPU 显存随时间的测量（无可移植 API，报告说明渲染器缓冲估计恒定且更新路径不新建 GPU 对象）；
  `cryptography` 在此环境无法联网安装，本机验收用的是本机已有的 cp310 构建（pyproject 里已声明为可选 extra
  `protected-assets`）。

apps/studio/pyproject.toml

@@ -27,6 +27,14 @@ dependencies = [
 three-d = [
   "PyOpenGL>=3.1.6",
 ]
+# Sealed release packages (stage 5): Ed25519 signatures and AES-256-GCM for
+# `.oryscene`. Separated from `three-d` because a plain package needs neither, and a
+# machine that only ever reads plain packages should not have to install a crypto
+# library to show a mesh. The runtime refuses a sealed package, with its reason, when
+# this extra is missing — it never falls back to reading it as plain.
+protected-assets = [
+  "cryptography>=42",
+]
 
 [project.scripts]
 orisys-studio = "orisys_studio.main:main"

apps/studio/src/orisys_studio/app_window.py

@@ -453,8 +453,33 @@ class StudioMainWindow(QMainWindow):
             self.toolbar.set_record_checked(False)
             self._refresh_record_state()
             return
+        # What the display actually did, while the writer is still accepting events:
+        # the block in session.json knows the configuration, and only this moment knows
+        # the totals. Logged before the stop so it cannot be lost to a closed queue.
+        self._log_visualization3d_totals()
         self._publish_record_report(self.recording.stop(wait=wait))
 
+    def _log_visualization3d_totals(self) -> None:
+        """One event with the display-side counters. Never raises, never blocks."""
+        try:
+            view = self.mesh3d_panel.view
+            if view is None:
+                return
+            coordinator = view.coordinator
+            stats = view.render_stats()
+            shown = int(getattr(stats, "displayed_frames", 0) or 0)
+            dropped = int(
+                coordinator.superseded_frames if coordinator is not None else 0
+            )
+            self.recorder.log_event(
+                "visualization3d",
+                f"shown={shown} dropped_display={dropped} "
+                f"stale={int(getattr(coordinator, 'stale_frames', 0) or 0)} "
+                f"invalid={int(getattr(coordinator, 'invalid_frames', 0) or 0)}",
+            )
+        except Exception:  # noqa: BLE001 - a picture must not fail a recording
+            logger.exception("Could not log the 3D display totals")
+
     def _publish_record_report(self, report) -> None:
         """Update the button and the summary from a recording report."""
         self.toolbar.set_record_status("")
@@ -580,8 +605,99 @@ class StudioMainWindow(QMainWindow):
             "filter": self._filter_metadata(),
             "recording_mode": self.toolbar.record_mode(),
             "video_config": config.as_dict(),
+            # What the 3D pane was, for a reader who has to decide whether a picture
+            # was part of the observation. Display-only facts: no measurement, and no
+            # counters (those are only known when the recording stops and travel as an
+            # event).
+            "visualization3d": self._visualization3d_metadata(),
         }
 
+    def _visualization3d_metadata(self) -> dict:
+        """The pane's state for ``session.json``. Must never block a recording.
+
+        Every read is guarded and every value is a plain JSON type: this method runs
+        on the way into a recording, and a widget that has been torn down or a scene
+        that was refused is not a reason to fail one.
+        """
+        from orisys_app_shared.record import build_visualization3d_block
+
+        enabled = False
+        available = False
+        reason = ""
+        scene: dict = {}
+        gl: dict = {}
+        display: dict = {}
+        stream: dict = {}
+        try:
+            pane = self.mesh3d_panel
+            view = pane.view
+            enabled = bool(pane.enabled())
+            available = bool(pane.is_available())
+            diagnostic = pane.last_diagnostic
+            assets = view.assets if view is not None else None
+            if assets is None:
+                reason = (
+                    diagnostic.message
+                    if diagnostic is not None
+                    else str(t("panels.mesh3d_no_scene"))
+                )
+            else:
+                scene = {
+                    "path": str(pane.scene_path() or ""),
+                    "asset_id": str(getattr(assets, "asset_id", "")),
+                    "asset_version": str(getattr(assets, "asset_version", "")),
+                    "asset_hash": str(getattr(assets, "asset_hash", "")),
+                    "geometry_id": str(getattr(assets, "geometry_id", "")),
+                    "field_domain_id": str(getattr(assets, "field_domain_id", "")),
+                    "platform_lock": (
+                        assets.platform_lock.to_dict()
+                        if getattr(assets, "platform_lock", None) is not None
+                        else None
+                    ),
+                }
+                widget = getattr(view, "gl_widget", None)
+                capabilities = widget.capabilities() if widget is not None else None
+                if capabilities is not None:
+                    gl = {
+                        "profile": str(capabilities.profile),
+                        "vendor": str(capabilities.vendor),
+                        "renderer": str(capabilities.renderer),
+                        "gl_version": str(capabilities.gl_version),
+                        "glsl_version": str(capabilities.glsl_version),
+                        "software_renderer": bool(capabilities.software_renderer),
+                    }
+                settings = view.settings()
+                scale = settings.color_scale
+                display = {
+                    "deform_enabled": bool(settings.deform_enabled),
+                    "display_gain": float(settings.display_gain),
+                    "housing_visible": bool(settings.housing_visible),
+                    "max_fps": int(settings.max_fps),
+                    "scale_mode": str(scale.mode) if scale is not None else "none",
+                    "scale_lower": float(scale.lower) if scale is not None else None,
+                    "scale_upper": float(scale.upper) if scale is not None else None,
+                }
+                descriptor = view.last_descriptor
+                if descriptor is not None:
+                    stream = {
+                        "quantity": str(descriptor.quantity),
+                        "unit": str(descriptor.unit),
+                        "quality": str(descriptor.quality),
+                        "signed": bool(descriptor.signed),
+                    }
+        except Exception:  # noqa: BLE001 - a recording must not fail over a picture
+            logger.exception("Could not describe the 3D pane for the recording")
+            reason = reason or "the 3D pane could not be described"
+        return build_visualization3d_block(
+            enabled=enabled,
+            available=available,
+            reason=reason,
+            scene=scene or None,
+            gl=gl or None,
+            display=display or None,
+            stream=stream or None,
+        )
+
     @staticmethod
     def _config_hash(config_ref: str) -> str:
         try:

apps/studio/src/orisys_studio/scene3d/view.py

@@ -38,9 +38,11 @@ from orisys_app_shared.scene3d.contracts import (
     ExpectedGeometry,
     FieldDescriptor,
     FrameIdentity,
+    PlatformInfo,
     RenderStats,
     SceneAssets,
     SceneState,
+    check_platform_lock,
     diagnostic,
     validate_assets,
 )
@@ -170,6 +172,8 @@ class Scene3DView(QWidget):
         snapshot = self._make_snapshot(assets, expected)
         if snapshot is None:
             return False
+        if not self._lock_allows(assets):
+            return False
         self._assets = assets
         self._expected = expected
         self._snapshot = snapshot
@@ -180,6 +184,19 @@ class Scene3DView(QWidget):
             self._panel.set_scene(assets)
         return True
 
+    def _lock_allows(self, assets: SceneAssets) -> bool:
+        """The half of the platform lock that can be checked before a context exists.
+
+        Operating system and architecture are known now; the graphics fields only after
+        Qt has made a context, which is why the check is split (see
+        ``_check_lock_capabilities``). Refusing here is what keeps a package released
+        for one operating system from being drawn on another at all.
+        """
+        violations = check_platform_lock(assets.platform_lock, PlatformInfo.here())
+        for item in violations:
+            self._on_diagnostic(item)
+        return not violations
+
     def _make_snapshot(
         self, assets: SceneAssets, expected: Optional[ExpectedGeometry]
     ) -> Optional[Callable[[Any, FrameIdentity], Any]]:
@@ -373,13 +390,50 @@ class Scene3DView(QWidget):
         self.stateChanged.emit(state)
 
     def _on_capabilities(self, capabilities: Any) -> None:
-        if self._panel is not None and getattr(capabilities, "software_renderer", False):
+        software = bool(getattr(capabilities, "software_renderer", False))
+        if software and self._panel is not None:
             self._panel.set_diagnostic(
                 diagnostic(
                     "gl_unsupported",
                     "the OpenGL context is a software rasteriser: expect a slow view",
                 )
             )
+        self._check_lock_capabilities(capabilities)
+
+    def _check_lock_capabilities(self, capabilities: Any) -> None:
+        """The graphics half of the platform lock, checked the moment it is knowable.
+
+        A locked package whose lock this machine violates is *withdrawn*: the scene is
+        dropped and the pane shows the reason. Half a lock (the OS matched, the GPU did
+        not) is not a partial success — the package was qualified somewhere else.
+        """
+        assets = self._assets
+        if assets is None or assets.platform_lock is None:
+            return
+        if capabilities is None:
+            return
+        info = PlatformInfo.here(capabilities)
+        violations = check_platform_lock(assets.platform_lock, info)
+        if not violations:
+            return
+        for item in violations:
+            self._on_diagnostic(item)
+        self._withdraw_scene()
+
+    def _withdraw_scene(self) -> None:
+        """Drop the scene, keep the pane: a lock violation is not a crash."""
+        self._assets = None
+        self._snapshot = None
+        if self._coordinator is not None:
+            self._coordinator.close()
+        if self._widget is not None:
+            try:
+                self._widget.release_resources()
+            except Exception:  # noqa: BLE001 - withdrawal must not raise
+                logger.exception("releasing the GPU resources after a refusal failed")
+        if self._panel is not None:
+            self._panel.set_scene(None)
+        self._enabled = False
 
     def _on_descriptor(self, descriptor: Any) -> None:
         """The frame on screen changed what it claims to be.

apps/studio/src/orisys_studio/ui/mesh3d_panel.py

@@ -41,7 +41,9 @@ _REJECTED = "rejected"
 
 #: Diagnostics that mean "this view cannot draw here", as opposed to "this one frame
 #: was refused". The first kind replaces the picture; the second must not.
-_TERMINAL_CODES = frozenset({"gl_unsupported", "shader_compile_failed"})
+_TERMINAL_CODES = frozenset(
+    {"gl_unsupported", "shader_compile_failed", "platform_mismatch"}
+)
 
 #: One locale key per state, so ``retranslate`` can rebuild whatever is on screen.
 _MESSAGE_KEYS = {

apps/studio/tests/test_scene3d_view.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import itertools
 import shutil
+from dataclasses import replace
 from pathlib import Path
 
 import numpy as np
@@ -270,6 +271,7 @@ class _RecordingView:
 
     def __init__(self) -> None:
         self.packets: list = []
+        self.coordinator = None
 
     def submit_packet(self, packet) -> None:
         # Deliberately more work than the real one does per packet, so a leak into the
@@ -278,6 +280,9 @@ class _RecordingView:
         frame = np.asarray(packet.raw_frame)
         float(np.asarray(frame, dtype=np.float64).sum())
 
+    def render_stats(self):
+        return None
+
 
 def _run_session(make_window, record_root, *, with_3d: bool):
     """One full session with the 3D sink attached, or with no pane at all."""
@@ -533,3 +538,86 @@ def test_a_finger_scene_uses_the_finger_adapter(tmp_path, write_poc, qt_app):
         assert view.assets is not None
     finally:
         view.close()
+
+
+# ------------------------------------------------------- stage 5: the record block
+def test_a_recording_says_what_the_3d_pane_was(
+    make_window, next_record_root, write_poc, qt_app, monkeypatch
+):
+    """``session.json`` carries the pane's state, and an event carries the totals."""
+    import json
+
+    import orisys_studio.app_window as app_module
+
+    window, stuck = _running_window(make_window)
+    app_module.recordings_dir = lambda: next_record_root()
+    try:
+        # A real view on a machine with no GL is not possible; the stand-in gives the
+        # metadata assembly something to describe (an enabled pane with a scene).
+        view = _RecordingView()
+        view.assets = None
+        window.mesh3d_panel._view = view
+        window.toolbar.btn_record.setChecked(True)
+        for index in range(20):
+            stuck.emit(ui_check._fake_packet(index, mono_t=index / 30.0))
+        window._on_run_tick()
+        window.toolbar.btn_record.setChecked(False)
+        report = window._record_last_report
+        assert report is not None and report.completed or report is not None
+        if report is None or not report.completed:
+            pytest.skip("the writer had not finished on this machine")
+        meta = json.loads((report.directory / "session.json").read_text(encoding="utf-8"))
+        block = meta["visualization3d"]
+        assert block["block_version"] == 1
+        assert block["enabled"] is False, (
+            "the pane was not switched on, so the record must say so"
+        )
+        # The pane has no scene here (no package installed), so the block names the
+        # reason instead of pretending to describe a picture.
+        assert block.get("reason")
+        events = (report.directory / "events.csv").read_text(encoding="utf-8")
+        assert "visualization3d" in events, (
+            "the display totals were not recorded as an event"
+        )
+    finally:
+        _finish(window, stuck)
+        window.close()
+
+
+def test_a_platform_locked_scene_is_refused_in_the_application(qt_app):
+    """A lock violation is a *pane* failure: the view refuses the scene and says why."""
+    from orisys_app_shared.scene3d.contracts import PlatformInfo, PlatformLock
+    from orisys_studio.scene3d.view import Scene3DView
+    from orisys_studio.ui.mesh3d_panel import Mesh3dPanel
+
+    here = PlatformInfo.here()
+    elsewhere = "linux" if here.os_family != "linux" else "windows"
+    locked = replace(
+        synthetic.poc_scene(),
+        platform_lock=PlatformLock(os_family=(elsewhere,), machine=("aarch64",)),
+    )
+    view = Scene3DView()
+    try:
+        if not view.available:
+            pytest.skip("no GL binding here")
+        reported: list = []
+        view.diagnosticRaised.connect(reported.append)
+        assert view.use_scene(locked, source_id="locked") is False
+        assert view.assets is None, "a refused scene must not remain adopted"
+        assert any(item.code == "platform_mismatch" for item in reported), reported
+    finally:
+        view.close()
+
+    panel = Mesh3dPanel()
+    try:
+        # The pane shows the reason rather than an empty picture: `platform_mismatch`
+        # is one of the terminal diagnostics.
+        panel._on_diagnostic(
+            __import__(
+                "orisys_app_shared.scene3d.contracts", fromlist=["diagnostic"]
+            ).diagnostic("platform_mismatch", "this package is not released for this OS")
+        )
+        assert panel.showing_message
+        assert "not released" in panel.message.text()
+    finally:
+        panel.deleteLater()