dreamwell-runtime 1.0.0

// Scene renderer — draws the game scene to the window surface.
// Delegates GPU pipeline orchestration to DreamFabric.
// Render graph: fabric.begin_frame → extract → prepare → queue → fabric.end_frame → present.
//
// CODESPEC: No per-frame allocation. Buffers pre-allocated and reused.
// Pipeline creation is lazy (first frame only) with warmup precompilation at startup.
// Surface errors handled without panic (reconfigure on Lost/Outdated).
// GPU timestamps (TIMESTAMP_QUERY) provide gpu_ms when adapter supports them.

use crate::scene::Scene;
use crate::window::WindowState;
use dreamwell_engine::material::SceneDreamMode;
use dreamwell_engine::TopologyLayer;
use dreamwell_fabric::entanglement::CausalEntanglement;
use dreamwell_fabric::DreamFabric;
use dreamwell_fabric::{CausalObserverLaneSender, CausalObserverRecorder, FrameGate, FrameMemory, FrameSeal};
use dreamwell_gpu::formats::DEPTH_FORMAT;
use dreamwell_gpu::post::PostProcessConfig;

/// Frame health record — populated after present(), read by app.rs next frame.
#[derive(Clone, Debug)]
pub struct FrameContract {
    pub frame: u64,
    pub cpu_ms: f32,
    pub gpu_ms: f32,
    pub budget_ms: f32,
    pub budget_exceeded: bool,
    pub quality_tier: u32,
    pub particle_count: u32,
    pub post_process_enabled: bool,
    pub frame_skipped: bool,
    pub seal_digest: [u8; 32],
    pub chain_depth: u64,
    pub presented: bool,
}

impl Default for FrameContract {
    fn default() -> Self {
        Self {
            frame: 0,
            cpu_ms: 0.0,
            gpu_ms: 0.0,
            budget_ms: 16.67,
            budget_exceeded: false,
            quality_tier: 0,
            particle_count: 0,
            post_process_enabled: true,
            frame_skipped: false,
            seal_digest: [0u8; 32],
            chain_depth: 0,
            presented: true,
        }
    }
}

/// Scene renderer for the runtime. Owns DreamFabric and depth buffer.
///
/// Memory safety:
/// - `depth_texture` / `depth_view` are recreated on resize (old dropped first).
/// - `fabric` owns GPU scene, observer, meshlet, cull, and particle resources.
/// - `fabric.matter` is the single owner of all particle systems.
/// - No Arc/Mutex — single-owner, no thread sharing.
pub struct SceneRenderer {
    width: u32,
    height: u32,
    depth_texture: Option<wgpu::Texture>,
    depth_view: Option<wgpu::TextureView>,
    /// MSAA color resolve texture (created when sample_count > 1).
    /// Allocation deferred until fabric gains MSAA support.
    msaa_texture: Option<wgpu::Texture>,
    msaa_view: Option<wgpu::TextureView>,
    /// MSAA sample count (1 = disabled, 4 = recommended).
    msaa_samples: u32,
    pub fabric: Box<DreamFabric>,
    total_time: f32,
    /// CPU frame time in milliseconds from the previous frame (dt * 1000).
    last_cpu_ms: f32,
    /// GPU timestamp query set (2 timestamps: start/end). None if adapter lacks TIMESTAMP_QUERY.
    query_set: Option<wgpu::QuerySet>,
    /// GPU timestamp resolve buffer (16 bytes = 2 x u64).
    resolve_buf: Option<wgpu::Buffer>,
    /// GPU timestamp readback buffer (16 bytes, MAP_READ). Read 1 frame behind.
    readback_buf: Option<wgpu::Buffer>,
    /// Last GPU frame time in milliseconds (1-frame lag from readback).
    last_gpu_ms: f32,
    /// GPU timestamp period (nanoseconds per tick). 0.0 if timestamps unavailable.
    timestamp_period: f32,
    /// FrameGate — GPU budget enforcement and quality scaling.
    frame_gate: FrameGate,
    /// FrameSeal — BLAKE3 chain attestation for GPU frames.
    frame_seal: FrameSeal,
    /// FrameMemory — 120-frame ring buffer of sealed frame records.
    frame_memory: FrameMemory,
    /// CausalObserverRecorder — KPI timing for GPU causal observer hot path.
    causal_observer_recorder: CausalObserverRecorder,
    /// CausalObserverLane sender — cold path to QuantumCloud (set by SimulationService).
    causal_observer_tx: Option<CausalObserverLaneSender>,
    /// Last bridge seal digest (from decoder).
    last_bridge_seal: [u8; 32],
    /// Last frame contract — public API for app layer.
    pub last_frame_contract: FrameContract,
    /// Frame counter for seal chain.
    frame_count: u64,
}

