From 94963725b357572f7f9fc6a9e68f86dfc5575d81 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 01:46:43 +0300 Subject: [PATCH 01/11] The platform interface is published through one module: host, with an EventSink beside the SDL poll Shell, Surface, FrameProbe, Platform, MediaBoot, Composition, Exit and Release become pub items that a platform crate reaches only through plxnative_modules::host (owner ruling 2026-11-21, Decision 3 amended); HostEvent stays private. Surface::deliver(&self, &mut dyn EventSink) is additive beside poll, which is defaulted and hidden: the SDL surface delivers nothing and every SDL event still comes through poll. A private HostQueue is the one conversion, with one call in drain_sdl. RawKey moves to plx_ui::consts. host::run forwards to run_application. Co-Authored-By: Claude Sonnet 5.5 --- rust-modules/shell-sdl/src/lib.rs | 9 +- rust-modules/src/app/events.rs | 132 +++++++++++++++++++++++++++--- rust-modules/src/app/exit.rs | 10 +-- rust-modules/src/app/mod.rs | 4 +- rust-modules/src/app/platform.rs | 131 +++++++++++++++++++++++------ rust-modules/src/app/run.rs | 45 ++++++++++ rust-modules/src/host.rs | 42 ++++++++++ rust-modules/src/lib.rs | 4 + rust-modules/ui/src/consts.rs | 15 ++++ 9 files changed, 349 insertions(+), 43 deletions(-) create mode 100644 rust-modules/src/host.rs diff --git a/rust-modules/shell-sdl/src/lib.rs b/rust-modules/shell-sdl/src/lib.rs index 507abe9c3..ee0d734fb 100644 --- a/rust-modules/shell-sdl/src/lib.rs +++ b/rust-modules/shell-sdl/src/lib.rs @@ -11,8 +11,8 @@ //! as two plain function pointers the television fills and a desktop leaves empty. //! //! The crate is a mounted module of the `shell_sdl` layer (`ci/module-layers.ini`), which may use -//! `base`, `machine` and `os`; the crate names `base` alone. The application's `Shell` and `Surface` traits and its `HostEvent` stay app-private -//! (`docs/platform-ports.md`, Target shapes 1 and 8); [`window::Window`] is the one SDL +//! `base`, `machine` and `os`; the crate names `base` alone. The application's `HostEvent` stays app-private, and its `Shell` and `Surface` traits are reachable only through +//! the application crate's `host` module (`docs/platform-ports.md`, Target shapes 1 and 8); [`window::Window`] is the one SDL //! implementation of that `Surface`, and [`event::Decoded`] is the neutral value the application maps //! onto its own event type. //! @@ -57,9 +57,12 @@ mod pins { #[test] fn every_source_file_is_scanned() { + // `*.rs` files and directories only: an editor's swap file or a `.DS_Store` is not source. let mut on_disk: Vec = std::fs::read_dir(concat!(env!("CARGO_MANIFEST_DIR"), "/src")) .expect("the crate's src directory") - .map(|e| e.expect("a directory entry").file_name().to_string_lossy().into_owned()) + .map(|e| e.expect("a directory entry")) + .filter(|e| e.path().is_dir() || e.path().extension().is_some_and(|x| x == "rs")) + .map(|e| e.file_name().to_string_lossy().into_owned()) .collect(); on_disk.sort(); let mut listed: Vec<&str> = SOURCES.iter().map(|s| s.0).collect(); diff --git a/rust-modules/src/app/events.rs b/rust-modules/src/app/events.rs index d6db179e4..015200281 100644 --- a/rust-modules/src/app/events.rs +++ b/rust-modules/src/app/events.rs @@ -10,6 +10,8 @@ use super::*; use plx_machine::machine::Edge; +// `RawKey` is `plx_ui::consts`' (a platform crate names it through `host`); this is the application's spelling. +pub(crate) use plx_ui::consts::RawKey; use plx_ui::consts::{action_of, raw_pair, Action}; /// Preserve one IME commit and its place among key events. Desktop text does not imply an @@ -128,17 +130,6 @@ impl HostEvent { } } -/// The raw `(sym, wcode)` pair a key arrived as. Kept beside the [`Action`] because three things -/// still read it: a press with no action (an unsupported key flows on as exactly the pair it was), -/// the lab trigger key (named by `lab.json`, not by an action), and the recorder's tape, whose -/// format IS the pair. A platform with no SDL pair sends none, and the loop builds -/// [`raw_pair`] for its action. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) struct RawKey { - pub sym: c_uint, - pub wcode: c_uint, -} - /// One edge of one key, as a platform hands it to the loop: the canonical [`Action`] where the key /// has one, the [`Edge`], and the raw pair where the platform has one. /// @@ -253,6 +244,44 @@ fn host_event(decoded: Decoded) -> Option { }) } +/// What a platform's [`EventSink`](super::platform::EventSink) calls become: the [`HostEvent`]s the loop +/// ingests, in the order the platform made them. The one place a non-SDL platform's events become the +/// application's own type, beside [`host_event`] for SDL's (the two are the only constructors of a +/// [`HostEvent`], so the private event type has exactly two doors). A key goes through [`KeyPress::new`], +/// which refuses what is neither an action nor a pair, or an action and a pair that name two keys. +#[derive(Default)] +pub(crate) struct HostQueue(Vec); + +impl HostQueue { + /// The queued events, oldest first. + pub(crate) fn into_events(self) -> Vec { + self.0 + } +} + +impl super::platform::EventSink for HostQueue { + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool { + let Some(press) = KeyPress::new(action, edge, raw) else { return false }; + self.0.push(HostEvent::Key(press)); + true + } + fn text(&mut self, text: &str) { + self.0.push(HostEvent::Text(text.to_owned())); + } + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge) { + self.0.push(HostEvent::Pointer { x, y, edge }); + } + fn wheel(&mut self, dy: i32) { + self.0.push(HostEvent::Wheel { dy }); + } + fn lifecycle(&mut self, edge: Lifecycle) { + self.0.push(HostEvent::Lifecycle(edge)); + } + fn quit(&mut self) { + self.0.push(HostEvent::Quit); + } +} + /// **One native key edge as the loop hands it to the tree**, for the effect-level guards (W5b): the /// SDL bytes a television or the simulator delivers for the pair `(sym, wcode)` (the literals a /// test writes down, never an `Action`'s `raw_pair`), decoded by [`decode_host_event`], and the @@ -1214,3 +1243,84 @@ mod key_event_tests { assert_eq!(text(b""), Some(HostEvent::Text(String::new()))); } } + +/// A platform's `EventSink` calls become the same `HostEvent`s the SDL decode makes of the same events +/// (the one conversion a non-SDL platform's input goes through), in the order they were made, and a key +/// the application cannot name is refused, not queued. +#[cfg(test)] +mod host_queue_tests { + use super::super::platform::EventSink; + use super::{decode_host_event, encode_key, Action, Edge, HostEvent, HostQueue, KeyPress, Lifecycle, PointerEdge, RawKey}; + use plx_ui::consts::raw_pair; + + fn event_of(code: u32) -> [u8; 128] { + let mut ev = [0u8; 128]; + ev[..4].copy_from_slice(&code.to_ne_bytes()); + ev + } + + #[test] + fn quit_and_the_lifecycle_edges_queue_what_the_sdl_decode_makes_of_their_events() { + let mut queue = HostQueue::default(); + queue.quit(); + queue.lifecycle(Lifecycle::WillBackground); + queue.lifecycle(Lifecycle::DidBackground); + queue.lifecycle(Lifecycle::WillForeground); + queue.lifecycle(Lifecycle::DidForeground); + let decoded: Vec = + [0x100, 0x103, 0x104, 0x105, 0x106].iter().map(|&code| decode_host_event(&event_of(code)).expect("decoded")).collect(); + assert_eq!(queue.into_events(), decoded); + } + + #[test] + fn a_raw_pair_with_or_without_its_action_queues_the_press_the_sdl_decode_makes_of_those_bytes() { + let (sym, wcode) = raw_pair(Action::Ok); + let pair = RawKey { sym, wcode }; + let Some(decoded) = decode_host_event(&encode_key(sym, wcode, true)) else { panic!("a key event") }; + let mut queue = HostQueue::default(); + assert!(queue.key(None, Some(pair), Edge::Down), "a pair alone is a press"); + assert!(queue.key(Some(Action::Ok), Some(pair), Edge::Down), "and so is the pair with the action it names"); + assert_eq!(queue.into_events(), vec![decoded.clone(), decoded]); + } + + #[test] + fn an_action_alone_queues_a_press_whose_pair_is_the_one_a_remote_sends() { + let mut queue = HostQueue::default(); + assert!(queue.key(Some(Action::Back), None, Edge::Up)); + let want = KeyPress::new(Some(Action::Back), Edge::Up, None).expect("Back names a key"); + let events = queue.into_events(); + assert_eq!(events, vec![HostEvent::Key(want)]); + let HostEvent::Key(press) = &events[0] else { panic!("a key") }; + assert_eq!(press.pair(), RawKey { sym: raw_pair(Action::Back).0, wcode: raw_pair(Action::Back).1 }); + } + + #[test] + fn a_key_the_application_cannot_name_is_refused_and_queues_nothing() { + let (sym, wcode) = raw_pair(Action::Ok); + let mut queue = HostQueue::default(); + assert!(!queue.key(None, None, Edge::Down), "neither an action nor a pair"); + assert!(!queue.key(Some(Action::Digit(10)), None, Edge::Down), "no pair spells Digit(10)"); + assert!(!queue.key(Some(Action::Back), Some(RawKey { sym, wcode }), Edge::Down), "an action and a pair of two keys"); + assert!(queue.into_events().is_empty()); + } + + #[test] + fn text_pointer_and_wheel_queue_as_given_and_keep_their_order() { + let mut queue = HostQueue::default(); + queue.text("wal"); + queue.pointer(960.0, 540.0, PointerEdge::Down); + queue.wheel(-2); + queue.text(""); + queue.pointer(1.0, 2.0, PointerEdge::Up); + assert_eq!( + queue.into_events(), + vec![ + HostEvent::Text("wal".into()), + HostEvent::Pointer { x: 960.0, y: 540.0, edge: PointerEdge::Down }, + HostEvent::Wheel { dy: -2 }, + HostEvent::Text(String::new()), + HostEvent::Pointer { x: 1.0, y: 2.0, edge: PointerEdge::Up }, + ] + ); + } +} diff --git a/rust-modules/src/app/exit.rs b/rust-modules/src/app/exit.rs index f0ff5bf38..fbf5729d8 100644 --- a/rust-modules/src/app/exit.rs +++ b/rust-modules/src/app/exit.rs @@ -54,7 +54,7 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; /// Whether the application gave back every native resource it held before it returned. #[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) enum Release { +pub enum Release { /// The teardown ran to its end and released the window and the GL context. Complete, /// Something is still held: a native worker is inside firmware, or the boot refused before any @@ -65,15 +65,15 @@ pub(crate) enum Release { /// What `run_application` returns to its entry. #[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) struct Exit { +pub struct Exit { /// The process exit status: `1` after a failed recording or a refused boot, else `0`. - pub(crate) code: c_int, - pub(crate) release: Release, + pub code: c_int, + pub release: Release, } impl Exit { /// An early-boot refusal. Nothing was torn down, so nothing is released. - pub(crate) const fn refused(code: c_int) -> Self { + pub const fn refused(code: c_int) -> Self { Self { code, release: Release::Retained } } diff --git a/rust-modules/src/app/mod.rs b/rust-modules/src/app/mod.rs index 657912679..71fa616fa 100644 --- a/rust-modules/src/app/mod.rs +++ b/rust-modules/src/app/mod.rs @@ -78,7 +78,9 @@ mod hint_taught; mod recorder; mod window_activity; mod exit; -pub(crate) use exit::Exit; +// `pub`, not `pub(crate)`, because `host` re-exports them: a `pub use` cannot re-export a binding the crate +// only sees, and `app` itself is private, so this reaches no further than `host`. +pub use exit::{Exit, Release}; pub(crate) mod events; pub(crate) mod lifecycle; pub(crate) mod playback; diff --git a/rust-modules/src/app/platform.rs b/rust-modules/src/app/platform.rs index 7ff3228b1..6efe19bdb 100644 --- a/rust-modules/src/app/platform.rs +++ b/rust-modules/src/app/platform.rs @@ -20,12 +20,17 @@ //! platform composed through [`publish_composition`], the one function that does, so the set of //! installed drivers and the resolver the planner reads cannot disagree. //! -//! `Shell`, `Surface`, `FrameProbe` and `Platform` are app-private on purpose: no type a platform's shell has -//! to match leaves the application crate until the platform contract is settled. The webOS value is -//! built by `port.rs`; `ci/check-deps.sh`'s `frame` gate pins the call text of the three +//! These types are reachable from outside the application crate ONLY through the narrow `host` module +//! (`crate::host`, `docs/platform-ports.md`, Target shape 8), which re-exports them for a platform crate +//! to build its `static` `Platform` against: the application's general API stays private, and so does +//! `HostEvent` (a platform reports input through [`EventSink`], which the application converts). The webOS +//! value is built by `port.rs`; `ci/check-deps.sh`'s `frame` gate pins the call text of the three //! privileged calls (`pump_bus`, `opaque_route`, `clear_opaque_region`) to `app/run.rs`. use super::Exit; use plx_base::task::MainThread; +use plx_machine::machine::Edge; +use plx_shell_sdl::event::{Lifecycle, PointerEdge}; +use plx_ui::consts::{Action, RawKey}; use plx_media::player::adapter::PlayerAdapter; use plx_media::route::uri_preflight::ResolvePort; use plx_media::route::PlaybackSession; @@ -34,8 +39,8 @@ use std::os::raw::c_void; /// What a platform's boot asks of SDL, as plain data: [`InitHooks`] (the two steps a platform runs /// around `SDL_Init`), and [`OpenAsk`] with its [`Placement`] (the window's title, place and size). The -/// shell crate's own types, re-exported rather than copied: they hold no SDL type, and W7a, which -/// publishes `Shell` and `Surface`, is where a platform-neutral spelling of them is decided. +/// shell crate's own types, re-exported rather than copied: they hold no SDL type. `host` re-exports +/// `OpenAsk` and `Placement` for a platform crate (`InitHooks` stays here: only the SDL helpers below take it). pub(crate) use plx_shell_sdl::{InitHooks, OpenAsk, Placement}; /// The platform's window, bus and pointer, as the application drives them: the SDL window and its @@ -48,7 +53,7 @@ pub(crate) use plx_shell_sdl::{InitHooks, OpenAsk, Placement}; /// request first, the session read, then the window. That is the order boot has always had, and /// `app::boot` pins it. A platform whose surface is not SDL's states its own pair; every SDL one is the /// shell crate's (`plx_shell_sdl`), reached through [`sdl_init`] and [`sdl_open`]. -pub(crate) trait Shell: Sync { +pub trait Shell: Sync { /// Bring the platform's windowing up and ask for the GL context, once, FIRST: before the stored /// session is read and before [`open`](Shell::open). A refusal ends the boot with that `Exit`. fn init(&self, mt: &MainThread) -> Result<(), Exit>; @@ -88,24 +93,36 @@ pub(crate) trait Shell: Sync { } /// The window the application presents to and reads events from, owned by `App` for the rest of the -/// process. App-private and thread-affine (not `Sync`) like [`Shell`], and for the same reason: no -/// type a platform has to match leaves the application crate until the platform contract is settled -/// (`docs/platform-ports.md`, Target shapes 1 and 8, which W7a publishes as `host`). +/// process. Thread-affine (not `Sync`, unlike [`Shell`], which returns it from [`Shell::open`] on the loop +/// thread). Published only through `host` (`docs/platform-ports.md`, Target shapes 1 and 8). /// /// `window` is the raw handle the [`Shell`]'s per-window calls still take (`bind_window`, /// `grab_surface`, and `textinput`'s focus read), so every call site the `frame` gate pins stays where -/// it is; W7a folds those into this trait. `poll` is SDL-shaped bytes until the platform's own event -/// sink replaces it. There is no destructor: the `App` is leaked at exit and a worker may still hold -/// the handle, so the end is the explicit, decided [`quit`](Surface::quit). -pub(crate) trait Surface { +/// it is; W9 folds those into this trait (plan, §1). **Two event paths, one of them temporary:** a +/// platform delivers its events through [`deliver`](Surface::deliver) and [`EventSink`]; the SDL shells +/// still deliver through [`poll`](Surface::poll), SDL-shaped bytes, and their `deliver` delivers nothing. +/// `poll` is retired once the SDL shells deliver through the sink (W9 at the latest). There is no +/// destructor: the `App` is leaked at exit and a worker may still hold the handle, so the end is the +/// explicit, decided [`quit`](Surface::quit). +pub trait Surface { /// The raw window handle, null for a surface that has none (the rig's). fn window(&self) -> *mut c_void; /// Present the frame. The compositor commit of the opaque-region request just made is this call's. fn swap(&self); /// 1 locks the frame rate to the panel's refresh, 0 uncaps it; the application computes which. fn set_swap_interval(&self, interval: i32); - /// Take the next event off the platform's queue into `ev`; `false` when there is none. - fn poll(&self, ev: &mut [u8; 128]) -> bool; + /// Take the next event off the platform's queue into `ev`; `false` when there is none. SDL's bytes: + /// only the SDL shells have a queue of that shape, so it is hidden and defaults to none. Retired with + /// the second path ([`deliver`](Surface::deliver) is the one that stays). + #[doc(hidden)] + fn poll(&self, _ev: &mut [u8; 128]) -> bool { + false + } + /// Hand the platform's pending input and window events to `sink`, in order, on the loop thread: called + /// once per drain, after [`poll`](Surface::poll) has been emptied. A platform whose callbacks arrive on + /// another thread queues them and delivers them here. Required: a surface with nothing to deliver + /// states it, as the SDL one does (its events still come through `poll`). + fn deliver(&self, sink: &mut dyn EventSink); /// End the platform's windowing for the process. /// /// # Safety @@ -130,11 +147,36 @@ impl Surface for plx_shell_sdl::Window { fn poll(&self, ev: &mut [u8; 128]) -> bool { plx_shell_sdl::event::poll(ev) } + /// Nothing: every SDL event, a synthetic one the dev tooling pushed included, still comes through + /// [`poll`](Surface::poll) exactly as before, so the SDL event path is unchanged. + fn deliver(&self, _sink: &mut dyn EventSink) {} unsafe fn quit(&self) { plx_shell_sdl::init::quit() } } +/// What a platform reports to the loop through [`Surface::deliver`]: the public face of the application's +/// input vocabulary, whose own event type (`HostEvent`) stays private. Every call runs on the loop thread, +/// in the order the platform saw the events. The application converts each into its event, so a platform +/// names no application type beyond these. +pub trait EventSink { + /// One edge of a key: its canonical [`Action`] where it has one, the raw pair where the platform has + /// one, and the [`Edge`]. A platform that is not SDL sends the action alone. `false` when the press is + /// refused and dropped: it carries neither field, or an action that is not what the pair names, or an + /// action no pair spells (`Action::Digit` above 9). + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool; + /// One commit from the platform's text input, possibly empty. + fn text(&mut self, text: &str); + /// One pointer event at authored 1920x1080 coordinates. + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge); + /// One tick of the wheel, in signed whole ticks. + fn wheel(&mut self, dy: i32); + /// The window left or came back to the screen. + fn lifecycle(&mut self, edge: Lifecycle); + /// The host asks the application to end. + fn quit(&mut self); +} + /// [`Shell::init`] for an SDL platform: SDL up with the platform's two steps around `SDL_Init`, then the /// GL context request. `SDL_Init` refused ends the boot (`Exit::refused(1)`, the status it always had). /// @@ -165,7 +207,7 @@ pub(crate) fn detached_surface() -> Box { /// The dev frame probe (`/tmp/plxnative-framecb`): the platform's presentation-callback clock, read /// by the loop and by the renderer's clear hook. Unarmed, every call is a latched flag read. -pub(crate) trait FrameProbe: Sync { +pub trait FrameProbe: Sync { /// Ask for this frame's presentation callback. Call on a PRESENTING frame, before the swap. fn request(&self); /// `prepare_window` is next: starts the frame's `p` stretch. @@ -186,20 +228,20 @@ pub(crate) trait FrameProbe: Sync { /// /// `Composition::default()` is a platform that composed no URI driver (the Feed or nothing): no resolver. #[derive(Default)] -pub(crate) struct Composition { - pub(crate) resolver: Option, +pub struct Composition { + pub resolver: Option, } /// A platform's two playback steps at boot. Both are plain functions: the platform's entry states /// them once, in its `static`, and the boot calls them through [`Platform::media`]. -pub(crate) struct MediaBoot { +pub struct MediaBoot { /// Before the first adapter exists, once per process. The caller runs it only on a boot that /// touches the television (not a controlled one), so a platform's body never asks. - pub(crate) early_init: fn(&MainThread), + pub early_init: fn(&MainThread), /// Install this platform's drivers on the adapter, and return what the session must also be told. /// `controlled` is a replay or scripted Home, which touches no native port and so installs no /// native driver. It takes no session and publishes nothing: [`publish_composition`] does that. - pub(crate) compose: fn(&mut PlayerAdapter, controlled: bool) -> Composition, + pub compose: fn(&mut PlayerAdapter, controlled: bool) -> Composition, } /// Tell the route session what the platform composed: the resolver first, then the backend set the @@ -234,7 +276,7 @@ pub(crate) fn publish_composition( /// functions put their guards around them (`sound::output`'s blocking check, `secure`'s test store, /// `home`'s request counter). The one thing the application does with it is /// [`install_services`](Platform::install_services); nothing in `app` can call a hook directly. -pub(crate) struct Platform { +pub struct Platform { services: &'static Services, pub(crate) shell: &'static dyn Shell, pub(crate) diag: &'static dyn FrameProbe, @@ -243,7 +285,7 @@ pub(crate) struct Platform { impl Platform { /// A platform's entry states its four parts once, in a `static`. - pub(crate) const fn new( + pub const fn new( services: &'static Services, shell: &'static dyn Shell, diag: &'static dyn FrameProbe, @@ -469,6 +511,49 @@ mod tests { assert!(!other.shell.release_surface(), "the rest of the shell answers as the host-test one does"); } + /// **The SDL surface delivers nothing through its sink, so on the television and a desktop every event + /// still comes through `poll`, exactly as before.** An SDL key is pushed onto SDL's queue; the surface's + /// `deliver` reports none of it (the sink is called zero times), and `poll` still returns it. The + /// two-path drain therefore changes nothing for an SDL platform. + #[test] + fn the_sdl_surface_delivers_nothing_and_its_events_still_come_through_poll() { + #[derive(Default)] + struct Count(usize); + impl EventSink for Count { + fn key(&mut self, _: Option, _: Option, _: Edge) -> bool { + self.0 += 1; + true + } + fn text(&mut self, _: &str) { + self.0 += 1; + } + fn pointer(&mut self, _: f32, _: f32, _: PointerEdge) { + self.0 += 1; + } + fn wheel(&mut self, _: i32) { + self.0 += 1; + } + fn lifecycle(&mut self, _: Lifecycle) { + self.0 += 1; + } + fn quit(&mut self) { + self.0 += 1; + } + } + let _serial = plx_base::testlock::serial(); + let _events = plx_shell_sdl::testing::EventsOnly::init(); + let surface = detached_surface(); + let mut ev = [0u8; 128]; + while surface.poll(&mut ev) {} + plx_shell_sdl::inject::synth_key(plx_ui::consts::SDLK_UP, 0); + let mut count = Count::default(); + surface.deliver(&mut count); + assert_eq!(count.0, 0, "an SDL surface delivers nothing through the sink"); + assert!(surface.poll(&mut ev), "the pushed key is still the queue's, through `poll`"); + assert!(plx_shell_sdl::event::decode(&ev).is_some(), "and it decodes as before"); + assert!(!surface.poll(&mut ev), "and the queue is empty after it"); + } + /// **The SDL calls the application still declares are the two that stay.** Everything SDL-shaped /// that is the stock shell's (the window, the GL context, the queue, the text-input panel) is /// `plx_shell_sdl`'s; what remains is `system.rs`'s `SDL_GetWindowWMInfo` handshake (the television's diff --git a/rust-modules/src/app/run.rs b/rust-modules/src/app/run.rs index 2ef8d7fb0..891c4cf12 100644 --- a/rust-modules/src/app/run.rs +++ b/rust-modules/src/app/run.rs @@ -1071,6 +1071,21 @@ unsafe fn drain_sdl(app: &mut App, fr: &mut Frame) { while app.surface.poll(&mut app.ev) { ingest_sdl_event(app, fr); } + // The second path: what the platform's surface delivers through its sink. An SDL surface delivers + // nothing here (every SDL event came through `poll` above), so on the television and a desktop this + // is an empty queue; a surface that is not SDL's has no `poll` and only this. `poll` is retired once + // the SDL shells deliver through the sink (W9 at the latest, `docs/platform-ports.md`). + deliver_events(app, fr); +} + +/// Take what the surface delivers through its sink into the loop, in the order the platform made it. +unsafe fn deliver_events(app: &mut App, fr: &mut Frame) { + let mut queue = super::events::HostQueue::default(); + app.surface.deliver(&mut queue); + let shell = app.platform.shell; + for event in queue.into_events() { + ingest_host_event(app, fr, event, |win| shell.grab_surface(win)); + } } unsafe fn ingress_token(app: &mut App, fr: &mut Frame, token: &str) -> bool { @@ -4267,6 +4282,36 @@ pub(in crate::app) mod lifecycle_regression_tests { assert_eq!(second.runtime.bridge(&mut second.bridge).consent_subhash(), second_consent); } + /// A surface that is not SDL's: it has no queue to `poll` and delivers its one event, the host's + /// request to end, through the sink it is handed. + struct SinkSurface; + + impl crate::app::platform::Surface for SinkSurface { + fn window(&self) -> *mut c_void { + std::ptr::null_mut() + } + fn swap(&self) {} + fn set_swap_interval(&self, _interval: i32) {} + fn deliver(&self, sink: &mut dyn crate::app::platform::EventSink) { + sink.quit(); + } + unsafe fn quit(&self) {} + } + + /// **The loop drains a surface's sink**: `drain_sdl` hands the surface a sink, and what it delivers + /// is ingested like any event (here the host's request to end, `HostEvent::Quit`, which stops the loop). + /// A surface with no `poll` of its own reaches the loop only through this call. + #[test] + fn a_surface_that_delivers_through_its_sink_reaches_the_loop_through_drain_sdl() { + let _serial = plx_base::testlock::serial(); + let mut app = app(); + app.surface = Box::new(SinkSurface); + let mut fr = Frame::begin(&app.player.session, app.runtime.metadata_view()); + app.running = true; + unsafe { drain_sdl(&mut app, &mut fr) }; + assert!(!app.running, "the delivered quit ended the loop"); + } + fn frame(app: &mut App, now: u32) { super::super::bridge::app_frame( app, diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs new file mode 100644 index 000000000..21df7ed03 --- /dev/null +++ b/rust-modules/src/host.rs @@ -0,0 +1,42 @@ +//! The cross-crate construction interface: what a platform crate needs to build its `static` [`Platform`] +//! and hand it to the application (`docs/platform-ports.md`, Target shape 8). +//! +//! The application's modules are private (`mod app;`), so a crate that is a sibling of this one cannot +//! name `app::Platform` or implement a crate-private `Shell`. This is the one narrow public face: re-exports +//! of the types a platform builds or implements, an [`EventSink`] through which it reports input, and +//! [`run`], the one function in here (it hands the platform to the application's entry). Nothing else of +//! the application is public. `HostEvent`, the loop's own event type, stays private: a platform reports +//! input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 +//! amended): `Shell`, `Surface`, `Platform`, `Services`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` +//! and `Release` are reachable only through this module. +//! +//! The split is by thread. A [`Platform`] is registration data in a `static`: function pointers and +//! `&'static dyn` of `Sync` types, [`Shell`] included as a factory. The thread-affine state (the window, +//! the GL context, a toolkit's handles) lives only in the [`Surface`] that [`Shell::open`] returns on the +//! loop thread and that the application owns from then on. +//! +//! Beside the platform's own types, the vocabulary their signatures name is re-exported from the lower +//! layers it lives in ([`MainThread`], [`Action`], [`Edge`], [`RawKey`], [`Lifecycle`], [`PointerEdge`], +//! [`OpenAsk`], [`Placement`]), so a platform crate names the application's own types through `host` alone. +//! The two SDL helpers (`sdl_init`, `sdl_open`) are not here: W7b publishes what the two real platforms need. +use std::ffi::CStr; +use std::os::raw::c_int; + +pub use crate::app::platform::{Composition, EventSink, FrameProbe, MediaBoot, Platform, Shell, Surface}; +pub use crate::app::{Exit, Release}; +pub use plx_base::task::MainThread; +pub use plx_machine::machine::Edge; +pub use plx_os::tv::Services; +pub use plx_shell_sdl::event::{Lifecycle, PointerEdge}; +pub use plx_shell_sdl::{OpenAsk, Placement}; +pub use plx_ui::consts::{Action, RawKey}; + +/// Boot the application on `platform` and return the status it ended with: the application's entry +/// (`run_application`), which installs the platform's services, brings the window up through its +/// [`Shell`], runs the loop and tears down. Ending the process is the caller's, as for the television's +/// and the desktop's own entries: a process that hosts the application never does. +/// +/// `pms_host` and `pms_port` are the pair `plex_run` hands the entry and `platform_desktop::run` takes. +pub fn run(platform: &'static Platform, pms_host: &CStr, pms_port: u16) -> Exit { + crate::app::run_application(platform, pms_host.as_ptr(), c_int::from(pms_port)) +} diff --git a/rust-modules/src/lib.rs b/rust-modules/src/lib.rs index f1fe806ea..d0b9ddd74 100644 --- a/rust-modules/src/lib.rs +++ b/rust-modules/src/lib.rs @@ -19,6 +19,10 @@ mod capture; // dev live UI capture stream: own-GLES-frame grab → MPEG1/TS or mod coldstart; // retires old last-page bookmarks; authenticated cold boots now stay on Home mod dev; // the /tmp/plxnative-* trigger surface, behind one `devtriggers` feature — read it before adding a trigger mod focusprobe; // dev: one diffable line naming everything app.rs's key ladder can move, logged when it changes +/// The one narrow public face of the application for a platform crate: the types it builds and implements +/// (`Platform`, `Shell`, `Surface`, `EventSink`, ...) and the entry `run`, as re-exports. Everything else of +/// the application stays private (`docs/platform-ports.md`, Target shape 8). +pub mod host; // The simulator's HUD tools (`--hud-lint`, `--hud-schema`, `--hud-export`): a library function the thin // `src/bin/sim.rs` calls before it reads a PMS host. `pub` because that binary is a separate crate; absent // from the television build, which has no use for a linter and no argv to read it from. diff --git a/rust-modules/ui/src/consts.rs b/rust-modules/ui/src/consts.rs index 69a25e4a3..131c86548 100644 --- a/rust-modules/ui/src/consts.rs +++ b/rust-modules/ui/src/consts.rs @@ -491,6 +491,21 @@ pub fn is_remote_bound(sym: c_uint, wcode: c_uint) -> bool { action_of(sym, wcode).is_some() } +/// The raw `(sym, wcode)` pair a key arrived as. Kept beside the [`Action`] because three things +/// still read it: a press with no action (an unsupported key flows on as exactly the pair it was), +/// the lab trigger key (named by `lab.json`, not by an action), and the recorder's tape, whose +/// format IS the pair. A platform with no SDL pair sends none, and the loop builds [`raw_pair`] +/// for its action. +/// +/// It lives here, beside [`raw_pair`] and [`action_of`] whose pair it names, so a platform crate +/// reaches it without the application's private events module (`docs/platform-ports.md`, Target +/// shape 8: `host::EventSink::key` takes one). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct RawKey { + pub sym: c_uint, + pub wcode: c_uint, +} + /// **A key press by what it MEANS, with no SDL in it** — the vocabulary a platform that has no SDL /// key pair hands the loop (`HostEvent::Key`'s `action`), and the one the screens move onto when /// they stop reading `(sym, wcode)` themselves. From bb2578efe1d2e59b4aafeedb9657be69c5837f04 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 01:46:43 +0300 Subject: [PATCH 02/11] make test-host-interface runs the host interface from outside the crate, and check runs it too rust-modules/tests/host_interface.rs builds a static Platform from fakes and boots it through host::run to the fake shell's refusal. check-cargo-unit-hostsim gains the line, pinned in GATES. Co-Authored-By: Claude Sonnet 5.5 --- Makefile | 35 +++- ci/module-layers.ini | 5 +- ci/test_arm_profile.py | 2 +- ci/test_ci_split.py | 6 +- rust-modules/tests/host_interface.rs | 301 +++++++++++++++++++++++++++ 5 files changed, 341 insertions(+), 8 deletions(-) create mode 100644 rust-modules/tests/host_interface.rs diff --git a/Makefile b/Makefile index 53d366323..05d40698d 100644 --- a/Makefile +++ b/Makefile @@ -880,7 +880,7 @@ RUST_CFG = features:$(RUST_FEATFLAGS)$(if $(filter-out release,$(ARM_PROFI # goal in the two kinds above resets nothing under a dry run, and every goal named as NOT here stays out # of the list. The list is ONE line on purpose (`grep '^SIDE_EFFECT_FREE' Makefile` is the exact set, # and several tests read it that way). -SIDE_EFFECT_FREE = $(QUERY_GOALS) release-guard lab-guard disk disk-preflight build-bench build-bench-quick test-hostsim check-nodef test-fast test-crate fuzz-hud lint check-cargo-lint check-cargo-unit-hostsim check-localization check-c-unit check-python-harness notices notices-verify setup-rust setup-env disk-watch disk-watch-uninstall fixtures fixtures-quick fixtures-pipeline demo-library sim-token sim-macos-token sim-clean sim-macos-clean kill run run-stream verify-deploy uninstall fetch-profile softfloat-probe tv-lock-require +SIDE_EFFECT_FREE = $(QUERY_GOALS) release-guard lab-guard disk disk-preflight build-bench build-bench-quick test-hostsim test-host-interface check-nodef test-fast test-crate fuzz-hud lint check-cargo-lint check-cargo-unit-hostsim check-localization check-c-unit check-python-harness notices notices-verify setup-rust setup-env disk-watch disk-watch-uninstall fixtures fixtures-quick fixtures-pipeline demo-library sim-token sim-macos-token sim-clean sim-macos-clean kill run run-stream verify-deploy uninstall fetch-profile softfloat-probe tv-lock-require PURE_QUERY := $(if $(MAKECMDGOALS),$(if $(filter-out $(SIDE_EFFECT_FREE),$(MAKECMDGOALS)),,yes),) # `PLAYBACK_BACKENDS=none` builds no television package. It is refused HERE, at parse time and before # the stamp reset below: a recipe-level refusal ran after that reset, so a mistyped @@ -1583,7 +1583,7 @@ test: deploy run # it is not the table's value for that dir's name (tools/disk-budget.py NEED_GIB). `ci/test_disk_preflight.py` # finds every target whose recipe runs cargo and fails when one is missing from this list. DISK_ENTRIES = check check-replay check-cargo-lint check-cargo-unit-default check-cargo-unit-hostsim lint \ - test-fast test-crate test-hostsim check-nodef check-ass check-ffmpeg sim-macos sim-linux screenshots-sim site-video-sim \ + test-fast test-crate test-hostsim test-host-interface check-nodef check-ass check-ffmpeg sim-macos sim-linux screenshots-sim site-video-sim \ $(RUST_LIB) pkg/plxnative-storage macapp macapp-zip build-bench build-bench-quick fuzz-hud $(DISK_ENTRIES): | disk-preflight @@ -1591,7 +1591,7 @@ $(DISK_ENTRIES): | disk-preflight DISK_TREE = $(if $(CARGO_TARGET_DIR),$(if $(filter /%,$(CARGO_TARGET_DIR)),$(CARGO_TARGET_DIR),$(CURDIR)/rust-modules/$(CARGO_TARGET_DIR)),$(CURDIR)/rust-modules/target) DISK_NEED = test-fast test-crate: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_FAST_TDIR) -test-hostsim: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_HOSTSIM_TDIR) +test-hostsim test-host-interface: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_HOSTSIM_TDIR) # The fuzz tree (ASan + coverage, release with debuginfo, ten binaries): 3.1 GiB measured after a cold build # of the first eight; the ninth, `ws_frame`, adds 83 MiB, and the tenth, `owp_json`, 49 MiB with `plx_owp` # (measured on Linux x86_64). @@ -1807,11 +1807,19 @@ check-cargo-unit-hostsim: @# was invisible to all 1398 default-feature tests because the seam it needs was not there. @# Cargo keys fingerprints by feature set, so the two configurations coexist in one target/ and @# this costs a few seconds warm rather than a rebuild. + @# The second cargo line is W7a's gate and a test executable of its own (`--lib` never builds an integration test): + @# `rust-modules/tests/host_interface.rs` uses the application crate's `host` module from outside the crate and boots + @# a fake platform to its shell's refusal. It needs `hostsim` and a throwaway runtime root, which this pass has; + @# `make test-host-interface` is the same line as an incremental loop. @set -e; d=$$(mktemp -d /tmp/plxnative-check.XXXXXX); trap 'rm -rf "'"$$d"'"' EXIT; \ cd rust-modules && PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ $(TELEMETRY_ENV) \ $(HOST_ENV) \ - $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim; \ + PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ + $(TELEMETRY_ENV) \ + $(HOST_ENV) \ + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test -p plxnative-modules --test host_interface --features hostsim # OPT-IN incremental inner loop: the default-feature unit suite (the same `cargo test --lib` as # `check-cargo-unit-default`, same throwaway runtime root and telemetry env) with @@ -1906,6 +1914,25 @@ test-hostsim: $(HOST_ENV) \ $(UNIT_RUN) --require-match $(if $(T),--filter '$(T)') -- cargo +$(RUST_TOOLCHAIN) test --lib $(addprefix -p ,$(HOSTSIM_PKGS)) --features hostsim +# `make test-host-interface` -- W7a's gate (docs/platform-ports.md, Target shape 8): the application crate's `host` +# module used from OUTSIDE the crate. `rust-modules/tests/host_interface.rs` is an integration test, a crate of its own +# that can name only the `pub` items of `plxnative_modules`. It builds a `static Platform` from a fake `Shell`, `Surface` +# and `FrameProbe` and boots it through `host::run` to the fake shell's refusal of the window (the boot cannot go +# further without a GL context). It needs `hostsim`: only there is the runtime root steerable, so the boot's logs land +# in the throwaway directory below. The incremental loop, in `rust-modules/$(TEST_HOSTSIM_TDIR)` beside `make test-hostsim` +# (same feature set, same tree); `make check` runs the same test non-incrementally in `check-cargo-unit-hostsim`. +# Refused under RELEASE=1 like `test-hostsim`. +.PHONY: test-host-interface +test-host-interface: + @$(if $(RELEASE),echo "make test-host-interface: refused under RELEASE=1 -- it runs the default-plus-hostsim feature set incrementally; RELEASE=1 is the shipping feature set (use make check-nodef for that)." >&2; exit 1,:) + @echo "test-host-interface: the host interface test of plxnative-modules in rust-modules/$(TEST_HOSTSIM_TDIR) -- see 'make disk'" + @set -e; d=$$(mktemp -d /tmp/plxnative-check.XXXXXX); trap 'rm -rf "'"$$d"'"' EXIT; \ + cd rust-modules && CARGO_INCREMENTAL=1 CARGO_TARGET_DIR=$(TEST_HOSTSIM_TDIR) \ + PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ + $(TELEMETRY_ENV) \ + $(HOST_ENV) \ + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test -p plxnative-modules --test host_interface --features hostsim + # `make fuzz-hud [T=] [SECS=60]` -- the `cargo fuzz` package over every parser a HUD package or the # registry reaches (`fuzz/`: its own workspace, outside rust-modules, so nothing shipped names it). T is one # or more targets (`python3 tools/fuzz-hud.py list`), default all; SECS is the time per target, run one after diff --git a/ci/module-layers.ini b/ci/module-layers.ini index c51584367..469398249 100644 --- a/ci/module-layers.ini +++ b/ci/module-layers.ini @@ -201,11 +201,12 @@ uses = base machine os gfx net plex telemetry ui data session media appkit play_ members = screens [app] -# The loop, its adapters and every dev/diagnostic surface; lib.rs's own items are the facade. +# The loop, its adapters and every dev/diagnostic surface; lib.rs's own items are the facade. `host` is the +# one doorway a platform crate names (re-exports of the construction interface, and `run`). uses = base machine os gfx net plex telemetry ui data session media appkit screens shell_sdl playback_contract play_uri play_feed media_codecs members = crate app dev lab capture remote focusprobe hud_cli hud_tools shot coldstart textinput system release_line port - platform_desktop + platform_desktop host [platform webos] # Not a layer: the modules that exist only because the target is webOS. Identity, capability and diff --git a/ci/test_arm_profile.py b/ci/test_arm_profile.py index b92b646a7..644dd6d5a 100644 --- a/ci/test_arm_profile.py +++ b/ci/test_arm_profile.py @@ -110,7 +110,7 @@ def test_the_profile_is_part_of_the_stamp_only_when_it_is_not_release(self): # `check-cargo-unit-hostsim` and `check-python-harness` (tests/test_harness.py alone). `test-hostsim` # and `check-nodef` were the first two to be listed. `fuzz-hud` runs tools/fuzz-hud.py (a cargo tree # under rust-modules/ and files under fuzz/); it reads nothing the stamp guards. - "test-hostsim", "check-nodef", "test-fast", "test-crate", "fuzz-hud", "lint", "check-cargo-lint", "check-cargo-unit-hostsim", + "test-hostsim", "test-host-interface", "check-nodef", "test-fast", "test-crate", "fuzz-hud", "lint", "check-cargo-lint", "check-cargo-unit-hostsim", "check-localization", "check-c-unit", "check-python-harness", # the documentation tables "notices", "notices-verify", diff --git a/ci/test_ci_split.py b/ci/test_ci_split.py index 173fb1ebd..113602ecf 100644 --- a/ci/test_ci_split.py +++ b/ci/test_ci_split.py @@ -64,7 +64,11 @@ def rule(target): r"ci/test_no_host_staticlib\.py", r"ci/test_build_not_always_dirty\.py", ], - "check-cargo-unit-hostsim": [r"cargo \+\$\(RUST_TOOLCHAIN\) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim"], + "check-cargo-unit-hostsim": [ + r"cargo \+\$\(RUST_TOOLCHAIN\) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim", + # W7a: the `host` module used from outside the crate (`make test-host-interface` is the same line) + r"cargo \+\$\(RUST_TOOLCHAIN\) test -p plxnative-modules --test host_interface --features hostsim", + ], } diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs new file mode 100644 index 000000000..c16bb67ac --- /dev/null +++ b/rust-modules/tests/host_interface.rs @@ -0,0 +1,301 @@ +//! W7a's gate: a platform built against `plxnative_modules::host` alone (`docs/platform-ports.md`, +//! Target shape 8). +//! +//! This is an integration test, a separate crate that can name only the `pub` items of the application +//! crate, which is the point: a platform crate that is a sibling of the application has the same view. It +//! builds a `static PLATFORM` from a fake `Shell`, `Surface` and `FrameProbe` and boots it. +//! +//! **What "boots it" can mean here.** The real `run_application` runs, through [`host::run`], up to the +//! fake's `Shell::open`, which refuses: the boot ends with that `Exit`. It cannot go further, and no +//! fake could take it further: after `open` the boot makes real GL calls (`init_gl` links the renderer's +//! programs), which need a current GL context, and a surface that is not a real window has none. So this +//! test proves the construction interface and the boot order (the services installed, `init` before +//! `open`, `open` asked for the window the application means to ask for, the refusal returned as the +//! entry's `Exit`), not the loop. The loop's own fake-surface tests are in-crate (`make test-hostsim`). +//! +//! **The boot test needs `hostsim`** (the recipe `make test-host-interface` passes it): only there is the +//! runtime root steerable by `PLXNATIVE_RUNTIME_DIR`, so the boot's event log, crash log and diagnostics +//! land in a throwaway directory and not in a real install's. It refuses to run without that variable. +//! The rest of the file compiles in every configuration (`make lint` and `check-cargo-lint` build it), +//! which type-checks the interface from outside in the default non-hostsim feature set too. +//! +//! The application replaces the process's panic hook while it boots (`install_panic_logger`): it wraps +//! the previous hook, so a panic still reaches the test harness, and additionally writes one line to the +//! event log and the crash log in the runtime root. Only one test here boots, because the services are +//! installed once per process. +#![cfg_attr(not(feature = "hostsim"), allow(dead_code))] + +use plxnative_modules::host::{ + Action, Composition, Edge, EventSink, Exit, FrameProbe, Lifecycle, MainThread, MediaBoot, OpenAsk, Placement, + Platform, PointerEdge, RawKey, Services, Shell, Surface, +}; +#[cfg(feature = "hostsim")] +use plxnative_modules::host::Release; +use std::ffi::c_void; +#[cfg(feature = "hostsim")] +use std::ffi::CString; +use std::sync::Mutex; + +/// The refusal the fake `open` ends the boot with: a status no real refusal uses. +const REFUSAL: i32 = 73; + +/// Fake services: the production tables' `NONE` groups, and one hook of its own, so the test can see that +/// the platform's table was the one installed. +static SERVICES: Services = Services { + identity: plx_os::tv::IdentityHooks { system_locale: fake_locale, ..plx_os::tv::IdentityHooks::NONE }, + secure: plx_os::tv::SecureHooks::NONE, + system: plx_os::tv::SystemHooks::NONE, + storage: plx_os::tv::StorageHooks::NONE, + legacy_webos_media: plx_os::tv::LegacyWebosMedia::NONE, +}; + +fn fake_locale() -> plx_os::tv::LocaleReply { + plx_os::tv::LocaleReply::Reply("fake-host-locale".into()) +} + +/// A `Shell` of `Sync` state alone: an ordered call log and the window it was asked to open. +struct FakeShell { + log: Mutex>, + /// The window `open` was asked for: its title, placement and HiDPI flag. + asked: Mutex>, +} + +impl FakeShell { + fn note(&self, what: &'static str) { + self.log.lock().unwrap().push(what); + } +} + +impl Shell for FakeShell { + fn init(&self, _mt: &MainThread) -> Result<(), Exit> { + self.note("init"); + Ok(()) + } + fn open(&self, _mt: &MainThread, ask: &OpenAsk) -> Result, Exit> { + self.note("open"); + *self.asked.lock().unwrap() = Some((ask.title.to_string_lossy().into_owned(), ask.placement, ask.high_dpi)); + Err(Exit::refused(REFUSAL)) + } + fn bind_window(&self, _win: *mut c_void) { + self.note("bind_window"); + } + fn grab_surface(&self, _win: *mut c_void) { + self.note("grab_surface"); + } + fn release_surface(&self) -> bool { + self.note("release_surface"); + false + } + fn arm_opaque_region(&self) { + self.note("arm_opaque_region"); + } + fn opaque_route(&self, _player: bool) { + self.note("opaque_route"); + } + fn clear_opaque_region(&self) { + self.note("clear_opaque_region"); + } + fn pump_bus(&self) { + self.note("pump_bus"); + } + fn hide_pointer(&self) { + self.note("hide_pointer"); + } + fn show_pointer_after_motion(&self) { + self.note("show_pointer_after_motion"); + } + fn hide_is_cursor_swap(&self) -> bool { + false + } +} + +static SHELL: FakeShell = FakeShell { log: Mutex::new(Vec::new()), asked: Mutex::new(None) }; + +struct FakeProbe; + +impl FrameProbe for FakeProbe { + fn request(&self) {} + fn prepare_begin(&self) {} + fn prepare_end(&self) {} + fn waiting(&self) {} + fn acquired(&self) {} + fn fields(&self) -> String { + String::new() + } +} + +/// A surface that is not SDL's: it has no queue of bytes (`poll` is left at its default) and delivers its +/// events through the sink. Thread-affine state is its own (`!Sync`: a `Cell`), as a toolkit's would be. +struct FakeSurface { + frames: std::cell::Cell, +} + +impl Surface for FakeSurface { + fn window(&self) -> *mut c_void { + std::ptr::null_mut() + } + fn swap(&self) { + self.frames.set(self.frames.get() + 1); + } + fn set_swap_interval(&self, _interval: i32) {} + fn deliver(&self, sink: &mut dyn EventSink) { + sink.lifecycle(Lifecycle::DidForeground); + sink.pointer(10.0, 20.0, PointerEdge::Move); + sink.wheel(-1); + sink.text("ok"); + assert!(sink.key(Some(Action::Ok), None, Edge::Down), "an action alone is a key"); + assert!(!sink.key(None, None, Edge::Down), "a key of neither action nor pair is refused"); + sink.quit(); + } + unsafe fn quit(&self) {} +} + +fn early_init(_mt: &MainThread) {} + +fn compose(_adapter: &mut plx_media::player::adapter::PlayerAdapter, _controlled: bool) -> Composition { + Composition::default() +} + +/// The platform, as a sibling crate states it: a `static`, so every part of it is `Sync`. +static PLATFORM: Platform = + Platform::new(&SERVICES, &SHELL, &FakeProbe, MediaBoot { early_init, compose }); + +fn assert_sync(_: &T) {} + +/// The registration data is `Sync` (a `static` of it compiles), and the thread-affine surface is not +/// required to be: a `Surface` holding a `Cell` is accepted as `Box`. +#[test] +fn the_platform_is_registration_data_and_the_surface_may_be_thread_affine() { + assert_sync(&PLATFORM); + let surface: Box = Box::new(FakeSurface { frames: std::cell::Cell::new(0) }); + surface.swap(); + surface.set_swap_interval(1); + assert!(surface.window().is_null()); + let mut ev = [0u8; 128]; + assert!(!surface.poll(&mut ev), "a surface with no SDL queue has nothing to poll"); +} + +/// What a fake surface delivers is what its `EventSink` receives, in order, from outside the crate: the +/// sink is implementable here with the public vocabulary alone. +#[test] +fn an_event_sink_is_implementable_from_outside_and_receives_a_surfaces_events_in_order() { + #[derive(Default)] + struct Recorder(Vec); + impl EventSink for Recorder { + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool { + self.0.push(format!("key {action:?} {raw:?} {edge:?}")); + action.is_some() || raw.is_some() + } + fn text(&mut self, text: &str) { + self.0.push(format!("text {text}")); + } + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge) { + self.0.push(format!("pointer {x} {y} {edge:?}")); + } + fn wheel(&mut self, dy: i32) { + self.0.push(format!("wheel {dy}")); + } + fn lifecycle(&mut self, edge: Lifecycle) { + self.0.push(format!("lifecycle {edge:?}")); + } + fn quit(&mut self) { + self.0.push("quit".into()); + } + } + let surface = FakeSurface { frames: std::cell::Cell::new(0) }; + let mut sink = Recorder::default(); + surface.deliver(&mut sink); + assert_eq!( + sink.0, + [ + "lifecycle DidForeground", + "pointer 10 20 Move", + "wheel -1", + "text ok", + "key Some(Ok) None Down", + "key None None Down", + "quit", + ] + ); +} + +/// **The one source rule of this file** (it is how "against `host` alone" is held): every path into the +/// application crate starts `plxnative_modules::host`. The lower-layer crates a platform crate lists as its +/// own dependencies (`plx_os`, `plx_media`) are fine to name; the application's private modules are not +/// reachable, and this keeps a future edit from reaching for a re-export that would widen the surface. +#[test] +fn every_path_into_the_application_crate_goes_through_host() { + let source = include_str!("host_interface.rs"); + // Split, so this test's own text never matches. + let needle = concat!("plxnative_", "modules::"); + let mut seen = 0; + for (at, _) in source.match_indices(needle) { + seen += 1; + let line = source[..at].matches('\n').count() + 1; + assert!(source[at + needle.len()..].starts_with("host"), "line {line}: a path into the application crate that is not `host`'s"); + } + assert!(seen > 0, "the scan found no path at all: it is not reading this file"); +} + +/// The entries of `dir` whose name starts with `plxnative-`, sorted. +#[cfg(feature = "hostsim")] +fn plxnative_entries(dir: &std::path::Path) -> Vec { + let mut names: Vec = std::fs::read_dir(dir) + .map(|rd| { + rd.filter_map(|e| e.ok()) + .map(|e| e.file_name().to_string_lossy().into_owned()) + .filter(|n| n.starts_with("plxnative-")) + .collect() + }) + .unwrap_or_default(); + names.sort(); + names +} + +/// **The boot of the fake platform, to its refusal.** The real `run_application` runs on `PLATFORM`: +/// it installs the platform's services, brings the shell up (`init`), reads the stored session, then asks +/// the shell for the window (`open`), which refuses. The test asserts the order, the window asked for, the +/// installed services and the returned `Exit`, and that the boot created nothing named `plxnative-*` in `/tmp` +/// (where a device's trigger files live) outside the throwaway runtime root. +#[cfg(feature = "hostsim")] +#[test] +fn run_boots_the_fake_platform_through_init_then_open_and_returns_the_refusal() { + let runtime = std::env::var_os("PLXNATIVE_RUNTIME_DIR").map(std::path::PathBuf::from).expect( + "PLXNATIVE_RUNTIME_DIR must name a throwaway directory: this test boots the application, which writes \ + its logs and reads its triggers under the runtime root (`make test-host-interface` sets it)", + ); + assert!(runtime.is_dir(), "the runtime root {} is not a directory", runtime.display()); + let tmp = std::path::Path::new("/tmp"); + // The recipe's own throwaway directories (`plxnative-check.XXXXXX`) come and go with other runs. + let outside = |names: Vec| -> Vec { + names.into_iter().filter(|n| !n.starts_with("plxnative-check.")).collect() + }; + let tmp_before = outside(plxnative_entries(tmp)); + let runtime_before = std::fs::read_dir(&runtime).map(|rd| rd.count()).unwrap_or(0); + + let host = CString::new("127.0.0.1").unwrap(); + let exit = plxnative_modules::host::run(&PLATFORM, &host, 32400); + + assert_eq!(exit, Exit { code: REFUSAL, release: Release::Retained }, "the fake's refusal is the entry's Exit"); + assert_eq!(*SHELL.log.lock().unwrap(), ["init", "open"], "init, then open, and nothing after the refusal"); + let (title, placement, high_dpi) = SHELL.asked.lock().unwrap().clone().expect("open was asked for a window"); + assert_eq!(title, "PlxNative", "the title a hostsim build asks for"); + assert_eq!(placement, Placement::Desktop, "a hostsim build asks for the desktop placement"); + eprintln!("open was asked for: title {title:?}, {placement:?}, high_dpi {high_dpi}"); + assert!( + matches!(plx_os::tv::system_locale(), plx_os::tv::LocaleReply::Reply(ref l) if l == "fake-host-locale"), + "the services the application installed are the platform's own table" + ); + + let tmp_after = outside(plxnative_entries(tmp)); + let runtime_after: Vec = std::fs::read_dir(&runtime) + .unwrap() + .filter_map(|e| e.ok()) + .map(|e| e.file_name().to_string_lossy().into_owned()) + .collect(); + eprintln!("/tmp/plxnative-* (outside plxnative-check.*) before: {tmp_before:?}"); + eprintln!("/tmp/plxnative-* (outside plxnative-check.*) after: {tmp_after:?}"); + eprintln!("runtime root {}: {runtime_before} entries before, after: {runtime_after:?}", runtime.display()); + let created: Vec<&String> = tmp_after.iter().filter(|n| !tmp_before.contains(n)).collect(); + assert!(created.is_empty(), "the boot created {created:?} in /tmp, outside the runtime root"); +} From 256ec7cdf018cb0a5ea4e432a333e35844eb039e Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 01:46:43 +0300 Subject: [PATCH 03/11] The plan, the layer docs and the reviewer note say what W7a published Co-Authored-By: Claude Sonnet 5.5 --- .agents/agents/fw-compat-reviewer.md | 2 +- docs/agent-reference.md | 18 +++++++ docs/module-layers.md | 6 +-- docs/platform-ports.md | 74 +++++++++++++++++++--------- 4 files changed, 72 insertions(+), 28 deletions(-) diff --git a/.agents/agents/fw-compat-reviewer.md b/.agents/agents/fw-compat-reviewer.md index 30f2bd3af..408369885 100644 --- a/.agents/agents/fw-compat-reviewer.md +++ b/.agents/agents/fw-compat-reviewer.md @@ -128,7 +128,7 @@ into `dynlib!` **trades link-time symbol checking away** for version tolerance a it where the version actually varies. If a diff moves a stable library there, push back and ask for the `--inventory` output that justifies it. The precedent for the other direction is `rust-modules/shell-sdl/src/sys.rs`: plain `extern "C"` (the `SDL_*TextInput*` calls among them), -justified in its module doc by all 14 inventories exporting the whole SDL2 family it names. +justified in its module doc by all 14 inventories exporting every name outside its `hostsim` block. ## WHAT `fwcompat.py` NEEDS BEFORE IT WILL ANSWER — settle this first, not at your third command diff --git a/docs/agent-reference.md b/docs/agent-reference.md index e66f45810..3dfb283e5 100644 --- a/docs/agent-reference.md +++ b/docs/agent-reference.md @@ -333,6 +333,24 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y `CARGO_TARGET_DIR` at a `/tmp` directory: those trees were not in any checkout, so no tool counted or reclaimed them (28 of them, 45.6 GiB, were found in `/tmp` on 2026-10-19). Refused under `RELEASE=1`; `ci/test_managed_targets.py` pins that the target dir is inside the checkout. +- `make test-host-interface` — W7a's gate (`docs/platform-ports.md`, Target shape 8): the application crate's + `host` module (`rust-modules/src/host.rs`, the one path a platform crate names) used from OUTSIDE the crate by + `rust-modules/tests/host_interface.rs`, an integration test and so a crate of its own. It builds a `static + Platform` from a fake `Shell`, `Surface` and `FrameProbe`, boots it through `host::run` (the real + `run_application`) and asserts that `init` ran before `open`, the `OpenAsk` the application made, and the fake's + refusal returned as the entry's `Exit`. The boot cannot go further: after `open` it makes real GL calls, and a fake + surface has no GL context (nothing stubs GL under `test-support`), so frames and the loop are graded by the + in-crate tests of `make test-hostsim`, not here. It needs `hostsim`, because only there does `PLXNATIVE_RUNTIME_DIR` + steer the runtime root, so the boot's event log and crash log land in the recipe's throwaway directory; the boot + replaces the process's panic hook (`install_panic_logger`, which wraps the previous hook and also writes the + event and crash logs), and only one test in the file boots, because the platform's services install once per + process. The file also holds a source scan that every path into the application crate starts + `plxnative_modules::host`. Same shape as `test-hostsim`: incremental in `rust-modules/target-hostsim`, through + `$(UNIT_RUN)` (a `--test` line is passed through), refused under `RELEASE=1`, in `SIDE_EFFECT_FREE` and + `DISK_ENTRIES`. `make check` runs the same test non-incrementally as the second cargo line of + `check-cargo-unit-hostsim` (`--lib` never builds an integration test), pinned in `ci/test_ci_split.py`'s `GATES`. + The file needs no `[[test]]` entry (cargo finds `rust-modules/tests/*.rs`), so the root manifest and the + `ci/proofs` certificates that hash it are unchanged. - `make fuzz-hud [T= ...] [SECS=60]` — the `cargo fuzz` package over every parser a HUD package or the registry reaches (`docs/hud-plugins.md`, threat model): `admit` (the whole admission path), `bundle_read`, `archive_read` (the 1.0 ZIP container), `svg_check` (the SVG gate in front of nanosvg), diff --git a/docs/module-layers.md b/docs/module-layers.md index 5091866d8..7d49c6900 100644 --- a/docs/module-layers.md +++ b/docs/module-layers.md @@ -136,7 +136,7 @@ base | media | `ff` (a facade over `play_feed`'s demuxer) `abr curlio player route speed_audio`; `aq` and `hls` moved to `play_feed` | 56k | 49% | | appkit | `appkit` (the player panels and the Sources row several screens draw) | 13k | 32% | | screens | `screens` | 54k | 28% | -| app | `crate app dev lab capture remote focusprobe shot coldstart textinput system release_line port` | 42k | 12% | +| app | `crate app dev lab capture remote focusprobe shot coldstart textinput system release_line port host` | 42k | 12% | "Prod lines" counts files that are not wholly `cfg(test)`, measured after L14. The last column is the share of all production lines in that layer plus every layer above it. Line counts stand in @@ -207,7 +207,7 @@ on the device, stock SDL2 under `hostsim`), the synthetic key, pointer, wheel an into the queue (a text event is built as bytes and handed to the decode, never pushed: pushing one crashes the Mac's SDL), and the text-input calls. The LG half does not move: the `SDL_SysWMinfo` buffer, the `wl_proxy_marshal` opaque region and the LS2 pump stay in `system.rs`, a member of `[platform webos]`, and a pin in the crate's `lib.rs` fails if the crate names the query that overruns it. The application reaches it through `app/platform.rs`, whose `Shell` opens a -`Surface` over the crate's `Window`; `Shell`, `Surface` and `HostEvent` stay application-private until W7a. +`Surface` over the crate's `Window`; `HostEvent` stays application-private, and `Shell` and `Surface` are reachable only through the application crate's `host` module (W7a). `ci/check-deps.sh` reads the whole crate for the same clock, statics and thread gates as every other layer, and not as one of the sans-IO areas: the shell is an IO crate by definition. @@ -347,7 +347,7 @@ proves the references are gone and nothing more; L15b is open. | **L15b** the OS-neutral port — **open** | — | An OS-neutral video sink with the ACB bind sequence behind it and the webOS facts the gate cannot see; the simulator became its own platform in W4. See below. | | **L15c** the platform value and the three contracts — **done** | — | Wave R (the rename that gave this page `os` and `[platform webos]`) landed as #1474; W2 landed (`tv::Port` became `tv::Services`, with four groups of hooks; the shell and the frame probes moved to `app::Platform`), and so did the three contracts, W3a to W3c: who may persist credentials (#1477), what evidence admits a URI player (#1478), who ends the process (#1479). See "L15c to L15h" below. | | **L15d** neutral types and the simulator as its own platform (L15b item 2) — **W3d and W4 landed** | — | W3d landed (the opaque `Backend` tag, `sandbox` to `native_video`, identity publishes a platform name and version, `device::Info` keeps its webOS fields in `WebosDetail`, and `devcaps` reads its files through the platform), and so did W4: `platform_desktop` (`rust-modules/src/platform_desktop.rs`, a second fence section, `[platform desktop]`) is the simulator's and the macOS app's own platform value, which `src/bin/sim.rs` enters through; the `hostsim` terms of the television's fence are gone, so the television's code is compiled into every build and the linker drops it from a desktop executable (`simulators.yml` links the macapp feature set to guard that until W7), and the stand-ins in `webos` and `keymanager` are test seams, compiled for tests and `test-support` (`docs/platform-ports.md`, W4). The desktop platform is the second implementation. | -| **L15e** events, the shell and composition — **W5a to W5c, W6 and W6b landed** | — | W5 (`HostEvent` with `Option`) landed in three PRs, lifecycle and quit (W5a, #1484), keys and text (W5b, #1487) and the pointer and wheel (W5c, #1492), and so did W6b (platform-supplied composition in two boot phases, #1489) and W6 (`plx_shell_sdl`, a `[shell_sdl]` layer: SDL's bring-up, the window, the swap, the event decode and the text-input calls moved out of the application behind its private `Shell` and `Surface`, and the LG half stays in `system.rs`). W6c (a URI-only and a two-driver composition play an ordinary title) is planned. | +| **L15e** events, the shell and composition — **W5a to W5c, W6, W6b, W6c and W7a landed** | — | W5 (`HostEvent` with `Option`) landed in three PRs, lifecycle and quit (W5a, #1484), keys and text (W5b, #1487) and the pointer and wheel (W5c, #1492), and so did W6b (platform-supplied composition in two boot phases, #1489) and W6 (`plx_shell_sdl`, a `[shell_sdl]` layer: SDL's bring-up, the window, the swap, the event decode and the text-input calls moved out of the application behind its private `Shell` and `Surface`, and the LG half stays in `system.rs`). W6c (a URI-only and a two-driver composition play an ordinary title) landed (#1494), and W7a published the construction interface through `plxnative_modules::host` alone (`rust-modules/src/host.rs`, tested from outside the crate by `rust-modules/tests/host_interface.rs`, `make test-host-interface`). | | **L15f** extract the platform crates — **planned** | — | W7: a narrow public `host` module in the application crate, `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h (the storage-authority part of W8a, #1488, #1490 and #1491, landed ahead of W7; the rest of W8 still follows W7). | | **L15g** the webOS facts and the remaining `hostsim` (L15b item 3) — **W8a started** | — | W8a has begun: the platform states where the account's records live (`tv::Services.storage`, #1488), and telemetry's consent store (#1490) and plex's session persistence (#1491) follow it instead of the `target_arch = "arm"` fence. Still planned: the rest of W8a, one PR per directory (`os`, `src`, `base`, `storage` and `play-feed`; telemetry's nine `target_arch = "arm"` lines in `telemetry/src/telemetry/native.rs`, the Sentry Native crash capture, are not among them and no step owns them yet, the follow-up for Tizen ARM retail builds that #1490 names), sorting the `target_arch = "arm"` and `target_os = "linux"` sites into "is webOS" (a platform value or runner) and "is 32-bit ARM" or "is Linux" (stays); then W8b, the library name lists, `paths` and the packaging, and W8c, the `feature = "hostsim"` lines left in the tree (none of them in the fence now; `git grep -h 'feature = "hostsim"' -- '*.rs' | wc -l` counts them). | | **L15h** the OS-neutral Feed sink (L15b item 1) — **planned** | — | W11: `plx_acb` (an `[acb]` layer) takes the ACB plane owner and the URI media verbs out of `os`, the Feed-side ACB results become neutral, and the bind sequence moves behind a neutral sink. Needs the television. | diff --git a/docs/platform-ports.md b/docs/platform-ports.md index c236b7001..dac95ac1e 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -894,17 +894,20 @@ There is no `default_backend` (review M8, critic M1): the backend set is derived `Shell` (the factory) opens the loop's `Surface`: `create_surface`, `make_current`, `swap`, `drawable_size`, `gl_proc_address`; `release`/`reacquire` around background; `video_hole(Option)`, which replaces `arm_opaque_region`, `opaque_route` and `clear_opaque_region`; `pump()`, which replaces `pump_bus`. The trait doc -states which thread runs each call (Target shape 7). `Shell`, `Surface` and `HostEvent` stay app-private until -H1 and H2 return (critic M5; H3, H4 and H5 returned on the emulator only, E6, E8, E10; Decision 3, A): code moves -now, but no type a Samsung shell must match leaves the app crate; Target shape 8 is the one narrow, public -construction interface. The dispatcher's rig hooks (`ui/src/dispatch.rs:728-730`) keep delegating through -`run::rig_*`. +states which thread runs each call (Target shape 7). `Shell`, `Surface` and `HostEvent` stayed app-private until +H1 and H2 return (critic M5; H3, H4 and H5 returned on the emulator only, E6, E8, E10; Decision 3, A). The owner then +ruled (2026-11-21, Decision 3 amended) that `Shell` and `Surface`, with the rest of the construction interface, +are reachable ONLY through `plxnative_modules::host` (Target shape 8), never as general `pub` items of the +application crate; `HostEvent` stays app-private, and a platform reports input through `EventSink`. W7a publishes +today's `Shell` (12 methods) and `Surface` (5, plus `deliver`) as they are; the fold toward the shape above (one +`Surface`, `video_hole`, `pump`) is W9's, which is the first change with a second implementation to fold toward. +The dispatcher's rig hooks (`ui/src/dispatch.rs:728-730`) keep delegating through `run::rig_*`. ### 2. Input and lifecycle: canonical actions (review M6, C8; critic F11) This replaces two earlier designs, "`HostEvent::Key` carries SDL keycodes plus LG scancodes" and critic M7's "map Ecore names to `remote_token_key` pairs". -- `HostEvent` (app-private, like `Shell`) has: +- `HostEvent` (app-private; `Shell` is published through `host` only, Target shape 8) has: - `Key { action: Option, edge: Edge, raw: Option }`, `Edge` being `Down | Repeat | Up` as in `InputKind::Key` (F33). `action` is `Option` because unbound keys flow today as raw pairs (`k:0,269` HOME, `app/events.rs:202-212`), the configurable lab trigger consumes pairs no `Action` names, and the recorder @@ -1177,23 +1180,40 @@ Ecore names to `remote_token_key` pairs". (`src/lib.rs:17`), so a sibling cannot name `app::Platform` or implement a crate-private `Shell`; and a `static PLATFORM` must be `Sync`, while window state is thread-affine (`MainThread` is `!Send + !Sync`, `base/src/task.rs:129`). -- The interface. One narrow public module, `plxnative_modules::host`, of re-exports only: `Platform`, `Services`, - `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` trait. The - split is by thread: registration data (the `static PLATFORM`: function pointers and `&'static dyn` of `Sync` - types, `Shell` included as a factory) is `Sync` and shared; thread-affine state (window, GL context, the - Ecore handles) lives only in a `Surface` that `Shell::open(&self, &MainThread)` returns on the loop thread and - that the app owns inside `App`. The platform reports input through `EventSink` (`key(Option, - Option, Edge)`, `text`, `pointer`, `wheel`, `lifecycle`, `quit`, ...); the APP converts to its private - `HostEvent`, so the owner's decision that the event API stays private holds. `Action`, `RawKey` and `Edge` - are already public lower-layer types. -- Gate. Before extraction, a desktop-shaped root is compiled against `host` alone: an integration test +- The interface. One narrow public module, `plxnative_modules::host`: re-exports, and ONE function, `run(&'static + Platform, &CStr, u16) -> Exit`, which forwards to `run_application` (the single exception to "re-exports + only": the entry is `pub(crate)`, and a platform crate has nothing else to call). The re-exports are `Platform`, + `Services`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` + trait, with the vocabulary their signatures use: `MainThread`, `OpenAsk`, `Placement`, `Lifecycle`, `PointerEdge`, + `Action`, `RawKey` and `Edge`. Those nine are reachable ONLY through `host` (owner ruling, 2026-11-21; Decision 3, + amended): `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are `pub` in a + private module, so no path outside `host` names them. The split is by thread: registration data (the `static + PLATFORM`: function pointers and `&'static dyn` of `Sync` types, `Shell` included as a factory) is `Sync` and + shared; thread-affine state (window, GL context, the Ecore handles) lives only in a `Surface` that + `Shell::open(&self, &MainThread, &OpenAsk)` returns on the loop thread and that the app owns inside `App`. +- Events. The platform reports input through `EventSink` (`key(Option, Option, Edge) -> bool`, `text`, + `pointer`, `wheel`, `lifecycle`, `quit`); the APP converts to its private `HostEvent` (a private `HostQueue`, the + one place), so the owner's decision that the event API stays private holds. `Action`, `RawKey` and `Edge` are + lower-layer types: `RawKey` moved to `plx_ui::consts` beside `raw_pair` and `action_of` (a `pub(crate) use` keeps + the app's old path). `Surface::deliver(&self, &mut dyn EventSink)` is ADDITIVE, beside `Surface::poll`: `deliver` is + required, `poll` is defaulted to `false` and `#[doc(hidden)]`, and the loop's `drain_sdl` drains `poll` as before and + then calls `deliver` once. The SDL shells deliver nothing through the sink, so every SDL event still comes through + `poll` (a unit test pins both). `poll` is RETIRED once the SDL shells deliver through the sink, W9 at the latest. +- Gate. Before extraction, a platform is compiled against `host` alone: an integration test (`rust-modules/tests/host_interface.rs`, a separate crate that can name only `pub` items) builds a - `static PLATFORM` with a fake `Shell` and boots it under `hostsim`. W7b extracts only after it passes. + `static PLATFORM` from a fake `Shell`, `Surface` and `FrameProbe` and boots it through the real `run_application` + (`host::run`) to the fake `Shell::open`'s refusal, under `hostsim` and a throwaway `PLXNATIVE_RUNTIME_DIR`. It + asserts `init` before `open`, the `OpenAsk` the application means to make, and the refusal returned as the entry's + `Exit`. It cannot run frames, and no fake `Surface` could take it further: after `open` the boot makes real GL calls + (`init_gl` links the renderer's programs), which need a current GL context, and nothing stubs GL under + `test-support`. The loop's fake-surface tests stay in the crate (`make test-hostsim`). The test's one source rule is + that every path into the application crate begins `plxnative_modules::host`; the lower-layer crates a platform + lists as its own dependencies (`plx_os`, `plx_media`) are fair to name. W7b extracts only after it passes. - Runner (G8; F52). No target runs it today (every one is `cargo test --lib`; `rust-modules/tests/` does not exist), so a test file alone would be a gate nobody runs. W7a adds (1) `make test-host-interface`: `cargo test -p plxnative-modules --features hostsim --test host_interface`, incrementally in `target-hostsim` like - `make test-hostsim`, through `$(UNIT_RUN)` if it accepts `--test` (UNVERIFIED: F52) and as a plain `cargo test` - otherwise; it is a cargo-running target, so it joins `DISK_ENTRIES` (with its `DISK_TREE` line) or + `make test-hostsim`, through `$(UNIT_RUN)` (it accepts `--test`: it passes the cargo line through and requires one + executable per `-p`, which one integration test is); it is a cargo-running target, so it joins `DISK_ENTRIES` (with its `DISK_TREE` line) or `ci/test_disk_preflight.py` fails; and (2) the same invocation as a recipe line of `check-cargo-unit-hostsim`, the `host-unit-hostsim` CI job's target, so `make check` and CI run it, pinned in `ci/test_ci_split.py`'s `GATES`. @@ -1649,19 +1669,20 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). hidden W10 work critic M1 named, and they land here. ### W7 (N, accepted T). Extract the platform crates (W7a -> W7b) -- W7a: the interface of Target shape 8: `pub mod host` in `src/lib.rs`, `host_interface.rs`, a desktop-shaped root - compiled against it. W7b: `[platform webos]` becomes `rust-modules/platform-webos` and `[platform desktop]` +- W7a: the interface of Target shape 8: `pub mod host` in `src/lib.rs`, `host_interface.rs`, a fake platform compiled + against it and booted to its refusal. W7b: `[platform webos]` becomes `rust-modules/platform-webos` and `[platform desktop]` becomes `rust-modules/platform-desktop`. `RUST_LIB` (`Makefile:882`) archives `plx_platform_webos`; the gate learns "platform as crate above app". `tv/plane.rs` and `tv::uri` stay in the bottom layer until W11a. - Order: after W0, W4, W6, W6b, W6c and Wave R. W0's reading (the desktop counts as the second implementation) reverses `docs/module-layers.md:22-24`; the owner's yes is Decision 3, A. The owner's condition was H1-H4 from the emulator or a set: H3 and H4 returned on the emulator (E6, E8) and are recorded as answered on the emulator only; H1 and H2 are open (E9), recorded as open, and gate a retail set, not W7 (nor the emulator MVP of W9, - Decision 8). `HostEvent` and `Shell` stay app-private. + Decision 8). `HostEvent` stays app-private; `Shell` and `Surface` are reachable only through `host` (Decision 3, + amended 2026-11-21). - The Cargo mechanism of the PLATFORM axis lands here: the ARM recipe passes `RUST_FEATFLAGS` (`Makefile:1023-1024`), so each platform crate depends on the app with `default-features = false` and forwards every app feature the Makefile passes (`rust-modules/Cargo.toml:78-82`), same defaults. -- Files: `src/lib.rs`, `rust-modules/tests/host_interface.rs`, `rust-modules/Cargo.toml`, the `Makefile` `RUST_LIB` +- Files: `src/lib.rs`, `src/host.rs`, `rust-modules/tests/host_interface.rs`, `rust-modules/Cargo.toml`, the `Makefile` `RUST_LIB` and `cargo rustc` lines and (W7a, G8; F52) the new `test-host-interface` target with its `DISK_ENTRIES` entry and a line in `check-cargo-unit-hostsim`, `ci/test_ci_split.py` (its `GATES`), `ci/check-staticlib-artifact.py` (`CRATE`, F25), `ci/check-module-layers.py`, @@ -1831,8 +1852,13 @@ emulator runs E11 and E12); they are recorded below and the body follows them. - 2026-11-20, Decision 3 (W7 gate): A. W7 may start. H3 and H4 recorded as answered on the emulator only; H1 and H2 stay open and gate W9, not W7. `Shell` and `HostEvent` stay app-private. Read with Decision 8: the emulator MVP of W9 does not wait for H1 and H2 either. +- 2026-11-21, Decision 3 amended (owner): `Shell`, `Surface`, `Platform`, `Services`, `FrameProbe`, `MediaBoot`, + `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, never as general `pub` + items of the application crate. `HostEvent` stays app-private; `EventSink` is the public face of input. This + replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and only `Shell`. - 2026-11-20, Decision 4 (order): A. The three contracts (W3a-c) first, then the rest, the Samsung-facing types - app-private. Cut into the waves of "Workstreams". + app-private (`Shell` and `Surface` are published through `host` only, by the 2026-11-21 amendment to Decision 3). + Cut into the waves of "Workstreams". - 2026-11-20, Decision 5 (probes): go. H5 was built on `samsung/hello-tpk` for the emulator and passed there (E10, `64c609a46`); the tester request on #1460 for H1, H2 and H6 is posted only with the owner's approval; the tester build with an on-screen diagnostics and key-code panel ran on the emulator (E11) and is the From f0abd37d69767043c47dead76be262f02a11dce6 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 02:23:59 +0300 Subject: [PATCH 04/11] The source scan names every mention of the application crate, and the SDL delivery test polls both edges of a tap Co-Authored-By: Claude Sonnet 5.5 --- rust-modules/src/app/platform.rs | 9 ++++++--- rust-modules/tests/host_interface.rs | 7 +++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/rust-modules/src/app/platform.rs b/rust-modules/src/app/platform.rs index 6efe19bdb..d759fbe51 100644 --- a/rust-modules/src/app/platform.rs +++ b/rust-modules/src/app/platform.rs @@ -549,9 +549,12 @@ mod tests { let mut count = Count::default(); surface.deliver(&mut count); assert_eq!(count.0, 0, "an SDL surface delivers nothing through the sink"); - assert!(surface.poll(&mut ev), "the pushed key is still the queue's, through `poll`"); - assert!(plx_shell_sdl::event::decode(&ev).is_some(), "and it decodes as before"); - assert!(!surface.poll(&mut ev), "and the queue is empty after it"); + // `synth_key` pushes the two edges of a tap, down then up: both are still the queue's. + for edge in ["down", "up"] { + assert!(surface.poll(&mut ev), "the pushed key's {edge} edge is still the queue's, through `poll`"); + assert!(plx_shell_sdl::event::decode(&ev).is_some(), "and it decodes as before ({edge})"); + } + assert!(!surface.poll(&mut ev), "and the queue is empty after them"); } /// **The SDL calls the application still declares are the two that stay.** Everything SDL-shaped diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs index c16bb67ac..1bd0f0007 100644 --- a/rust-modules/tests/host_interface.rs +++ b/rust-modules/tests/host_interface.rs @@ -227,12 +227,15 @@ fn an_event_sink_is_implementable_from_outside_and_receives_a_surfaces_events_in fn every_path_into_the_application_crate_goes_through_host() { let source = include_str!("host_interface.rs"); // Split, so this test's own text never matches. - let needle = concat!("plxnative_", "modules::"); + let needle = concat!("plxnative_", "modules"); let mut seen = 0; for (at, _) in source.match_indices(needle) { seen += 1; let line = source[..at].matches('\n').count() + 1; - assert!(source[at + needle.len()..].starts_with("host"), "line {line}: a path into the application crate that is not `host`'s"); + assert!( + source[at + needle.len()..].starts_with("::host"), + "line {line}: a name of the application crate that is not a path into `host`" + ); } assert!(seen > 0, "the scan found no path at all: it is not reading this file"); } From 7c37869c60156a113e2432ff996999cdacf64bc0 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 02:31:13 +0300 Subject: [PATCH 05/11] The host-threads pin counts the two HOST_ENV lines the new host interface gate carries Co-Authored-By: Claude Sonnet 5.5 --- ci/test_host_threads.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ci/test_host_threads.py b/ci/test_host_threads.py index 740ca0d7e..406592be3 100644 --- a/ci/test_host_threads.py +++ b/ci/test_host_threads.py @@ -16,7 +16,7 @@ nightly toolchain: asking for more than one thread on the stable pin is a Makefile error that names the fix, rather than a cargo failure in the middle of a recipe; * the flag reaches exactly the host test recipes (`check-cargo-unit-default`, `-hostsim`, - `test-fast`, `test-crate`, `test-hostsim`, `build-bench`) when it is on, and NO recipe when it is off, so a CI + `test-fast`, `test-crate`, `test-hostsim`, `test-host-interface`, `build-bench`) when it is on, and NO recipe when it is off, so a CI recipe is the command it always was; * it is never exported and no ARM, simulator, clippy or package line, and no workflow, names it, so a release or simulator build cannot pick it up; @@ -39,7 +39,7 @@ "GITHUB_ACTIONS", "ARM_PROFILE", "HOST_THREADS") FLAG = "CARGO_BUILD_RUSTFLAGS" HOST_RECIPES = (("check-cargo-unit-default",), ("check-cargo-unit-hostsim",), ("test-fast",), - ("test-crate", "C=plx_base"), ("test-hostsim",), ("build-bench",)) + ("test-crate", "C=plx_base"), ("test-hostsim",), ("test-host-interface",), ("build-bench",)) def make(*args: str, env: dict[str, str] | None = None) -> str: @@ -109,7 +109,7 @@ def test_off_means_no_recipe_names_it(self): ("RELEASE", ["RELEASE=1"], None), ("stable", ["FLAVOR=stable"], None)): # those goals refuse RELEASE=1 outright goals = [goal for goal in HOST_RECIPES - if not (goal[0] in ("test-fast", "test-crate", "test-hostsim", "build-bench") and what in ("RELEASE",))] + if not (goal[0] in ("test-fast", "test-crate", "test-hostsim", "test-host-interface", "build-bench") and what in ("RELEASE",))] with self.subTest(f"{what}: {', '.join(goal[0] for goal in goals)}"): out = make("-n", *[word for goal in goals for word in goal], *args, env=env) self.assertNotIn(FLAG, out) @@ -125,7 +125,8 @@ def test_the_arm_and_simulator_recipes_never_name_it(self): self.assertNotIn(banned, line, f"Makefile:{lineno} puts the host flag on a non-host line") # ...and the lines that DO carry it are the host test recipes, nothing else. users = [l for l in text.splitlines() if "$(HOST_ENV)" in l and not l.lstrip().startswith("#")] - self.assertEqual(len(users), len(HOST_RECIPES), users) + # `check-cargo-unit-hostsim` carries it on two cargo lines (the `--lib` suite and W7a's `--test host_interface`). + self.assertEqual(len(users), len(HOST_RECIPES) + 1, users) def test_no_workflow_names_it(self): # Workflows and composite actions only: ci.yml's `paths` filter skips pushes that touch only From ac7127b808637528eeb45bad9f571904fbb0276a Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 02:31:28 +0300 Subject: [PATCH 06/11] The plan records what W7a landed Co-Authored-By: Claude Sonnet 5.5 --- docs/platform-ports.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/platform-ports.md b/docs/platform-ports.md index dac95ac1e..3ab8e4589 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -1689,7 +1689,17 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). `ci/module-layers.ini`, `docs/module-layers.md`, `ci/build-budgets.json` (re-measure; no raise), and the bottom layer's `src/lib.rs` (drops `pub mod keymanager;` and `pub mod webos;`) with its `Cargo.toml`: both pinned, a reviewed certificate change (F25). -- Test: `make test-hostsim` and `make test-host-interface` (the integration test, run by no target today; `ci/ +- As landed (W7a): the interface, not the move. `src/host.rs` is the one public module (re-exports and `run`), the + nine types of the owner's ruling are reachable through it only, and `rust-modules/tests/host_interface.rs` builds + a `static Platform` from fakes and boots it through `host::run` to the fake shell's refusal, with a source scan + that holds every mention of the application crate to `plxnative_modules::host`. The test has no `[[test]]` + entry (cargo discovers `tests/*.rs`), so no `Cargo.toml` and no `ci/proofs` certificate changed. `make + test-host-interface` is the incremental loop and `check-cargo-unit-hostsim` runs the same line, pinned in + `ci/test_ci_split.py` (`GATES`). `Surface::poll` and `Surface::deliver` coexist until W9 retires `poll`; the SDL + shells' `deliver` delivers nothing. `sdl_init` and `sdl_open` are not published: W7b decides what the two real + platform crates need of them. The W6 minors rode along (the reviewer note's inventory claim, and the SDL crate's + source-file pin reading only `*.rs` entries). +- Test: `make test-hostsim` and `make test-host-interface` (the integration test; run by both since W7a; `ci/ test_disk_preflight.py` and `ci/test_ci_split.py` pass with it); W7a changes the `Makefile`, so its PR carries a build-bench table as well as W7b's; `ARM_PROFILE=release` size within budget; every undefined symbol of the C objects (`main.c`, `crashtrace.c`, `sentry_context.c`, `starfish.c`, From 47df75e6ee953064657598742929cd41b152a4cb Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 02:42:33 +0300 Subject: [PATCH 07/11] The prose says what the host interface made false: Surface is published, Services is plx_os's, and the integration test exists Co-Authored-By: Claude Sonnet 5.5 --- Makefile | 11 ++++++----- docs/agent-reference.md | 4 ++-- docs/module-layers.md | 2 +- docs/platform-ports.md | 18 ++++++++++-------- rust-modules/src/app/events.rs | 7 ++++--- rust-modules/src/host.rs | 12 +++++++----- rust-modules/src/lib.rs | 5 +++-- 7 files changed, 33 insertions(+), 26 deletions(-) diff --git a/Makefile b/Makefile index 05d40698d..7c01e0ef7 100644 --- a/Makefile +++ b/Makefile @@ -581,8 +581,8 @@ ARM_PROFILE_FLAG = $(if $(filter release,$(ARM_PROFILE)),--release,--profile $(A # make RUST_TOOLCHAIN=nightly HOST_THREADS=8 test-fast # # A HOST_THREADS above 1 on a non-nightly toolchain is a hard error here rather than a cargo failure -# in the middle of a recipe. Which recipes: ONLY the host `cargo test` / `check-cargo-unit-*` builds, -# `test-fast`, `test-crate`, `test-hostsim` and `build-bench` carry `$(HOST_ENV)`. It is NOT exported, so the ARM +# in the middle of a recipe. Which recipes: the host `cargo test` builds and nothing else +# (`grep -n HOST_ENV Makefile` is the exact set; `ci/test_host_threads.py`'s `HOST_RECIPES` pins it). It is NOT exported, so the ARM # staticlib recipes (which set RUSTFLAGS themselves), the simulators' builds, clippy and the package # steps never see it (ci/test_host_threads.py pins both). 0 and 1 mean the serial front end. A # RUSTFLAGS the caller exported wins over it (cargo reads CARGO_BUILD_RUSTFLAGS last). @@ -1646,9 +1646,10 @@ check: # best. A bare `cargo test` builds for the host triple, which is exactly what we want — and it is # also why this suite cannot cover anything that links the TV's own libraries: media-codecs/src/ffi.rs gates its four # `#[link]` directives out of cfg(test) so the crate's pure logic stays host-testable, and a test -# that actually calls into FFmpeg or GL fails to link by design. --lib keeps it to the crate's own -# `#[cfg(test)] mod tests` blocks (there are no integration tests in tests/ — that directory is the -# on-device Python harness, a different thing entirely). +# that actually calls into FFmpeg or GL fails to link by design. --lib keeps it to the crates' own +# `#[cfg(test)]` blocks. The one integration test, `rust-modules/tests/host_interface.rs`, needs `hostsim` +# and runs in `check-cargo-unit-hostsim` (and `make test-host-interface`), not here; the repo-root `tests/` +# is the on-device Python harness, a different thing entirely. # NB the suite APPENDS to `/tmp/plxnative-events.log` on the dev Mac, and deliberately cannot be # pointed elsewhere. Since 2026-08-15 enough of the tree logs its failures (stream, posters, img, # account, remote) that host tests exercising those paths write real lines. `PLXNATIVE_RUNTIME_DIR` diff --git a/docs/agent-reference.md b/docs/agent-reference.md index 3dfb283e5..ba1b1d1ee 100644 --- a/docs/agent-reference.md +++ b/docs/agent-reference.md @@ -138,7 +138,7 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y stack is mostly a chain, so cargo has little to run side by side and the front end (parse, type-check, borrow-check) is single-threaded per crate by default. `-Zthreads=N` (N = the core count, capped at 8) parallelises it for the host `cargo test` recipes (`check-cargo-unit-default`, - `check-cargo-unit-hostsim`, `test-fast`, `test-crate`, `test-hostsim`, `build-bench`) through + `check-cargo-unit-hostsim`, `test-fast`, `test-crate`, `test-hostsim`, `test-host-interface`, `build-bench`) through `CARGO_BUILD_RUSTFLAGS`. Measured 2026-10-05 on an M4 (10 cores) on nightly, `make build-bench` non-incremental edit-rebuilds, medians of 5: `plx_base` leaf 20.1 s to 17.8 s, `plx_ui` 10.7 to 7.8, `plx_screens` 8.3 to 5.7, app 4.8 to 2.9; the incremental `test-fast` loop is unchanged @@ -1281,7 +1281,7 @@ every thin back-edge with `file:line` (the work list for breaking it up); `--dot `abnormal`, like a freeze's; one made after backgrounding (the PLX-NATIVE-1P shape) finds no open session, because backgrounding already ended it `exited` (`telemetry::session`), so only the `error` event exists. -- `rust-modules/src/` — the app core (Rust): `app/` (`mod.rs` the `run_application` shim + `struct App`, `boot.rs` the bring-up, `run.rs` the frame loop and its phase functions, `events.rs`/`input.rs` the input decode and key ladders, `lifecycle.rs`, `playback.rs`, `content.rs`, `bridge.rs` the seam onto the container and the ONE navigation vocabulary, `words.rs` the heartbeat's `route=`/`overlay=` alphabet — `nav.rs` is gone with `enum Route` since restructure phase 12), `system.rs` (wayland), `rust-modules/shell-sdl/` (crate `plx_shell_sdl`: `SDL_Init`, the window, the GL swap, the event decode and the text-input calls, which `app/platform.rs`'s `Shell` opens as the app-private `Surface`), +- `rust-modules/src/` — the app core (Rust): `app/` (`mod.rs` the `run_application` shim + `struct App`, `boot.rs` the bring-up, `run.rs` the frame loop and its phase functions, `events.rs`/`input.rs` the input decode and key ladders, `lifecycle.rs`, `playback.rs`, `content.rs`, `bridge.rs` the seam onto the container and the ONE navigation vocabulary, `words.rs` the heartbeat's `route=`/`overlay=` alphabet — `nav.rs` is gone with `enum Route` since restructure phase 12), `system.rs` (wayland), `rust-modules/shell-sdl/` (crate `plx_shell_sdl`: `SDL_Init`, the window, the GL swap, the event decode and the text-input calls, which `app/platform.rs`'s `Shell` opens as the `Surface` the `App` owns (`Shell` and `Surface` are reachable from outside the crate only through `plxnative_modules::host`; `HostEvent` stays app-private)), and, in the media layer (`rust-modules/media/`, crate `plx_media`, which the application links), `player/` (buffer-feed engine + worker threads — **`rust-modules/media/src/player/CLAUDE.md` is the playback deep-dive; read it before touching playback**), `abr/` and `route/`, and `ff.rs`, which diff --git a/docs/module-layers.md b/docs/module-layers.md index 7d49c6900..704e5e6ff 100644 --- a/docs/module-layers.md +++ b/docs/module-layers.md @@ -348,7 +348,7 @@ proves the references are gone and nothing more; L15b is open. | **L15c** the platform value and the three contracts — **done** | — | Wave R (the rename that gave this page `os` and `[platform webos]`) landed as #1474; W2 landed (`tv::Port` became `tv::Services`, with four groups of hooks; the shell and the frame probes moved to `app::Platform`), and so did the three contracts, W3a to W3c: who may persist credentials (#1477), what evidence admits a URI player (#1478), who ends the process (#1479). See "L15c to L15h" below. | | **L15d** neutral types and the simulator as its own platform (L15b item 2) — **W3d and W4 landed** | — | W3d landed (the opaque `Backend` tag, `sandbox` to `native_video`, identity publishes a platform name and version, `device::Info` keeps its webOS fields in `WebosDetail`, and `devcaps` reads its files through the platform), and so did W4: `platform_desktop` (`rust-modules/src/platform_desktop.rs`, a second fence section, `[platform desktop]`) is the simulator's and the macOS app's own platform value, which `src/bin/sim.rs` enters through; the `hostsim` terms of the television's fence are gone, so the television's code is compiled into every build and the linker drops it from a desktop executable (`simulators.yml` links the macapp feature set to guard that until W7), and the stand-ins in `webos` and `keymanager` are test seams, compiled for tests and `test-support` (`docs/platform-ports.md`, W4). The desktop platform is the second implementation. | | **L15e** events, the shell and composition — **W5a to W5c, W6, W6b, W6c and W7a landed** | — | W5 (`HostEvent` with `Option`) landed in three PRs, lifecycle and quit (W5a, #1484), keys and text (W5b, #1487) and the pointer and wheel (W5c, #1492), and so did W6b (platform-supplied composition in two boot phases, #1489) and W6 (`plx_shell_sdl`, a `[shell_sdl]` layer: SDL's bring-up, the window, the swap, the event decode and the text-input calls moved out of the application behind its private `Shell` and `Surface`, and the LG half stays in `system.rs`). W6c (a URI-only and a two-driver composition play an ordinary title) landed (#1494), and W7a published the construction interface through `plxnative_modules::host` alone (`rust-modules/src/host.rs`, tested from outside the crate by `rust-modules/tests/host_interface.rs`, `make test-host-interface`). | -| **L15f** extract the platform crates — **planned** | — | W7: a narrow public `host` module in the application crate, `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h (the storage-authority part of W8a, #1488, #1490 and #1491, landed ahead of W7; the rest of W8 still follows W7). | +| **L15f** extract the platform crates — **planned** | — | W7b: `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, over the narrow public `host` module W7a already published (the row above), and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h (the storage-authority part of W8a, #1488, #1490 and #1491, landed ahead of W7; the rest of W8 still follows W7). | | **L15g** the webOS facts and the remaining `hostsim` (L15b item 3) — **W8a started** | — | W8a has begun: the platform states where the account's records live (`tv::Services.storage`, #1488), and telemetry's consent store (#1490) and plex's session persistence (#1491) follow it instead of the `target_arch = "arm"` fence. Still planned: the rest of W8a, one PR per directory (`os`, `src`, `base`, `storage` and `play-feed`; telemetry's nine `target_arch = "arm"` lines in `telemetry/src/telemetry/native.rs`, the Sentry Native crash capture, are not among them and no step owns them yet, the follow-up for Tizen ARM retail builds that #1490 names), sorting the `target_arch = "arm"` and `target_os = "linux"` sites into "is webOS" (a platform value or runner) and "is 32-bit ARM" or "is Linux" (stays); then W8b, the library name lists, `paths` and the packaging, and W8c, the `feature = "hostsim"` lines left in the tree (none of them in the fence now; `git grep -h 'feature = "hostsim"' -- '*.rs' | wc -l` counts them). | | **L15h** the OS-neutral Feed sink (L15b item 1) — **planned** | — | W11: `plx_acb` (an `[acb]` layer) takes the ACB plane owner and the URI media verbs out of `os`, the Feed-side ACB results become neutral, and the bind sequence moves behind a neutral sink. Needs the television. | diff --git a/docs/platform-ports.md b/docs/platform-ports.md index 3ab8e4589..ae09eae92 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -1185,9 +1185,10 @@ Ecore names to `remote_token_key` pairs". only": the entry is `pub(crate)`, and a platform crate has nothing else to call). The re-exports are `Platform`, `Services`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` trait, with the vocabulary their signatures use: `MainThread`, `OpenAsk`, `Placement`, `Lifecycle`, `PointerEdge`, - `Action`, `RawKey` and `Edge`. Those nine are reachable ONLY through `host` (owner ruling, 2026-11-21; Decision 3, - amended): `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are `pub` in a - private module, so no path outside `host` names them. The split is by thread: registration data (the `static + `Action`, `RawKey` and `Edge`. The application's eight (all but `Services`) are reachable ONLY through `host` (owner ruling, 2026-11-21; + Decision 3, amended): `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are + `pub` in a private module, so no path outside `host` names them. `Services` stays `plx_os::tv::Services`, a lower + layer's type that `host` re-exports for one-stop naming. The split is by thread: registration data (the `static PLATFORM`: function pointers and `&'static dyn` of `Sync` types, `Shell` included as a factory) is `Sync` and shared; thread-affine state (window, GL context, the Ecore handles) lives only in a `Surface` that `Shell::open(&self, &MainThread, &OpenAsk)` returns on the loop thread and that the app owns inside `App`. @@ -1209,8 +1210,8 @@ Ecore names to `remote_token_key` pairs". `test-support`. The loop's fake-surface tests stay in the crate (`make test-hostsim`). The test's one source rule is that every path into the application crate begins `plxnative_modules::host`; the lower-layer crates a platform lists as its own dependencies (`plx_os`, `plx_media`) are fair to name. W7b extracts only after it passes. -- Runner (G8; F52). No target runs it today (every one is `cargo test --lib`; `rust-modules/tests/` does not - exist), so a test file alone would be a gate nobody runs. W7a adds (1) `make test-host-interface`: `cargo +- Runner (G8; F52). As of `e9924f0f9` no target ran it (every one was `cargo test --lib`; `rust-modules/tests/` did not + exist), so a test file alone would have been a gate nobody ran. W7a added (1) `make test-host-interface`: `cargo test -p plxnative-modules --features hostsim --test host_interface`, incrementally in `target-hostsim` like `make test-hostsim`, through `$(UNIT_RUN)` (it accepts `--test`: it passes the cargo line through and requires one executable per `-p`, which one integration test is); it is a cargo-running target, so it joins `DISK_ENTRIES` (with its `DISK_TREE` line) or @@ -1689,8 +1690,8 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). `ci/module-layers.ini`, `docs/module-layers.md`, `ci/build-budgets.json` (re-measure; no raise), and the bottom layer's `src/lib.rs` (drops `pub mod keymanager;` and `pub mod webos;`) with its `Cargo.toml`: both pinned, a reviewed certificate change (F25). -- As landed (W7a): the interface, not the move. `src/host.rs` is the one public module (re-exports and `run`), the - nine types of the owner's ruling are reachable through it only, and `rust-modules/tests/host_interface.rs` builds +- As landed (W7a): the interface, not the move. `src/host.rs` is the one public module of a television build (re-exports and `run`; a `hostsim` build keeps the simulator binary's own doors), the + eight application types of the owner's ruling are reachable through it only (`Services` is `plx_os`'s, re-exported), and `rust-modules/tests/host_interface.rs` builds a `static Platform` from fakes and boots it through `host::run` to the fake shell's refusal, with a source scan that holds every mention of the application crate to `plxnative_modules::host`. The test has no `[[test]]` entry (cargo discovers `tests/*.rs`), so no `Cargo.toml` and no `ci/proofs` certificate changed. `make @@ -1865,7 +1866,8 @@ emulator runs E11 and E12); they are recorded below and the body follows them. - 2026-11-21, Decision 3 amended (owner): `Shell`, `Surface`, `Platform`, `Services`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, never as general `pub` items of the application crate. `HostEvent` stays app-private; `EventSink` is the public face of input. This - replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and only `Shell`. + replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and only `Shell`. (`Services` is `plx_os::tv::Services`, + a `pub` type of a lower crate: `host` re-exports it, so it is nameable both ways; the other eight have one path.) - 2026-11-20, Decision 4 (order): A. The three contracts (W3a-c) first, then the rest, the Samsung-facing types app-private (`Shell` and `Surface` are published through `host` only, by the 2026-11-21 amendment to Decision 3). Cut into the waves of "Workstreams". diff --git a/rust-modules/src/app/events.rs b/rust-modules/src/app/events.rs index 015200281..375428525 100644 --- a/rust-modules/src/app/events.rs +++ b/rust-modules/src/app/events.rs @@ -77,9 +77,10 @@ pub(crate) fn host_wcode(sym: u32) -> u32 { } /// What the platform tells the loop: a key press, a text commit, the pointer, the wheel, the window -/// leaving or returning to the screen, and the host asking the application to end. App-private, like -/// [`Shell`](super::platform::Shell): no platform reaches it by a type of its own until the -/// platform contract is settled (`docs/platform-ports.md`, Target shape 2). +/// leaving or returning to the screen, and the host asking the application to end. App-private, unlike +/// [`Shell`](super::platform::Shell) and [`Surface`](super::platform::Surface), which `host` publishes: a +/// platform reports input through [`EventSink`](super::platform::EventSink) and the application converts it +/// to this type in [`HostQueue`] (`docs/platform-ports.md`, Target shapes 2 and 8). /// /// The SDL drain decodes SDL's events into it ([`decode_host_event`]) and the loop consumes it in /// ONE function (`run::ingest_host_event`), so a host that stops the application without SDL diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs index 21df7ed03..51b2d1c1f 100644 --- a/rust-modules/src/host.rs +++ b/rust-modules/src/host.rs @@ -4,11 +4,13 @@ //! The application's modules are private (`mod app;`), so a crate that is a sibling of this one cannot //! name `app::Platform` or implement a crate-private `Shell`. This is the one narrow public face: re-exports //! of the types a platform builds or implements, an [`EventSink`] through which it reports input, and -//! [`run`], the one function in here (it hands the platform to the application's entry). Nothing else of -//! the application is public. `HostEvent`, the loop's own event type, stays private: a platform reports -//! input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 -//! amended): `Shell`, `Surface`, `Platform`, `Services`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` -//! and `Release` are reachable only through this module. +//! [`run`], the one function in here (it hands the platform to the application's entry). No other module of the +//! application is public to a television build (a `hostsim` build also keeps the simulator binary's own doors: +//! `platform_desktop::run`, `hud_cli`, the `sim_*` helpers). `HostEvent`, the loop's own event type, stays +//! private: a platform reports input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 +//! amended): `Shell`, `Surface`, `Platform`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` +//! are reachable only through this module (`Services` is `plx_os::tv::Services`, a lower layer's type that this +//! module re-exports for one-stop naming). //! //! The split is by thread. A [`Platform`] is registration data in a `static`: function pointers and //! `&'static dyn` of `Sync` types, [`Shell`] included as a factory. The thread-affine state (the window, diff --git a/rust-modules/src/lib.rs b/rust-modules/src/lib.rs index d0b9ddd74..2d621e9d9 100644 --- a/rust-modules/src/lib.rs +++ b/rust-modules/src/lib.rs @@ -20,8 +20,9 @@ mod coldstart; // retires old last-page bookmarks; authenticated cold boots now mod dev; // the /tmp/plxnative-* trigger surface, behind one `devtriggers` feature — read it before adding a trigger mod focusprobe; // dev: one diffable line naming everything app.rs's key ladder can move, logged when it changes /// The one narrow public face of the application for a platform crate: the types it builds and implements -/// (`Platform`, `Shell`, `Surface`, `EventSink`, ...) and the entry `run`, as re-exports. Everything else of -/// the application stays private (`docs/platform-ports.md`, Target shape 8). +/// (`Platform`, `Shell`, `Surface`, `EventSink`, ...) and the entry `run`, as re-exports. Every other module of +/// the application stays private to a television build (`docs/platform-ports.md`, Target shape 8; a `hostsim` +/// build also exposes the simulator binary's own doors below). pub mod host; // The simulator's HUD tools (`--hud-lint`, `--hud-schema`, `--hud-export`): a library function the thin // `src/bin/sim.rs` calls before it reads a PMS host. `pub` because that binary is a separate crate; absent From 8f25da9f57699f31a1283d534c6c9b2e0ca74d59 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 03:15:30 +0300 Subject: [PATCH 08/11] The host test asserts its own footprint, not the shared /tmp, and the host docs name every simulator door The boot-to-refusal test asserted that a run created no plxnative-* entry in /tmp, but other checkouts' test runs write there concurrently, so the assertion was a race. It now asserts that the boot's event log landed in the throwaway runtime root, and prints both listings for a reader of --nocapture. host.rs named the simulator's hostsim doors by a sim_* glob, which misses publish_sim_webos_major and the synthetic_home_initial re-export; it now lists the six and says where to grep for them. The Makefile's HOST-ONLY comment lists test-host-interface beside test-hostsim. Co-Authored-By: Claude Sonnet 5.5 --- Makefile | 4 ++-- rust-modules/src/host.rs | 6 ++++-- rust-modules/tests/host_interface.rs | 13 +++++++++---- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 7c01e0ef7..1be253749 100644 --- a/Makefile +++ b/Makefile @@ -854,8 +854,8 @@ RUST_CFG = features:$(RUST_FEATFLAGS)$(if $(filter-out release,$(ARM_PROFI # it from the recipe AND its prerequisites, never the name (`check-ass` is a test goal and stages the # host libass into `pkg/`). Two kinds qualify: # -# * HOST-ONLY goals: the unit-test loops, the fuzz runs and the lint pass (`test-hostsim`, `check-nodef`, -# `test-fast`, `test-crate`, `fuzz-hud`, `lint`, `build-bench`), the pieces of `check` that are plain host work +# * HOST-ONLY goals: the unit-test loops, the fuzz runs and the lint pass (`test-hostsim`, `test-host-interface`, +# `check-nodef`, `test-fast`, `test-crate`, `fuzz-hud`, `lint`, `build-bench`), the pieces of `check` that are plain host work # (`check-cargo-lint`, `check-cargo-unit-hostsim`, `check-localization`, `check-c-unit`, # `check-python-harness`), the notices tables, and the set-up and local tooling that writes outside # `pkg/` (a toolchain install, the disk-watch agent, the test media, the demo library, the diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs index 51b2d1c1f..80270ffa1 100644 --- a/rust-modules/src/host.rs +++ b/rust-modules/src/host.rs @@ -5,8 +5,10 @@ //! name `app::Platform` or implement a crate-private `Shell`. This is the one narrow public face: re-exports //! of the types a platform builds or implements, an [`EventSink`] through which it reports input, and //! [`run`], the one function in here (it hands the platform to the application's entry). No other module of the -//! application is public to a television build (a `hostsim` build also keeps the simulator binary's own doors: -//! `platform_desktop::run`, `hud_cli`, the `sim_*` helpers). `HostEvent`, the loop's own event type, stays +//! application is public to a television build. A `hostsim` build also keeps the simulator binary's own doors, +//! each behind `feature = "hostsim"` in `lib.rs` (`grep -n 'feature = "hostsim"' rust-modules/src/lib.rs`): +//! `platform_desktop::run`, `hud_cli`, `sim_runtime_dir`, `sim_events_log`, `publish_sim_webos_major` and +//! `synthetic_home_initial`, the one `app` item re-exported at the crate root. `HostEvent`, the loop's own event type, stays //! private: a platform reports input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 //! amended): `Shell`, `Surface`, `Platform`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` //! are reachable only through this module (`Services` is `plx_os::tv::Services`, a lower layer's type that this diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs index 1bd0f0007..0f53caf52 100644 --- a/rust-modules/tests/host_interface.rs +++ b/rust-modules/tests/host_interface.rs @@ -258,8 +258,10 @@ fn plxnative_entries(dir: &std::path::Path) -> Vec { /// **The boot of the fake platform, to its refusal.** The real `run_application` runs on `PLATFORM`: /// it installs the platform's services, brings the shell up (`init`), reads the stored session, then asks /// the shell for the window (`open`), which refuses. The test asserts the order, the window asked for, the -/// installed services and the returned `Exit`, and that the boot created nothing named `plxnative-*` in `/tmp` -/// (where a device's trigger files live) outside the throwaway runtime root. +/// installed services and the returned `Exit`, and that the boot's event log landed in the throwaway runtime root. +/// It also PRINTS the `plxnative-*` entries of `/tmp` (where a device's trigger files live) and of the runtime root +/// before and after, for a reader of `--nocapture`; it does not assert on `/tmp`, which other checkouts' test runs +/// write under concurrently. #[cfg(feature = "hostsim")] #[test] fn run_boots_the_fake_platform_through_init_then_open_and_returns_the_refusal() { @@ -299,6 +301,9 @@ fn run_boots_the_fake_platform_through_init_then_open_and_returns_the_refusal() eprintln!("/tmp/plxnative-* (outside plxnative-check.*) before: {tmp_before:?}"); eprintln!("/tmp/plxnative-* (outside plxnative-check.*) after: {tmp_after:?}"); eprintln!("runtime root {}: {runtime_before} entries before, after: {runtime_after:?}", runtime.display()); - let created: Vec<&String> = tmp_after.iter().filter(|n| !tmp_before.contains(n)).collect(); - assert!(created.is_empty(), "the boot created {created:?} in /tmp, outside the runtime root"); + assert!( + runtime_after.iter().any(|n| n == "plxnative-events.log"), + "the boot's event log is not in the runtime root {}: {runtime_after:?}", + runtime.display() + ); } From 06d95595b387f64631d0c3a30c03722401098c37 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 05:32:17 +0300 Subject: [PATCH 09/11] The host ruling reads as one statement: eight application-crate items, and Services is a lower crate's type Decision 3's amendment listed nine types as "reachable only through host" and then said, in its own parenthetical, that Services is nameable both ways. host.rs and section 8 said eight. All four places (the amendment, section 8's interface bullet, the W7a landed bullet and host.rs's module doc) now say the same thing: Platform, Shell, Surface, FrameProbe, MediaBoot, Composition, Exit and Release are reachable only through host; Services is plx_os::tv::Services, already pub in a lower crate, which host re-exports so a platform crate names host alone; HostEvent stays private and EventSink is the public face. Co-Authored-By: Claude Sonnet 5.5 --- docs/platform-ports.md | 23 +++++++++++++---------- rust-modules/src/host.rs | 7 ++++--- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/platform-ports.md b/docs/platform-ports.md index ae09eae92..348940f2e 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -1185,10 +1185,11 @@ Ecore names to `remote_token_key` pairs". only": the entry is `pub(crate)`, and a platform crate has nothing else to call). The re-exports are `Platform`, `Services`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` trait, with the vocabulary their signatures use: `MainThread`, `OpenAsk`, `Placement`, `Lifecycle`, `PointerEdge`, - `Action`, `RawKey` and `Edge`. The application's eight (all but `Services`) are reachable ONLY through `host` (owner ruling, 2026-11-21; - Decision 3, amended): `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are - `pub` in a private module, so no path outside `host` names them. `Services` stays `plx_os::tv::Services`, a lower - layer's type that `host` re-exports for one-stop naming. The split is by thread: registration data (the `static + `Action`, `RawKey` and `Edge`. The eight application-crate items (`Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, + `Composition`, `Exit`, `Release`) are reachable ONLY through `host` (owner ruling, 2026-11-21; Decision 3, amended): + `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are `pub` in a private + module, so no path outside `host` names them. `Services` is not one of the eight: it stays `plx_os::tv::Services`, + already a `pub` type of a lower crate, which `host` re-exports so that a platform crate names `host` alone. The split is by thread: registration data (the `static PLATFORM`: function pointers and `&'static dyn` of `Sync` types, `Shell` included as a factory) is `Sync` and shared; thread-affine state (window, GL context, the Ecore handles) lives only in a `Surface` that `Shell::open(&self, &MainThread, &OpenAsk)` returns on the loop thread and that the app owns inside `App`. @@ -1691,7 +1692,7 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). layer's `src/lib.rs` (drops `pub mod keymanager;` and `pub mod webos;`) with its `Cargo.toml`: both pinned, a reviewed certificate change (F25). - As landed (W7a): the interface, not the move. `src/host.rs` is the one public module of a television build (re-exports and `run`; a `hostsim` build keeps the simulator binary's own doors), the - eight application types of the owner's ruling are reachable through it only (`Services` is `plx_os`'s, re-exported), and `rust-modules/tests/host_interface.rs` builds + eight application-crate items of the owner's ruling are reachable through it only (`Services` is `plx_os`'s own `pub` type, re-exported), and `rust-modules/tests/host_interface.rs` builds a `static Platform` from fakes and boots it through `host::run` to the fake shell's refusal, with a source scan that holds every mention of the application crate to `plxnative_modules::host`. The test has no `[[test]]` entry (cargo discovers `tests/*.rs`), so no `Cargo.toml` and no `ci/proofs` certificate changed. `make @@ -1863,11 +1864,13 @@ emulator runs E11 and E12); they are recorded below and the body follows them. - 2026-11-20, Decision 3 (W7 gate): A. W7 may start. H3 and H4 recorded as answered on the emulator only; H1 and H2 stay open and gate W9, not W7. `Shell` and `HostEvent` stay app-private. Read with Decision 8: the emulator MVP of W9 does not wait for H1 and H2 either. -- 2026-11-21, Decision 3 amended (owner): `Shell`, `Surface`, `Platform`, `Services`, `FrameProbe`, `MediaBoot`, - `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, never as general `pub` - items of the application crate. `HostEvent` stays app-private; `EventSink` is the public face of input. This - replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and only `Shell`. (`Services` is `plx_os::tv::Services`, - a `pub` type of a lower crate: `host` re-exports it, so it is nameable both ways; the other eight have one path.) +- 2026-11-21, Decision 3 amended (owner): the EIGHT application-crate items `Platform`, `Shell`, `Surface`, + `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, + never as general `pub` items of the application crate. `Services` is not one of the eight: it is + `plx_os::tv::Services`, already a `pub` type of a lower crate, which `host` re-exports so that a platform crate + names `host` alone. `HostEvent` stays app-private, and `EventSink` is the public face of input (it too is + reachable only through `host`). This replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and + only `Shell`. - 2026-11-20, Decision 4 (order): A. The three contracts (W3a-c) first, then the rest, the Samsung-facing types app-private (`Shell` and `Surface` are published through `host` only, by the 2026-11-21 amendment to Decision 3). Cut into the waves of "Workstreams". diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs index 80270ffa1..41bc3d996 100644 --- a/rust-modules/src/host.rs +++ b/rust-modules/src/host.rs @@ -10,9 +10,10 @@ //! `platform_desktop::run`, `hud_cli`, `sim_runtime_dir`, `sim_events_log`, `publish_sim_webos_major` and //! `synthetic_home_initial`, the one `app` item re-exported at the crate root. `HostEvent`, the loop's own event type, stays //! private: a platform reports input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 -//! amended): `Shell`, `Surface`, `Platform`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` -//! are reachable only through this module (`Services` is `plx_os::tv::Services`, a lower layer's type that this -//! module re-exports for one-stop naming). +//! amended): the eight application-crate items `Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, +//! `Composition`, `Exit` and `Release` are reachable only through this module. `Services` is not one of the eight: +//! it is `plx_os::tv::Services`, already a `pub` type of a lower crate, which this module re-exports so that a +//! platform crate names `host` alone. //! //! The split is by thread. A [`Platform`] is registration data in a `static`: function pointers and //! `&'static dyn` of `Sync` types, [`Shell`] included as a factory. The thread-affine state (the window, From b5d4098b8444bb36f1120289430f9e463a72d756 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 06:02:57 +0300 Subject: [PATCH 10/11] A source pin holds the crate's surface to host, and the docs stop saying a platform crate names host alone The owner's ruling that host is the only way into the application was held by nothing: the integration test reads only its own spelling, so `pub mod app;` or `pub use app::platform::Shell;` in lib.rs left every test green. host.rs now carries two pins in the style of port.rs and boot.rs. One holds lib.rs's pub items to host plus the simulator's hostsim-only doors (each checked to sit behind feature = "hostsim"). The other makes host.rs the only `pub use crate::app` site across src/**, apart from the root's hostsim-only synthetic_home_initial. Both fail with how to proceed: extend the set deliberately, and why Decision 3's 2026-11-21 amendment is the reason. The "names host alone" claim was false: building a Services names plx_os::tv's hook tables and MediaBoot::compose takes plx_media's PlayerAdapter, and host does not re-export them. The amendment, section 8's interface and gate bullets, the W7 entry, agent-reference and the host.rs and test-file docs now say a platform crate names the application crate's types through host alone and depends on plx_os and plx_media directly, and the test file claims only its own spelling. Co-Authored-By: Claude Sonnet 5.5 --- docs/agent-reference.md | 5 +- docs/platform-ports.md | 30 ++++-- rust-modules/src/host.rs | 146 ++++++++++++++++++++++++++- rust-modules/tests/host_interface.rs | 14 ++- 4 files changed, 178 insertions(+), 17 deletions(-) diff --git a/docs/agent-reference.md b/docs/agent-reference.md index ba1b1d1ee..47802e741 100644 --- a/docs/agent-reference.md +++ b/docs/agent-reference.md @@ -334,7 +334,7 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y counted or reclaimed them (28 of them, 45.6 GiB, were found in `/tmp` on 2026-10-19). Refused under `RELEASE=1`; `ci/test_managed_targets.py` pins that the target dir is inside the checkout. - `make test-host-interface` — W7a's gate (`docs/platform-ports.md`, Target shape 8): the application crate's - `host` module (`rust-modules/src/host.rs`, the one path a platform crate names) used from OUTSIDE the crate by + `host` module (`rust-modules/src/host.rs`, the one path a platform crate names the application's types by) used from OUTSIDE the crate by `rust-modules/tests/host_interface.rs`, an integration test and so a crate of its own. It builds a `static Platform` from a fake `Shell`, `Surface` and `FrameProbe`, boots it through `host::run` (the real `run_application`) and asserts that `init` ran before `open`, the `OpenAsk` the application made, and the fake's @@ -345,7 +345,8 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y replaces the process's panic hook (`install_panic_logger`, which wraps the previous hook and also writes the event and crash logs), and only one test in the file boots, because the platform's services install once per process. The file also holds a source scan that every path into the application crate starts - `plxnative_modules::host`. Same shape as `test-hostsim`: incremental in `rust-modules/target-hostsim`, through + `plxnative_modules::host` (its own spelling only; the crate's surface is pinned by `host.rs`'s tests, which + `make test-crate C=plxnative_modules` runs). Same shape as `test-hostsim`: incremental in `rust-modules/target-hostsim`, through `$(UNIT_RUN)` (a `--test` line is passed through), refused under `RELEASE=1`, in `SIDE_EFFECT_FREE` and `DISK_ENTRIES`. `make check` runs the same test non-incrementally as the second cargo line of `check-cargo-unit-hostsim` (`--lib` never builds an integration test), pinned in `ci/test_ci_split.py`'s `GATES`. diff --git a/docs/platform-ports.md b/docs/platform-ports.md index 348940f2e..d58d8d2ae 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -1189,7 +1189,12 @@ Ecore names to `remote_token_key` pairs". `Composition`, `Exit`, `Release`) are reachable ONLY through `host` (owner ruling, 2026-11-21; Decision 3, amended): `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are `pub` in a private module, so no path outside `host` names them. `Services` is not one of the eight: it stays `plx_os::tv::Services`, - already a `pub` type of a lower crate, which `host` re-exports so that a platform crate names `host` alone. The split is by thread: registration data (the `static + already a `pub` type of a lower crate, which `host` re-exports beside them. A platform crate names the APPLICATION + crate's types through `host` alone, but not everything it builds is the application's: a `Services` is built from + the hook tables of `plx_os::tv` (`IdentityHooks`, `SecureHooks`, `SystemHooks`, `StorageHooks`, `LegacyWebosMedia`, + `LocaleReply`) and `MediaBoot::compose` takes `plx_media::player::adapter::PlayerAdapter`, so a platform crate + depends on `plx_os` and `plx_media` directly, as well as on the application crate. `host` does not re-export them. + The split is by thread: registration data (the `static PLATFORM`: function pointers and `&'static dyn` of `Sync` types, `Shell` included as a factory) is `Sync` and shared; thread-affine state (window, GL context, the Ecore handles) lives only in a `Surface` that `Shell::open(&self, &MainThread, &OpenAsk)` returns on the loop thread and that the app owns inside `App`. @@ -1201,7 +1206,8 @@ Ecore names to `remote_token_key` pairs". required, `poll` is defaulted to `false` and `#[doc(hidden)]`, and the loop's `drain_sdl` drains `poll` as before and then calls `deliver` once. The SDL shells deliver nothing through the sink, so every SDL event still comes through `poll` (a unit test pins both). `poll` is RETIRED once the SDL shells deliver through the sink, W9 at the latest. -- Gate. Before extraction, a platform is compiled against `host` alone: an integration test +- Gate. Before extraction, a platform is compiled against the application crate through `host` alone (and against + `plx_os` and `plx_media` for the hook tables and `PlayerAdapter` it names): an integration test (`rust-modules/tests/host_interface.rs`, a separate crate that can name only `pub` items) builds a `static PLATFORM` from a fake `Shell`, `Surface` and `FrameProbe` and boots it through the real `run_application` (`host::run`) to the fake `Shell::open`'s refusal, under `hostsim` and a throwaway `PLXNATIVE_RUNTIME_DIR`. It @@ -1210,7 +1216,11 @@ Ecore names to `remote_token_key` pairs". (`init_gl` links the renderer's programs), which need a current GL context, and nothing stubs GL under `test-support`. The loop's fake-surface tests stay in the crate (`make test-hostsim`). The test's one source rule is that every path into the application crate begins `plxnative_modules::host`; the lower-layer crates a platform - lists as its own dependencies (`plx_os`, `plx_media`) are fair to name. W7b extracts only after it passes. + lists as its own dependencies (`plx_os`, `plx_media`) are fair to name, and it must, as above. That rule holds + only this file's own spelling. The crate's SURFACE is held by an in-crate source pin in `host.rs`'s tests (`make + test-crate C=plxnative_modules`): the crate root's `pub` items are `host` plus the `hostsim`-only simulator + doors, and `host.rs` is the only `pub use crate::app` site, apart from the root's `hostsim`-only + `synthetic_home_initial`. W7b extracts only after it passes. - Runner (G8; F52). As of `e9924f0f9` no target ran it (every one was `cargo test --lib`; `rust-modules/tests/` did not exist), so a test file alone would have been a gate nobody ran. W7a added (1) `make test-host-interface`: `cargo test -p plxnative-modules --features hostsim --test host_interface`, incrementally in `target-hostsim` like @@ -1683,7 +1693,9 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). amended 2026-11-21). - The Cargo mechanism of the PLATFORM axis lands here: the ARM recipe passes `RUST_FEATFLAGS` (`Makefile:1023-1024`), so each platform crate depends on the app with `default-features = false` and forwards - every app feature the Makefile passes (`rust-modules/Cargo.toml:78-82`), same defaults. + every app feature the Makefile passes (`rust-modules/Cargo.toml:78-82`), same defaults. W7b's platform crates + also depend on `plx_os` and `plx_media` directly: the hook tables of `Services` and `PlayerAdapter` are theirs, and + `host` does not re-export them (`rust-modules/tests/host_interface.rs` shows what a platform crate names). - Files: `src/lib.rs`, `src/host.rs`, `rust-modules/tests/host_interface.rs`, `rust-modules/Cargo.toml`, the `Makefile` `RUST_LIB` and `cargo rustc` lines and (W7a, G8; F52) the new `test-host-interface` target with its `DISK_ENTRIES` entry and a line in `check-cargo-unit-hostsim`, `ci/test_ci_split.py` (its `GATES`), `ci/check-staticlib-artifact.py` @@ -1694,7 +1706,9 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). - As landed (W7a): the interface, not the move. `src/host.rs` is the one public module of a television build (re-exports and `run`; a `hostsim` build keeps the simulator binary's own doors), the eight application-crate items of the owner's ruling are reachable through it only (`Services` is `plx_os`'s own `pub` type, re-exported), and `rust-modules/tests/host_interface.rs` builds a `static Platform` from fakes and boots it through `host::run` to the fake shell's refusal, with a source scan - that holds every mention of the application crate to `plxnative_modules::host`. The test has no `[[test]]` + that holds every mention of the application crate in that file to `plxnative_modules::host`; the crate's own + surface is held by a source pin in `host.rs`'s tests. A platform crate depends on `plx_os` and `plx_media` as well as + the application crate. The test has no `[[test]]` entry (cargo discovers `tests/*.rs`), so no `Cargo.toml` and no `ci/proofs` certificate changed. `make test-host-interface` is the incremental loop and `check-cargo-unit-hostsim` runs the same line, pinned in `ci/test_ci_split.py` (`GATES`). `Surface::poll` and `Surface::deliver` coexist until W9 retires `poll`; the SDL @@ -1867,8 +1881,10 @@ emulator runs E11 and E12); they are recorded below and the body follows them. - 2026-11-21, Decision 3 amended (owner): the EIGHT application-crate items `Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, never as general `pub` items of the application crate. `Services` is not one of the eight: it is - `plx_os::tv::Services`, already a `pub` type of a lower crate, which `host` re-exports so that a platform crate - names `host` alone. `HostEvent` stays app-private, and `EventSink` is the public face of input (it too is + `plx_os::tv::Services`, already a `pub` type of a lower crate, which `host` re-exports beside them. A platform + crate names the application crate's types through `host` alone; the hook tables a `Services` is built from + (`plx_os::tv`) and `PlayerAdapter` (`plx_media`) come from their own crates, which it depends on directly. + `HostEvent` stays app-private, and `EventSink` is the public face of input (it too is reachable only through `host`). This replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and only `Shell`. - 2026-11-20, Decision 4 (order): A. The three contracts (W3a-c) first, then the rest, the Samsung-facing types diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs index 41bc3d996..8a7223ace 100644 --- a/rust-modules/src/host.rs +++ b/rust-modules/src/host.rs @@ -12,8 +12,10 @@ //! private: a platform reports input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 //! amended): the eight application-crate items `Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, //! `Composition`, `Exit` and `Release` are reachable only through this module. `Services` is not one of the eight: -//! it is `plx_os::tv::Services`, already a `pub` type of a lower crate, which this module re-exports so that a -//! platform crate names `host` alone. +//! it is `plx_os::tv::Services`, already a `pub` type of a lower crate, which this module re-exports beside them. +//! A platform crate names the application crate's types through `host` alone; the hook tables a `Services` is +//! built from (`plx_os::tv`) and `PlayerAdapter`, which `MediaBoot::compose` takes (`plx_media`), come from +//! their own crates, which it depends on directly. //! //! The split is by thread. A [`Platform`] is registration data in a `static`: function pointers and //! `&'static dyn` of `Sync` types, [`Shell`] included as a factory. The thread-affine state (the window, @@ -22,7 +24,7 @@ //! //! Beside the platform's own types, the vocabulary their signatures name is re-exported from the lower //! layers it lives in ([`MainThread`], [`Action`], [`Edge`], [`RawKey`], [`Lifecycle`], [`PointerEdge`], -//! [`OpenAsk`], [`Placement`]), so a platform crate names the application's own types through `host` alone. +//! [`OpenAsk`], [`Placement`]), so a platform crate names the application crate's types, and the vocabulary they use, through `host` alone. //! The two SDL helpers (`sdl_init`, `sdl_open`) are not here: W7b publishes what the two real platforms need. use std::ffi::CStr; use std::os::raw::c_int; @@ -45,3 +47,141 @@ pub use plx_ui::consts::{Action, RawKey}; pub fn run(platform: &'static Platform, pms_host: &CStr, pms_port: u16) -> Exit { crate::app::run_application(platform, pms_host.as_ptr(), c_int::from(pms_port)) } + +/// **The owner's ruling, held in the source.** `tests/host_interface.rs` is a separate crate and reads only its own +/// spelling, so nothing there stops `lib.rs` from growing `pub mod app;` or `pub use app::platform::Shell;`: every +/// test would still pass. These pins read the crate's own source, in the style of the `include_str!` pins of +/// `port.rs` and `app/boot.rs`, and fail on that edit. The reason is Decision 3's amendment of 2026-11-21 +/// (`docs/platform-ports.md`): `host` is the only way a platform crate reaches the application's types. +#[cfg(test)] +mod surface_pin_tests { + use std::path::Path; + + /// What the crate root may make `pub`, by the head of the item: `host`, and the simulator binary's own doors + /// (a separate crate, so they must be `pub`), each behind `feature = "hostsim"`. `host` alone is open to a + /// television build. + const ROOT_ITEMS: [(&str, bool); 7] = [ + ("pub mod host", false), + ("pub mod hud_cli", true), + ("pub mod platform_desktop", true), + ("pub fn sim_runtime_dir", true), + ("pub fn publish_sim_webos_major", true), + ("pub fn sim_events_log", true), + ("pub use app::synthetic_home_initial", true), + ]; + + const HOW_TO_PROCEED: &str = "The application is reachable only through `host` (the crate root also keeps the simulator's \ + `hostsim`-only doors, ROOT_ITEMS), because the owner's 2026-11-21 amendment to Decision 3 \ + (docs/platform-ports.md) makes `host` the only way a platform crate reaches the application. If this edit is \ + deliberate, extend ROOT_ITEMS in this test (or the one allowed `pub use` below) AND record the reason in that \ + amendment; do not publish an application item from lib.rs or from another module."; + + /// The text of `item`'s head: up to its first `;`, `{`, `(` or `<`. + fn head(line: &str) -> &str { + let end = line.find([';', '{', '(', '<']).unwrap_or(line.len()); + line[..end].trim() + } + + /// Whether the attributes directly above line `at` gate the item behind `feature = "hostsim"` (a `not(...)` does + /// not count), skipping the doc and line comments that sit between them. + fn gated_behind_hostsim(lines: &[&str], at: usize) -> bool { + let mut gated = false; + for line in lines[..at].iter().rev().map(|l| l.trim()) { + if line.starts_with("#[") { + gated |= line.starts_with("#[cfg(") && line.contains("feature = \"hostsim\"") && !line.contains("not("); + } else if !line.starts_with("//") { + break; + } + } + gated + } + + #[test] + fn the_crate_root_publishes_host_and_the_simulators_hostsim_doors_and_nothing_else() { + let source = include_str!("lib.rs"); + let lines: Vec<&str> = source.lines().collect(); + let mut seen = Vec::new(); + for (at, line) in lines.iter().enumerate() { + let line = line.trim_start(); + // `pub(crate)` has no space after `pub`, so it is not public and is not matched. + if !line.starts_with("pub ") { + continue; + } + let item = head(line); + let Some(&(_, hostsim_only)) = ROOT_ITEMS.iter().find(|(known, _)| *known == item) else { + panic!("lib.rs line {} makes `{item}` public. {HOW_TO_PROCEED}", at + 1); + }; + assert!( + !hostsim_only || gated_behind_hostsim(&lines, at), + "lib.rs line {}: `{item}` is a simulator door and must be behind `feature = \"hostsim\"`, or a \ + television build exposes it. {HOW_TO_PROCEED}", + at + 1 + ); + seen.push(item); + } + for (item, _) in ROOT_ITEMS { + assert!(seen.contains(&item), "lib.rs no longer makes `{item}` public: update ROOT_ITEMS to match. {HOW_TO_PROCEED}"); + } + // An exported macro is a public path into the crate that a `pub ` line scan cannot see. + assert!(!source.contains(concat!("#[macro_", "export")), "lib.rs exports a macro. {HOW_TO_PROCEED}"); + } + + /// `pub use` statements of `text`, each as `(line number, its text after `pub use` with whitespace removed)`. + /// A statement runs to its `;`, so a `{ ... }` list over several lines is one. + fn pub_uses(text: &str) -> Vec<(usize, String)> { + let mut found = Vec::new(); + let mut lines = text.lines().enumerate(); + while let Some((at, line)) = lines.next() { + let Some(rest) = line.trim_start().strip_prefix("pub use ") else { continue }; + let mut statement = rest.to_string(); + while !statement.contains(';') { + match lines.next() { + Some((_, more)) => statement.push_str(more), + None => break, + } + } + found.push((at + 1, statement.split_whitespace().collect())); + } + found + } + + fn rust_sources(dir: &Path, root: &Path, out: &mut Vec<(String, String)>) { + let mut entries: Vec<_> = std::fs::read_dir(dir).expect("the source directory").map(|e| e.expect("an entry").path()).collect(); + entries.sort(); + for path in entries { + if path.is_dir() { + rust_sources(&path, root, out); + } else if path.extension().is_some_and(|e| e == "rs") { + let name = path.strip_prefix(root).expect("under the root").to_string_lossy().into_owned(); + out.push((name, std::fs::read_to_string(&path).expect("a source file"))); + } + } + } + + #[test] + fn host_is_the_only_place_that_re_exports_the_application() { + let root = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/src")); + let mut files = Vec::new(); + rust_sources(root, root, &mut files); + assert!(files.iter().any(|(name, _)| name == "host.rs"), "the scan did not read this crate's own sources"); + let mut in_host = 0; + for (name, text) in &files { + for (at, statement) in pub_uses(text) { + let names_app = ["crate::app::", "crate::{app", "app::", "{app"].iter().any(|p| statement.trim_start_matches("::").starts_with(p)); + if !names_app { + continue; + } + if name == "host.rs" { + in_host += 1; + } else { + // The one other: the root's `hostsim`-only `synthetic_home_initial`, which the simulator binary calls. + assert!( + name == "lib.rs" && statement == "app::synthetic_home_initial;", + "{name} line {at} re-exports from the application (`pub use {statement}`). {HOW_TO_PROCEED}" + ); + } + } + } + assert!(in_host >= 2, "host.rs re-exports the application's types: the scan found {in_host} `pub use` of `crate::app`"); + } +} diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs index 0f53caf52..74d01a169 100644 --- a/rust-modules/tests/host_interface.rs +++ b/rust-modules/tests/host_interface.rs @@ -1,4 +1,5 @@ -//! W7a's gate: a platform built against `plxnative_modules::host` alone (`docs/platform-ports.md`, +//! W7a's gate: a platform built against the application crate through `plxnative_modules::host`, with the hook +//! tables of `plx_os::tv` and `plx_media`'s `PlayerAdapter` from their own crates (`docs/platform-ports.md`, //! Target shape 8). //! //! This is an integration test, a separate crate that can name only the `pub` items of the application @@ -219,10 +220,13 @@ fn an_event_sink_is_implementable_from_outside_and_receives_a_surfaces_events_in ); } -/// **The one source rule of this file** (it is how "against `host` alone" is held): every path into the -/// application crate starts `plxnative_modules::host`. The lower-layer crates a platform crate lists as its -/// own dependencies (`plx_os`, `plx_media`) are fine to name; the application's private modules are not -/// reachable, and this keeps a future edit from reaching for a re-export that would widen the surface. +/// **The one source rule of this file**, and it holds this file's own spelling only: every path into the +/// application crate starts `plxnative_modules::host`. What the crate itself makes reachable is not read here; +/// that is pinned in-crate, by the source pins in `host.rs`'s tests (the crate root's `pub` items, and `host.rs` as +/// the only `pub use crate::app` site). The lower-layer crates a platform crate lists as its +/// own dependencies (`plx_os`, `plx_media`) are fine to name, and this file must (a `Services` is built from +/// `plx_os::tv`'s hook tables, `MediaBoot::compose` takes `plx_media`'s `PlayerAdapter`); an edit to this file that +/// names the application crate any other way fails here. #[test] fn every_path_into_the_application_crate_goes_through_host() { let source = include_str!("host_interface.rs"); From 9ce0310c582599e30a4c9b6210f8ac016df3a72e Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Sat, 21 Nov 2026 06:18:05 +0300 Subject: [PATCH 11/11] The surface pins judge a cfg by what it implies and a pub use by whether `app` is anywhere in its tree The first pin took any cfg attribute containing feature = "hostsim" and not(...) as confining a door to the simulator. That passed `any(test, feature = "hostsim", feature = "devtriggers")`, which a default television build compiles (devtriggers is on by default), and failed a multi-line attribute and an `all` with a `not`. Each attribute is now joined across its lines and evaluated for a build without hostsim or test: the door is confined only if the predicate cannot be true there. The second pin read only a `pub use` that began crate::app or app::, so `super::app::...` in a module under src/, `self::app::...` in lib.rs and `crate::{host, app::X}` slipped through. It now flags any `pub use` outside host.rs whose tree has `app` as a path segment, keeping the one exception. The failure message's first remedy is now to re-export the item from host.rs, which the second pin allows; extending ROOT_ITEMS is for a new simulator door that is not an application item. Co-Authored-By: Claude Sonnet 5.5 --- docs/platform-ports.md | 2 +- rust-modules/src/host.rs | 129 +++++++++++++++++++-------- rust-modules/tests/host_interface.rs | 2 +- 3 files changed, 93 insertions(+), 40 deletions(-) diff --git a/docs/platform-ports.md b/docs/platform-ports.md index d58d8d2ae..2ce14a879 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -1219,7 +1219,7 @@ Ecore names to `remote_token_key` pairs". lists as its own dependencies (`plx_os`, `plx_media`) are fair to name, and it must, as above. That rule holds only this file's own spelling. The crate's SURFACE is held by an in-crate source pin in `host.rs`'s tests (`make test-crate C=plxnative_modules`): the crate root's `pub` items are `host` plus the `hostsim`-only simulator - doors, and `host.rs` is the only `pub use crate::app` site, apart from the root's `hostsim`-only + doors (each confined to `hostsim`, or `test`, by its `cfg`), and `host.rs` is the only `pub use` whose tree names `app` (as `crate::app`, `super::app`, `self::app` or in a group), apart from the root's `hostsim`-only `synthetic_home_initial`. W7b extracts only after it passes. - Runner (G8; F52). As of `e9924f0f9` no target ran it (every one was `cargo test --lib`; `rust-modules/tests/` did not exist), so a test file alone would have been a gate nobody ran. W7a added (1) `make test-host-interface`: `cargo diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs index 8a7223ace..d68f91eb4 100644 --- a/rust-modules/src/host.rs +++ b/rust-modules/src/host.rs @@ -58,8 +58,8 @@ mod surface_pin_tests { use std::path::Path; /// What the crate root may make `pub`, by the head of the item: `host`, and the simulator binary's own doors - /// (a separate crate, so they must be `pub`), each behind `feature = "hostsim"`. `host` alone is open to a - /// television build. + /// (a separate crate, so they must be `pub`), each existing only under `feature = "hostsim"`. `host` alone is + /// open to a television build. const ROOT_ITEMS: [(&str, bool); 7] = [ ("pub mod host", false), ("pub mod hud_cli", true), @@ -70,57 +70,105 @@ mod surface_pin_tests { ("pub use app::synthetic_home_initial", true), ]; - const HOW_TO_PROCEED: &str = "The application is reachable only through `host` (the crate root also keeps the simulator's \ - `hostsim`-only doors, ROOT_ITEMS), because the owner's 2026-11-21 amendment to Decision 3 \ - (docs/platform-ports.md) makes `host` the only way a platform crate reaches the application. If this edit is \ - deliberate, extend ROOT_ITEMS in this test (or the one allowed `pub use` below) AND record the reason in that \ - amendment; do not publish an application item from lib.rs or from another module."; + const HOW_TO_PROCEED: &str = "The application is reachable only through `host`, because the owner's 2026-11-21 amendment to \ + Decision 3 (docs/platform-ports.md) makes `host` the only way a platform crate reaches it. To publish an \ + application item (W7b's `sdl_init` and `sdl_open`, say), re-export it from host.rs, which the second pin allows. \ + Only a new simulator door that is NOT an application item, existing only under `feature = \"hostsim\"`, extends \ + ROOT_ITEMS in this test, and the reason is recorded in that amendment."; - /// The text of `item`'s head: up to its first `;`, `{`, `(` or `<`. + /// The text of an item's head: up to its first `;`, `{`, `(` or `<`. fn head(line: &str) -> &str { let end = line.find([';', '{', '(', '<']).unwrap_or(line.len()); line[..end].trim() } - /// Whether the attributes directly above line `at` gate the item behind `feature = "hostsim"` (a `not(...)` does - /// not count), skipping the doc and line comments that sit between them. - fn gated_behind_hostsim(lines: &[&str], at: usize) -> bool { - let mut gated = false; - for line in lines[..at].iter().rev().map(|l| l.trim()) { + /// `(can be true, can be false)` for the cfg predicate at the start of `s` (whitespace removed), in a build with + /// neither `hostsim` nor `test` and whatever else set; also returns the rest of `s`. Any other predicate may be + /// either, so an `any(...)` naming another feature (`devtriggers` is on by default) can be true. + fn can_be(s: &str) -> ((bool, bool), &str) { + let end = s.find(|c: char| !(c.is_alphanumeric() || c == '_')).unwrap_or(s.len()); + let (name, rest) = s.split_at(end); + if let Some(mut rest) = rest.strip_prefix('(') { + let mut parts = Vec::new(); + while !rest.starts_with(')') { + assert!(!rest.is_empty(), "an unbalanced cfg predicate"); + let (part, after) = can_be(rest); + parts.push(part); + rest = after.strip_prefix(',').unwrap_or(after); + } + let result = match name { + "any" => (parts.iter().any(|p| p.0), parts.iter().all(|p| p.1)), + "all" => (parts.iter().all(|p| p.0), parts.iter().any(|p| p.1)), + "not" => (parts[0].1, parts[0].0), + other => panic!("an unknown cfg combinator `{other}`"), + }; + return (result, &rest[1..]); + } + if let Some(value) = rest.strip_prefix("=\"") { + let (value, after) = value.split_once('"').expect("a closed string"); + let never = name == "feature" && value == "hostsim"; + return ((!never, true), after); + } + (((name != "test"), true), rest) + } + + /// Whether the attribute `attr` (whitespace removed) is a `cfg` under which the item cannot exist without + /// `hostsim` or `test`: `feature = "hostsim"`, an `any` of those two, or an `all` with `hostsim` among its members. + fn confines_to_hostsim(attr: &str) -> bool { + let predicate = attr.strip_prefix("#[cfg(").and_then(|a| a.strip_suffix(")]")); + predicate.is_some_and(|p| !can_be(p).0 .0) + } + + /// The `pub` items of `source` (not `pub(crate)`, which has no space after `pub`) as `(line, head, confined)`. + /// An attribute may span lines, so each is read to its closing bracket and joined before it is judged. + fn public_items(source: &str) -> Vec<(usize, String, bool)> { + let mut found = Vec::new(); + let mut attrs: Vec = Vec::new(); + let mut lines = source.lines().enumerate(); + while let Some((at, line)) = lines.next() { + let line = line.trim(); + if line.is_empty() || line.starts_with("//") { + continue; + } if line.starts_with("#[") { - gated |= line.starts_with("#[cfg(") && line.contains("feature = \"hostsim\"") && !line.contains("not("); - } else if !line.starts_with("//") { - break; + let mut attr = line.to_string(); + while attr.matches('[').count() > attr.matches(']').count() { + match lines.next() { + Some((_, more)) => attr.push_str(more.trim()), + None => break, + } + } + attrs.push(attr.split_whitespace().collect()); + continue; } + if line.starts_with("pub ") { + found.push((at + 1, head(line).to_string(), attrs.iter().any(|a| confines_to_hostsim(a)))); + } + attrs.clear(); } - gated + found } #[test] fn the_crate_root_publishes_host_and_the_simulators_hostsim_doors_and_nothing_else() { let source = include_str!("lib.rs"); - let lines: Vec<&str> = source.lines().collect(); - let mut seen = Vec::new(); - for (at, line) in lines.iter().enumerate() { - let line = line.trim_start(); - // `pub(crate)` has no space after `pub`, so it is not public and is not matched. - if !line.starts_with("pub ") { - continue; - } - let item = head(line); - let Some(&(_, hostsim_only)) = ROOT_ITEMS.iter().find(|(known, _)| *known == item) else { - panic!("lib.rs line {} makes `{item}` public. {HOW_TO_PROCEED}", at + 1); + let items = public_items(source); + for (at, item, confined) in &items { + let Some(&(_, hostsim_only)) = ROOT_ITEMS.iter().find(|&&(known, _)| known == item.as_str()) else { + panic!("lib.rs line {at} makes `{item}` public. {HOW_TO_PROCEED}"); }; assert!( - !hostsim_only || gated_behind_hostsim(&lines, at), - "lib.rs line {}: `{item}` is a simulator door and must be behind `feature = \"hostsim\"`, or a \ - television build exposes it. {HOW_TO_PROCEED}", - at + 1 + !hostsim_only || *confined, + "lib.rs line {at}: `{item}` is a simulator door and must exist only under `feature = \"hostsim\"` (with \ + `test` or `all(..)` at most): an `any(..)` naming another feature, `devtriggers` being on by default, \ + ships it in a television build. {HOW_TO_PROCEED}" ); - seen.push(item); } - for (item, _) in ROOT_ITEMS { - assert!(seen.contains(&item), "lib.rs no longer makes `{item}` public: update ROOT_ITEMS to match. {HOW_TO_PROCEED}"); + for (known, _) in ROOT_ITEMS { + assert!( + items.iter().any(|(_, item, _)| item == known), + "lib.rs no longer makes `{known}` public: update ROOT_ITEMS to match. {HOW_TO_PROCEED}" + ); } // An exported macro is a public path into the crate that a `pub ` line scan cannot see. assert!(!source.contains(concat!("#[macro_", "export")), "lib.rs exports a macro. {HOW_TO_PROCEED}"); @@ -145,6 +193,12 @@ mod surface_pin_tests { found } + /// Whether a `pub use` tree has `app` as a path segment anywhere: `crate::app::X`, `super::app::X` (from a module + /// directly under `src/`), `self::app::X` (from `lib.rs`), `app::X` and `crate::{host, app::X}` all do. + fn names_the_application(statement: &str) -> bool { + statement.split(|c: char| !(c.is_alphanumeric() || c == '_')).any(|segment| segment == "app") + } + fn rust_sources(dir: &Path, root: &Path, out: &mut Vec<(String, String)>) { let mut entries: Vec<_> = std::fs::read_dir(dir).expect("the source directory").map(|e| e.expect("an entry").path()).collect(); entries.sort(); @@ -167,8 +221,7 @@ mod surface_pin_tests { let mut in_host = 0; for (name, text) in &files { for (at, statement) in pub_uses(text) { - let names_app = ["crate::app::", "crate::{app", "app::", "{app"].iter().any(|p| statement.trim_start_matches("::").starts_with(p)); - if !names_app { + if !names_the_application(&statement) { continue; } if name == "host.rs" { @@ -182,6 +235,6 @@ mod surface_pin_tests { } } } - assert!(in_host >= 2, "host.rs re-exports the application's types: the scan found {in_host} `pub use` of `crate::app`"); + assert!(in_host >= 2, "host.rs re-exports the application's types: the scan found {in_host} `pub use` of `app`"); } } diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs index 74d01a169..b751cc798 100644 --- a/rust-modules/tests/host_interface.rs +++ b/rust-modules/tests/host_interface.rs @@ -223,7 +223,7 @@ fn an_event_sink_is_implementable_from_outside_and_receives_a_surfaces_events_in /// **The one source rule of this file**, and it holds this file's own spelling only: every path into the /// application crate starts `plxnative_modules::host`. What the crate itself makes reachable is not read here; /// that is pinned in-crate, by the source pins in `host.rs`'s tests (the crate root's `pub` items, and `host.rs` as -/// the only `pub use crate::app` site). The lower-layer crates a platform crate lists as its +/// the only `pub use` that names `app`). The lower-layer crates a platform crate lists as its /// own dependencies (`plx_os`, `plx_media`) are fine to name, and this file must (a `Services` is built from /// `plx_os::tv`'s hook tables, `MediaBoot::compose` takes `plx_media`'s `PlayerAdapter`); an edit to this file that /// names the application crate any other way fails here.