impl SceneRenderer {
    pub fn new(ws: &WindowState) -> Self {
        Self::with_msaa(ws, 1)
    }

    /// Create renderer with explicit MSAA sample count.
    pub fn with_msaa(ws: &WindowState, msaa_samples: u32) -> Self {
        let samples = match msaa_samples {
            1 | 4 => msaa_samples,
            _ => {
                log::warn!("msaa_samples={msaa_samples} not supported, falling back to 1");
                1
            }
        };
        let fabric = Box::new(DreamFabric::new(&ws.device, ws.surface_config.format, false));

        // GPU timestamp query setup (adapter-dependent).
        // wgpu 27+ split TIMESTAMP_QUERY into two features:
        // TIMESTAMP_QUERY (for resolve) and TIMESTAMP_QUERY_INSIDE_ENCODERS (for write_timestamp).
        // We need both to use encoder.write_timestamp() + resolve.
        let has_timestamps = ws.device.features().contains(wgpu::Features::TIMESTAMP_QUERY)
            && ws
                .device
                .features()
                .contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS);
        let (query_set, resolve_buf, readback_buf, timestamp_period) = if has_timestamps {
            let qs = ws.device.create_query_set(&wgpu::QuerySetDescriptor {
                label: Some("gpu_timestamp_queries"),
                ty: wgpu::QueryType::Timestamp,
                count: 2,
            });
            let resolve = ws.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("gpu_timestamp_resolve"),
                size: 16, // 2 x u64
                usage: wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC,
                mapped_at_creation: false,
            });
            let readback = ws.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("gpu_timestamp_readback"),
                size: 16,
                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
                mapped_at_creation: false,
            });
            let period = ws.queue.get_timestamp_period();
            log::info!("GPU timestamps enabled (period={period:.2}ns)");
            (Some(qs), Some(resolve), Some(readback), period)
        } else {
            log::info!("GPU timestamps unavailable (adapter lacks TIMESTAMP_QUERY)");
            (None, None, None, 0.0)
        };

        let mut renderer = Self {
            width: ws.surface_config.width,
            height: ws.surface_config.height,
            depth_texture: None,
            depth_view: None,
            msaa_texture: None,
            msaa_view: None,
            msaa_samples: samples,
            fabric,
            total_time: 0.0,
            last_cpu_ms: 0.0,
            query_set,
            resolve_buf,
            readback_buf,
            last_gpu_ms: 0.0,
            timestamp_period,
            frame_gate: FrameGate::default(),
            frame_seal: FrameSeal::new(),
            frame_memory: FrameMemory::default(),
            causal_observer_recorder: CausalObserverRecorder::default(),
            causal_observer_tx: None,
            last_bridge_seal: [0u8; 32],
            last_frame_contract: FrameContract::default(),
            frame_count: 0,
        };
        renderer.create_depth_texture(&ws.device);
        renderer
            .fabric
            .resize(&ws.device, ws.surface_config.width, ws.surface_config.height);
        renderer
    }

    pub fn resize(&mut self, width: u32, height: u32, device: &wgpu::Device) {
        if width == 0 || height == 0 {
            return;
        }
        if self.width == width && self.height == height {
            return; // No-op if same size.
        }
        self.width = width;
        self.height = height;
        self.create_depth_texture(device);
        self.fabric.resize(device, width, height);
    }

    /// Create/recreate depth and MSAA textures. Old resources dropped before allocation.
    fn create_depth_texture(&mut self, device: &wgpu::Device) {
        if self.width == 0 || self.height == 0 {
            return;
        }
        // Drop old resources first to free GPU memory before allocating new.
        self.depth_view = None;
        self.depth_texture = None;
        self.msaa_view = None;
        self.msaa_texture = None;

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("runtime_depth"),
            size: wgpu::Extent3d {
                width: self.width,
                height: self.height,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: self.msaa_samples,
            dimension: wgpu::TextureDimension::D2,
            format: DEPTH_FORMAT,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        self.depth_texture = Some(texture);
        self.depth_view = Some(view);

        // Allocate MSAA color resolve texture when sample_count > 1.
        if self.msaa_samples > 1 {
            let surface_format = wgpu::TextureFormat::Bgra8UnormSrgb;
            let msaa_tex = device.create_texture(&wgpu::TextureDescriptor {
                label: Some("runtime_msaa_color"),
                size: wgpu::Extent3d {
                    width: self.width,
                    height: self.height,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: self.msaa_samples,
                dimension: wgpu::TextureDimension::D2,
                format: surface_format,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
            let msaa_v = msaa_tex.create_view(&wgpu::TextureViewDescriptor::default());
            self.msaa_texture = Some(msaa_tex);
            self.msaa_view = Some(msaa_v);
        }
    }

    /// Render the scene. Frame sequence:
    /// 1. Acquire surface texture (handle Lost/Outdated gracefully)
    /// 2. DreamFabric begin_frame (observer update, GPU upload)
    /// 3. Sync GPU scene transforms from engine scene
    /// 4. Extract → Prepare → Queue (render staging)
    /// 5. DreamFabric end_frame (cull → DreamMatter simulate → render → picking)
    /// 6. GPU timestamp resolve + readback
    /// 7. Submit + present
    pub fn render(
        &mut self,
        ws: &WindowState,
        scene: &Scene,
        dt: f32,
        player_pos: glam::Vec3,
        active_layer: TopologyLayer,
    ) {
        // Record CPU frame time from caller-supplied dt (measured by FrameTimer).
        self.last_cpu_ms = dt * 1000.0;
        self.total_time += dt;

        // Read previous frame's GPU timestamp (1-frame lag).
        self.read_gpu_timestamp(&ws.device);

        // 1. Acquire surface texture.
        let output = match ws.surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(t) => t,
            wgpu::CurrentSurfaceTexture::Suboptimal(t) => {
                log::warn!("surface suboptimal — reconfiguring");
                ws.surface.configure(&ws.device, &ws.surface_config);
                t
            }
            wgpu::CurrentSurfaceTexture::Outdated | wgpu::CurrentSurfaceTexture::Lost => {
                log::warn!("surface lost/outdated — reconfiguring");
                ws.surface.configure(&ws.device, &ws.surface_config);
                return;
            }
            wgpu::CurrentSurfaceTexture::Timeout | wgpu::CurrentSurfaceTexture::Occluded => {
                return;
            }
            wgpu::CurrentSurfaceTexture::Validation => {
                log::error!("surface validation error");
                return;
            }
        };

        let view = output.texture.create_view(&wgpu::TextureViewDescriptor::default());

        let mut encoder = ws.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("runtime_render"),
        });

        // GPU timestamp: start
        if let Some(ref qs) = self.query_set {
            encoder.write_timestamp(qs, 0);
        }

        // 2. DreamFabric begin_frame
        let fc = self.fabric.begin_frame(&ws.queue, dt, player_pos, active_layer);

        // 3. Sync GPU scene — re-upload if dirty, otherwise just update transforms.
        if self.fabric.gpu_scene().is_dirty() {
            self.fabric.upload_scene(&ws.device, &scene.game_objects);
        } else {
            self.fabric.sync_scene_transforms(&scene.game_objects);
        }

        // 4. Extract → Prepare → Queue (render staging).
        self.fabric.extract(&scene.game_objects, &fc.gpu_observer, dt);
        self.fabric.prepare(&scene.game_objects);
        self.fabric.queue_draw_items(&scene.camera);

        // 5. DreamFabric end_frame — submits compute commands immediately via
        // queue.submit(), then populates the render encoder. Compute-render ordering
        // is guaranteed by wgpu's sequential queue submission model.
        if let Some(dv) = &self.depth_view {
            self.fabric.end_frame(
                &ws.device,
                &ws.queue,
                &mut encoder,
                &view,
                dv,
                &scene.camera,
                &fc,
                self.msaa_view.as_ref(),
            );
        } else {
            // Fallback: depth_view missing — render a clear pass directly to surface
            // so the window isn't black. This indicates create_depth_texture failed.
            log::warn!("depth_view is None — rendering fallback clear pass");
            let _pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("fallback_clear"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &view,
                    resolve_target: None,
                    depth_slice: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Clear(wgpu::Color {
                            r: 1.0,
                            g: 0.0,
                            b: 0.0,
                            a: 1.0,
                        }),
                        store: wgpu::StoreOp::Store,
                    },
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });
        }

        // GPU timestamp: end + resolve + copy to readback
        if let (Some(ref qs), Some(ref resolve), Some(ref readback)) =
            (&self.query_set, &self.resolve_buf, &self.readback_buf)
        {
            encoder.write_timestamp(qs, 1);
            encoder.resolve_query_set(qs, 0..2, resolve, 0);
            encoder.copy_buffer_to_buffer(resolve, 0, readback, 0, 16);
        }

        // 6. Submit render command buffer. Compute was already submitted by end_frame().
        let render_cmds = encoder.finish();
        ws.queue.submit(std::iter::once(render_cmds));
        output.present();

        // === GPU Causal Observer Pipeline ===
        self.frame_count += 1;

        // Quality decision (uses previous frame's gpu_ms).
        let quality = self
            .frame_gate
            .evaluate(self.last_gpu_ms, self.fabric.matter().dreammatter_capacity());
        let quality_tier = self.frame_gate.quality_tier();

        // Seal the frame.
        let timestamp_ns = std::time::SystemTime::now()
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .map(|d| d.as_nanos() as u64)
            .unwrap_or(0);
        let entry = self.frame_seal.seal_frame(
            self.frame_count,
            self.last_gpu_ms,
            self.last_cpu_ms,
            quality.particle_count,
            quality_tier,
            self.last_bridge_seal,
            timestamp_ns,
            true,
        );

        // Capture to frame memory.
        let chain_depth = self.frame_seal.chain_depth();
        self.frame_memory.capture_seal(entry.clone());

        // Record causal observer timing.
        let dispatch_ns = self.causal_observer_recorder.now_ns();
        self.causal_observer_recorder.record(
            self.frame_count,
            dispatch_ns,
            self.last_gpu_ms,
            quality.particle_count,
            quality_tier,
            true,
        );

        // Cold path dispatch.
        if let Some(ref tx) = self.causal_observer_tx {
            tx.send_frame(&entry, self.frame_count, chain_depth);
        }

        // Populate frame contract for app layer.
        self.last_frame_contract = FrameContract {
            frame: self.frame_count,
            cpu_ms: self.last_cpu_ms,
            gpu_ms: self.last_gpu_ms,
            budget_ms: 16.67,
            budget_exceeded: self.last_gpu_ms > 16.67 * 0.85,
            quality_tier,
            particle_count: quality.particle_count,
            post_process_enabled: quality.post_process_enabled,
            frame_skipped: false,
            seal_digest: entry.seal_digest,
            chain_depth,
            presented: true,
        };
    }

    /// Render with CausalEntanglement — production entry point.
    /// Same pipeline as render() but uses begin_frame_entangled() for
    /// observer-aware quantum culling via CausalEntanglement.
    pub fn render_entangled(
        &mut self,
        ws: &WindowState,
        scene: &Scene,
        dt: f32,
        entanglement: &CausalEntanglement,
        active_layer: TopologyLayer,
    ) {
        self.last_cpu_ms = dt * 1000.0;
        self.total_time += dt;

        self.read_gpu_timestamp(&ws.device);

        let output = match ws.surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(t) => t,
            wgpu::CurrentSurfaceTexture::Suboptimal(t) => {
                log::warn!("surface suboptimal — reconfiguring");
                ws.surface.configure(&ws.device, &ws.surface_config);
                t
            }
            wgpu::CurrentSurfaceTexture::Outdated | wgpu::CurrentSurfaceTexture::Lost => {
                log::warn!("surface lost/outdated — reconfiguring");
                ws.surface.configure(&ws.device, &ws.surface_config);
                return;
            }
            wgpu::CurrentSurfaceTexture::Timeout | wgpu::CurrentSurfaceTexture::Occluded => {
                return;
            }
            wgpu::CurrentSurfaceTexture::Validation => {
                log::error!("surface validation error");
                return;
            }
        };

        let view = output.texture.create_view(&wgpu::TextureViewDescriptor::default());

        let mut encoder = ws.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("runtime_render_entangled"),
        });

        if let Some(ref qs) = self.query_set {
            encoder.write_timestamp(qs, 0);
        }

        // Production entry: CausalEntanglement → GpuObserverContext
        let fc = self
            .fabric
            .begin_frame_entangled(&ws.queue, dt, entanglement, active_layer);

        if self.fabric.gpu_scene().is_dirty() {
            self.fabric.upload_scene(&ws.device, &scene.game_objects);
        } else {
            self.fabric.sync_scene_transforms(&scene.game_objects);
        }

        self.fabric.extract(&scene.game_objects, &fc.gpu_observer, dt);
        self.fabric.prepare(&scene.game_objects);
        self.fabric.queue_draw_items(&scene.camera);

        if let Some(dv) = &self.depth_view {
            self.fabric.end_frame(
                &ws.device,
                &ws.queue,
                &mut encoder,
                &view,
                dv,
                &scene.camera,
                &fc,
                self.msaa_view.as_ref(),
            );
        }

        if let (Some(ref qs), Some(ref resolve), Some(ref readback)) =
            (&self.query_set, &self.resolve_buf, &self.readback_buf)
        {
            encoder.write_timestamp(qs, 1);
            encoder.resolve_query_set(qs, 0..2, resolve, 0);
            encoder.copy_buffer_to_buffer(resolve, 0, readback, 0, 16);
        }

        let render_cmds = encoder.finish();
        ws.queue.submit(std::iter::once(render_cmds));
        output.present();

        // === GPU Causal Observer Pipeline ===
        self.frame_count += 1;

        // Quality decision (uses previous frame's gpu_ms).
        let quality = self
            .frame_gate
            .evaluate(self.last_gpu_ms, self.fabric.matter().dreammatter_capacity());
        let quality_tier = self.frame_gate.quality_tier();

        // Seal the frame.
        let timestamp_ns = std::time::SystemTime::now()
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .map(|d| d.as_nanos() as u64)
            .unwrap_or(0);
        let entry = self.frame_seal.seal_frame(
            self.frame_count,
            self.last_gpu_ms,
            self.last_cpu_ms,
            quality.particle_count,
            quality_tier,
            self.last_bridge_seal,
            timestamp_ns,
            true,
        );

        // Capture to frame memory.
        let chain_depth = self.frame_seal.chain_depth();
        self.frame_memory.capture_seal(entry.clone());

        // Record causal observer timing.
        let dispatch_ns = self.causal_observer_recorder.now_ns();
        self.causal_observer_recorder.record(
            self.frame_count,
            dispatch_ns,
            self.last_gpu_ms,
            quality.particle_count,
            quality_tier,
            true,
        );

        // Cold path dispatch.
        if let Some(ref tx) = self.causal_observer_tx {
            tx.send_frame(&entry, self.frame_count, chain_depth);
        }

        // Populate frame contract for app layer.
        self.last_frame_contract = FrameContract {
            frame: self.frame_count,
            cpu_ms: self.last_cpu_ms,
            gpu_ms: self.last_gpu_ms,
            budget_ms: 16.67,
            budget_exceeded: self.last_gpu_ms > 16.67 * 0.85,
            quality_tier,
            particle_count: quality.particle_count,
            post_process_enabled: quality.post_process_enabled,
            frame_skipped: false,
            seal_digest: entry.seal_digest,
            chain_depth,
            presented: true,
        };
    }

    /// Read GPU timestamp from the readback buffer (previous frame's data).
    /// Polls the device to resolve the map_async callback, then reads with 1-frame lag.
    fn read_gpu_timestamp(&mut self, device: &wgpu::Device) {
        let Some(ref readback) = self.readback_buf else { return };
        if self.timestamp_period == 0.0 {
            return;
        }

        let slice = readback.slice(..);
        let (tx, rx) = std::sync::mpsc::sync_channel(1);
        slice.map_async(wgpu::MapMode::Read, move |result| {
            let _ = tx.send(result);
        });

        // Poll device to give the map_async callback a chance to fire.
        // Maintain::Poll is non-blocking — returns immediately if no work is pending.
        let _ = device.poll(wgpu::PollType::Poll);

        if let Ok(Ok(())) = rx.try_recv() {
            let data = slice.get_mapped_range();
            if data.len() >= 16 {
                let timestamps: &[u64] = bytemuck::cast_slice(&data[..16]);
                let start = timestamps[0];
                let end = timestamps[1];
                if end > start {
                    self.last_gpu_ms = (end - start) as f32 * self.timestamp_period / 1_000_000.0;
                }
            }
            drop(data);
            readback.unmap();
        }
    }

    /// Current render dimensions.
    pub fn dimensions(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    /// MSAA sample count.
    pub fn msaa_samples(&self) -> u32 {
        self.msaa_samples
    }

    /// Get the MSAA view for render pass color attachment.
    /// Returns None when MSAA is disabled (sample_count = 1).
    pub fn msaa_view(&self) -> Option<&wgpu::TextureView> {
        self.msaa_view.as_ref()
    }

    /// Last picked object ID.
    pub fn last_picked_id(&self) -> u32 {
        self.fabric.last_picked_id()
    }

    /// Per-frame stats. `cpu_ms` is the wall-clock frame time from FrameTimer.
    /// `gpu_ms` is populated from GPU timestamp queries when available (1-frame lag).
    pub fn last_frame_stats(&self) -> dreamwell_fabric::FrameStats {
        dreamwell_fabric::FrameStats {
            cpu_ms: self.last_cpu_ms,
            gpu_ms: self.last_gpu_ms,
            visible_meshlets: self.fabric.gpu_scene().object_count() as u32,
            particle_count: self.fabric.matter().dreammatter_capacity(),
        }
    }

    /// Set post-processing configuration.
    pub fn set_post_process_config(&mut self, config: PostProcessConfig) {
        self.fabric.set_post_process_config(config);
    }

    /// Get post-processing configuration.
    pub fn post_process_config(&self) -> &PostProcessConfig {
        self.fabric.post_process_config()
    }

    /// Set the scene rendering mode.
    pub fn set_scene_dream_mode(&mut self, mode: SceneDreamMode) {
        self.fabric.set_scene_dream_mode(mode);
    }

    /// Get the current scene rendering mode.
    pub fn scene_dream_mode(&self) -> SceneDreamMode {
        self.fabric.scene_dream_mode()
    }

    /// Set the causal observer lane sender for cold path dispatch.
    pub fn set_causal_observer_sender(&mut self, tx: CausalObserverLaneSender) {
        self.causal_observer_tx = Some(tx);
    }

    /// Set the last bridge seal digest (from decoder).
    pub fn set_bridge_seal(&mut self, seal: [u8; 32]) {
        self.last_bridge_seal = seal;
    }

    /// Get the frame gate for quality tier inspection.
    pub fn frame_gate(&self) -> &FrameGate {
        &self.frame_gate
    }

    /// Get the frame seal for chain depth inspection.
    pub fn frame_seal(&self) -> &FrameSeal {
        &self.frame_seal
    }

    /// Get the frame memory for replay/debug access.
    pub fn frame_memory(&self) -> &FrameMemory {
        &self.frame_memory
    }

    /// Get the causal observer recorder for KPI timing.
    pub fn causal_observer_recorder(&self) -> &CausalObserverRecorder {
        &self.causal_observer_recorder
    }
}