From 641ba143a583dd359ea1701efa2466e6f6925251 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Fri, 20 Nov 2026 15:59:41 +0300 Subject: [PATCH 1/2] The platform states where the account's records live: tv::Services.storage The session, the install's preferences and the consent record live in the LS2/DB8 storage helper on a webOS television and in files everywhere else. The persistence layers chose between the two with `all(target_os = "linux", target_arch = "arm", not(feature = "hostsim"), not(any(test, feature = "test-support")))`, which is "32-bit ARM Linux", not "a television": a Tizen ARM build would select the helper with none behind it. `tv::Services` gains a fifth group, `storage: StorageHooks { authority }`, in the new `os/src/tv/authority.rs`. `Authority::Helper` is webOS (`port.rs`); `Authority::Files` is the desktop platform, `Services::HOST_TEST` and any platform with no helper (`StorageHooks::NONE`). `tv::authority::authority()` reads the installed table, and an uninstalled process reads `Files` like every other group's host-test answer. There is deliberately no test override: the layers that read it take the authority as a parameter, so a test passes whichever one it grades. Nothing reads the value yet; the plex and telemetry lanes re-key their fences to it next. Tests pin the host-test answer in the destructuring test of `tv.rs`, the webOS and desktop tables, and the order `run_application` installs the services before it enters the application: an uninstalled television would read `Files` and write a plaintext session file. Co-Authored-By: Claude --- docs/module-layers.md | 2 +- docs/platform-ports.md | 4 ++ rust-modules/os/src/tv.rs | 10 ++++- rust-modules/os/src/tv/authority.rs | 65 ++++++++++++++++++++++++++++ rust-modules/src/platform_desktop.rs | 12 ++++- rust-modules/src/port.rs | 44 ++++++++++++++++++- 6 files changed, 132 insertions(+), 5 deletions(-) create mode 100644 rust-modules/os/src/tv/authority.rs diff --git a/docs/module-layers.md b/docs/module-layers.md index 06df7a3e2..714e30989 100644 --- a/docs/module-layers.md +++ b/docs/module-layers.md @@ -350,7 +350,7 @@ L15's 44 entries, 205 references of which 95 were in production code. The port's their layers, so none of this held up the split. L15 moved every one of those references behind an interface in `os`'s new `tv` module that -the port fills at boot. `tv::Services` is a table of function pointers in four groups (`identity`, `secure`, `system` and `legacy_webos_media`), installed once by `app::run_application` (from the `Platform` its entry hands it) before anything +the port fills at boot. `tv::Services` is a table of function pointers and stated values in five groups (`identity`, `secure`, `system`, `storage` and `legacy_webos_media`), installed once by `app::run_application` (from the `Platform` its entry hands it) before anything that reads it. With nothing installed (host unit tests, where nothing calls `plex_run`) `tv::Services::HOST_TEST` answers what the host arms answered before; a shipping build that reaches it logs `tv: port not installed - using the no-port defaults` once. diff --git a/docs/platform-ports.md b/docs/platform-ports.md index 45f9329ff..477fa0d54 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -848,6 +848,10 @@ split by who reads it (critic M4): `devcaps` parses through, `Files::NONE` for a platform with none); - `secure { seal, open, remove, mode }` (Target shape 4; until W2 `mode` is W3a's own once-set value); - `system { go_home, poll_home, deliver_toast }`; + - `storage { authority }` (W8a): `Authority::Helper` (webOS: the LS2/DB8 storage helper owns the session, the + install's preferences and the consent record) or `Authority::Files` (desktop, Tizen, a host test), read through + `tv::authority::authority()`. It replaces the `target_os = "linux"` + `target_arch = "arm"` fence the persistence + layers chose their store by; the helper's wake-up (`storage::client::install_activator`) joins it after W7b; - `legacy_webos_media { sink, display_sink, uri_media }`: the Starfish, ACB and `com.webos.media` verbs (F31), named for what they are (critic M3). Every hook is required (Decision 2, C): a platform states each field, a named `NONE` being a statement and a `Default`-filled gap not allowed. The one exemption is this group: diff --git a/rust-modules/os/src/tv.rs b/rust-modules/os/src/tv.rs index 4d372c779..4a2264b99 100644 --- a/rust-modules/os/src/tv.rs +++ b/rust-modules/os/src/tv.rs @@ -1,4 +1,5 @@ //! The television, as everything outside the port sees it (step L15, docs/module-layers.md). +pub mod authority; pub mod device; pub mod home; pub mod launch; @@ -10,13 +11,15 @@ pub mod sound; pub mod toast; pub mod uri; +pub use authority::StorageHooks; + use std::sync::OnceLock; /// What the platform's settings service said about the locale. i18n owns the parse and the log lines. #[cfg_attr(any(feature = "hostsim", test, feature = "test-support"), allow(dead_code))] // Reply/Unavailable: TV arm only pub enum LocaleReply { NoPlatform, Unavailable, Reply(String) } -/// What the lower layers read from the platform, in four groups. Installed once ([`install`]) before +/// What the lower layers read from the platform, in five groups. Installed once ([`install`]) before /// anything reads it, and read only by `tv`'s own modules, so no other module can issue a verb the /// interfaces below do not offer. The window, the bus pump and the frame probe are NOT here: only /// the loop reads them, so they belong to the application's own `Platform`. @@ -28,6 +31,7 @@ pub struct Services { pub identity: IdentityHooks, pub secure: SecureHooks, pub system: SystemHooks, + pub storage: StorageHooks, pub legacy_webos_media: LegacyWebosMedia, } @@ -117,6 +121,7 @@ impl Services { identity: IdentityHooks::NONE, secure: SecureHooks::NONE, system: SystemHooks::NONE, + storage: StorageHooks::NONE, legacy_webos_media: LegacyWebosMedia::NONE, }; } @@ -159,6 +164,7 @@ mod tests { identity: IdentityHooks { probe_device, start_capability_probe, repair_native_video, device_files, system_locale, sound_output }, secure: SecureHooks { seal, open, remove, mode }, system: SystemHooks { go_home, poll_home, deliver_toast }, + storage: StorageHooks { authority }, legacy_webos_media: LegacyWebosMedia { sink, display_sink, uri_media }, } = Services::HOST_TEST; @@ -193,6 +199,8 @@ mod tests { toast::Sent { reply: None, outcome: toast::Outcome::NoBus } ); + assert_eq!(authority, authority::Authority::Files, "no storage helper: the app keeps its records in files"); + assert!(!sink.feed_abi_is_cow(), "the refusing sink, not a native one"); assert_eq!(display_sink.window_mode(), sink::VP_NONE); assert_eq!(display_sink.window_id(), c""); diff --git a/rust-modules/os/src/tv/authority.rs b/rust-modules/os/src/tv/authority.rs new file mode 100644 index 000000000..85d8dd6a2 --- /dev/null +++ b/rust-modules/os/src/tv/authority.rs @@ -0,0 +1,65 @@ +//! Where the account's canonical state lives: the platform's storage helper, or plain files. +//! +//! The session record, the install's preferences and the consent record each have two homes. On a +//! webOS television the LS2/DB8 storage helper owns them ([`Authority::Helper`]): the app never +//! reads or writes a file of its own for them. Everywhere else the app keeps them in files under its +//! persistent state root ([`Authority::Files`]): the desktop simulator, a host test, and a platform +//! with no helper at all (Tizen). The layers that persist these records (`plex::session`, +//! `telemetry`) choose their store from this value, once per operation, instead of from the build's +//! CPU and OS, which is what picked it before: a 32-bit ARM Linux binary is not necessarily a +//! television. +//! +//! The platform states it once, as the `authority` of its [`StorageHooks`](super::StorageHooks), and +//! [`authority`] reads it. A process that installed no platform (a host test) reads +//! [`StorageHooks::NONE`], which is `Files`, like every other group's host-test answer. A shipping +//! process must install its services before anything persists: an uninstalled television would read +//! `Files` and write a plaintext session file, which is why `run_application` installs them first +//! (`port::tests` pins the order). +//! +//! This group is the home of the platform's other storage statements as well. The helper's wake-up +//! (`storage::client::install_activator`, which `port::plex_main` installs for webOS today) belongs +//! here as a later member and moves with the os lane after W7b; it is not moved yet. + +/// Where the account's canonical state lives. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Authority { + /// The platform's storage helper (webOS: the LS2/DB8 service). No file of the app's own holds + /// the record, and a helper that cannot answer is never papered over with one. + Helper, + /// Files under the app's persistent state root, written by the app itself. + #[default] + Files, +} + +/// The storage group of [`Services`](super::Services): what a platform states about where the app's +/// own records live. +pub struct StorageHooks { + pub authority: Authority, +} + +impl StorageHooks { + /// A platform with no storage helper: the app keeps its records in files. + pub const NONE: Self = Self { authority: Authority::Files }; +} + +/// The installed platform's [`Authority`], or `Files` when nothing is installed. +pub fn authority() -> Authority { + super::services().storage.authority +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_default_authority_is_files() { + assert_eq!(Authority::default(), Authority::Files); + assert_eq!(StorageHooks::NONE.authority, Authority::Files, "a platform with no helper keeps files"); + } + + /// Nothing is installed in a test process, so the reader answers the host-test group's `Files`. + #[test] + fn an_uninstalled_process_reads_files() { + assert_eq!(authority(), Authority::Files); + } +} diff --git a/rust-modules/src/platform_desktop.rs b/rust-modules/src/platform_desktop.rs index b4cb8f580..3a412fb05 100644 --- a/rust-modules/src/platform_desktop.rs +++ b/rust-modules/src/platform_desktop.rs @@ -18,6 +18,8 @@ //! no compositor to hint and no bus to pump. The secure store is `SecureHooks::NONE`: nothing seals, //! so a session is the 0600 plaintext file the session layer writes itself, which the simulator's //! harnesses plant and read. +//! The storage group is `StorageHooks::NONE`: there is no storage helper, so the account's records +//! live in files under the persistent state root. //! //! This module never names `port`, `system`, `webos` or `keymanager`, so a desktop executable //! references none of the television's code. It still COMPILES it (the television arms of those @@ -28,7 +30,7 @@ use crate::app::platform::{FrameProbe, Platform, Shell}; use plx_os::devcaps::dv::{self, DvCapability, DvProbe, ProbeSource}; use plx_os::tv::toast::{Identity, Outcome, Sent}; -use plx_os::tv::{IdentityHooks, LegacyWebosMedia, SecureHooks, Services, SystemHooks}; +use plx_os::tv::{IdentityHooks, LegacyWebosMedia, SecureHooks, Services, StorageHooks, SystemHooks}; use std::ffi::CStr; use std::os::raw::{c_int, c_void}; @@ -56,6 +58,7 @@ static SERVICES: Services = Services { }, secure: SecureHooks::NONE, system: SystemHooks { go_home, poll_home: SystemHooks::NONE.poll_home, deliver_toast }, + storage: StorageHooks::NONE, legacy_webos_media: LegacyWebosMedia { sink: SINK, display_sink: DISPLAY, @@ -141,6 +144,13 @@ pub fn run(pms_host: &CStr, pms_port: u16) -> c_int { mod tests { use super::*; + /// A desktop has no storage helper: the session, the install's preferences and the consent record + /// are files. The same value a host test reads from `Services::HOST_TEST`. + #[test] + fn the_desktop_table_keeps_the_account_in_files() { + assert_eq!(SERVICES.storage.authority, plx_os::tv::authority::Authority::Files); + } + /// The app's plane boot resolves the display through `display_installed()` (this table's /// `display_sink`), where media's old `acb_init` resolved it through `player::display()`. In /// the simulator both must be the host sink, never `NoSink`: a boot that read `NoSink` would diff --git a/rust-modules/src/port.rs b/rust-modules/src/port.rs index 7f717ca52..800c426a8 100644 --- a/rust-modules/src/port.rs +++ b/rust-modules/src/port.rs @@ -20,8 +20,8 @@ const DISPLAY: &dyn plx_os::tv::sink::DisplaySink = &plx_os::webos::video_sink:: #[cfg(test)] const DISPLAY: &dyn plx_os::tv::sink::DisplaySink = SINK; -/// What the lower layers read: the webOS identity, key manager, Home key and toast, and the native -/// playback seam. The window, the bus pump and the frame probe are the loop's own, in [`PLATFORM`]. +/// What the lower layers read: the webOS identity, key manager, Home key and toast, the storage helper +/// and the native playback seam. The window, the bus pump and the frame probe are the loop's own, in [`PLATFORM`]. static SERVICES: plx_os::tv::Services = plx_os::tv::Services { identity: plx_os::tv::IdentityHooks { probe_device: plx_os::webos::probe, @@ -42,6 +42,7 @@ static SERVICES: plx_os::tv::Services = plx_os::tv::Services { poll_home: plx_os::webos::poll_home, deliver_toast: plx_os::webos::toast::deliver, }, + storage: plx_os::tv::StorageHooks { authority: plx_os::tv::authority::Authority::Helper }, legacy_webos_media: plx_os::tv::LegacyWebosMedia { sink: SINK, display_sink: DISPLAY, @@ -148,3 +149,42 @@ pub unsafe extern "C" fn plx_launch_args(json: *const c_char) { let raw = unsafe { std::ffi::CStr::from_ptr(json) }.to_string_lossy(); plx_os::tv::launch::offer(&raw); } + +#[cfg(test)] +mod tests { + use super::SERVICES; + use plx_os::tv::authority::Authority; + + /// The webOS table states the storage helper as the home of the session, the install's preferences + /// and the consent record. The persistence layers choose their store from this value, so a table + /// that stated anything else would move a television's account out of DB8. + #[test] + fn the_webos_table_states_the_storage_helper_as_the_authority() { + assert_eq!(SERVICES.storage.authority, Authority::Helper); + assert_eq!(SERVICES.secure.mode, plx_os::tv::secure::StoreMode::Durable); + } + + /// `run_application` installs the services before anything else runs. The authority is read by + /// whatever persists first, and an uninstalled television reads `Files` and would write a + /// plaintext session file, so the install has to come before `exit::entry` runs `enter_application`. + /// Reads the source, like `app::boot`'s `seam_order_tests`, because no host test can run the entry. + #[test] + fn the_services_are_installed_before_the_application_enters() { + let source = include_str!("app/mod.rs"); + let body = source + .split_once("fn run_application(") + .expect("run_application") + .1 + .split_once("\n}\n") + .expect("end of run_application") + .0; + let install = body.find("platform.install_services();").expect("run_application installs the services"); + let enter = body.find("exit::entry(").expect("run_application enters through exit::entry"); + assert!(install < enter, "install_services must run before exit::entry"); + assert_eq!( + source.matches("install_services()").count(), + 1, + "one production install; a second would be refused by tv and could hide a missing first" + ); + } +} From 9914c2dec10506e551959d6469cc837d9f395aed Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Fri, 20 Nov 2026 16:30:00 +0300 Subject: [PATCH 2/2] The storage authority's docs say what the helper and the files are on a television, and the order pin is exact Review of the foundation found three things the first commit got wrong or left weak. On webOS the helper is the canonical store, but the app's own files are not absent there: the session layer writes a marked fallback (`save_legacy_fallback_locked`) whenever a commit to the helper is not durable, serves it as transient state while the helper cannot answer (`read_legacy_filtered_locked`), and the legacy files an older build left are migration inputs. `tv::authority`'s module doc and the `Helper` variant said no file is ever written and a helper outage is never papered over; they now say what the code does. The platform-ports bullet follows. The order pin in `port.rs` asserted only that the install precedes `exit::entry`. It now asserts that `platform.install_services();` is `run_application`'s first non-comment statement, counts the call and `tv::install(` across every source file of the application crate (not just `app/mod.rs`), and fails when a statement is inserted above the install, when a second call is added, and when `tv::install` is called a second time. Each of those three mutations was run and fails for its own assertion. `authority.rs` and the `port.rs` test docs spoke as if a reader of the value already existed. They now state what the value says and what it is for. Co-Authored-By: Claude --- docs/platform-ports.md | 6 ++- rust-modules/os/src/tv/authority.rs | 37 +++++++++------- rust-modules/src/port.rs | 67 +++++++++++++++++++++-------- 3 files changed, 76 insertions(+), 34 deletions(-) diff --git a/docs/platform-ports.md b/docs/platform-ports.md index 477fa0d54..49fe3eb59 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -848,8 +848,10 @@ split by who reads it (critic M4): `devcaps` parses through, `Files::NONE` for a platform with none); - `secure { seal, open, remove, mode }` (Target shape 4; until W2 `mode` is W3a's own once-set value); - `system { go_home, poll_home, deliver_toast }`; - - `storage { authority }` (W8a): `Authority::Helper` (webOS: the LS2/DB8 storage helper owns the session, the - install's preferences and the consent record) or `Authority::Files` (desktop, Tizen, a host test), read through + - `storage { authority }` (W8a): `Authority::Helper` (webOS: the LS2/DB8 storage helper is the canonical store of + the session, the install's preferences and the consent record; the app's own files there are the legacy + migration inputs and the marked fallback of a helper outage) or `Authority::Files` (desktop, Tizen, a host + test: the app's own record files are the store), read through `tv::authority::authority()`. It replaces the `target_os = "linux"` + `target_arch = "arm"` fence the persistence layers chose their store by; the helper's wake-up (`storage::client::install_activator`) joins it after W7b; - `legacy_webos_media { sink, display_sink, uri_media }`: the Starfish, ACB and `com.webos.media` verbs (F31), diff --git a/rust-modules/os/src/tv/authority.rs b/rust-modules/os/src/tv/authority.rs index 85d8dd6a2..629a19410 100644 --- a/rust-modules/os/src/tv/authority.rs +++ b/rust-modules/os/src/tv/authority.rs @@ -1,21 +1,27 @@ //! Where the account's canonical state lives: the platform's storage helper, or plain files. //! -//! The session record, the install's preferences and the consent record each have two homes. On a -//! webOS television the LS2/DB8 storage helper owns them ([`Authority::Helper`]): the app never -//! reads or writes a file of its own for them. Everywhere else the app keeps them in files under its -//! persistent state root ([`Authority::Files`]): the desktop simulator, a host test, and a platform -//! with no helper at all (Tizen). The layers that persist these records (`plex::session`, -//! `telemetry`) choose their store from this value, once per operation, instead of from the build's -//! CPU and OS, which is what picked it before: a 32-bit ARM Linux binary is not necessarily a -//! television. +//! The session record, the install's preferences and the consent record each have one canonical +//! store, and the platform states which. On a webOS television it is the LS2/DB8 storage helper +//! ([`Authority::Helper`]). Everywhere else it is the app's own record files under its persistent +//! state root ([`Authority::Files`]): the desktop simulator, a host test, and a platform with no +//! helper at all (Tizen). //! -//! The platform states it once, as the `authority` of its [`StorageHooks`](super::StorageHooks), and -//! [`authority`] reads it. A process that installed no platform (a host test) reads +//! Under `Helper` the app's own files are not the store. They are the legacy migration inputs an +//! older build left, and the marked fallback the session layer writes when a commit to the helper is +//! not durable (a helper outage): while the helper cannot answer, that file is served as transient +//! state, and it never replaces the helper's record. +//! +//! The platform states the value once, as the `authority` of its [`StorageHooks`](super::StorageHooks), +//! and [`authority`] reads it. A process that installed no platform (a host test) reads //! [`StorageHooks::NONE`], which is `Files`, like every other group's host-test answer. A shipping -//! process must install its services before anything persists: an uninstalled television would read -//! `Files` and write a plaintext session file, which is why `run_application` installs them first +//! process has to install its services before anything persists, because an uninstalled television +//! would be told it has no helper; `run_application` installs them as its first statement //! (`port::tests` pins the order). //! +//! The value exists so that the layers that persist these records can choose their canonical store +//! from what the platform states, not from the build's CPU and OS (a 32-bit ARM Linux binary is not +//! necessarily a television). +//! //! This group is the home of the platform's other storage statements as well. The helper's wake-up //! (`storage::client::install_activator`, which `port::plex_main` installs for webOS today) belongs //! here as a later member and moves with the os lane after W7b; it is not moved yet. @@ -23,10 +29,11 @@ /// Where the account's canonical state lives. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub enum Authority { - /// The platform's storage helper (webOS: the LS2/DB8 service). No file of the app's own holds - /// the record, and a helper that cannot answer is never papered over with one. + /// The platform's storage helper (webOS: the LS2/DB8 service) is the canonical store. The app's + /// own files are only the legacy migration inputs and the session layer's marked fallback, which + /// is written during a helper outage and is never the record. Helper, - /// Files under the app's persistent state root, written by the app itself. + /// The app's own record files under its persistent state root are the canonical store. #[default] Files, } diff --git a/rust-modules/src/port.rs b/rust-modules/src/port.rs index 800c426a8..ec914547a 100644 --- a/rust-modules/src/port.rs +++ b/rust-modules/src/port.rs @@ -155,36 +155,69 @@ mod tests { use super::SERVICES; use plx_os::tv::authority::Authority; - /// The webOS table states the storage helper as the home of the session, the install's preferences - /// and the consent record. The persistence layers choose their store from this value, so a table - /// that stated anything else would move a television's account out of DB8. + /// The webOS table states the storage helper as the canonical home of the session, the install's + /// preferences and the consent record: on a television that is DB8, and a table that stated + /// `Files` would say the app's own files are. #[test] fn the_webos_table_states_the_storage_helper_as_the_authority() { assert_eq!(SERVICES.storage.authority, Authority::Helper); assert_eq!(SERVICES.secure.mode, plx_os::tv::secure::StoreMode::Durable); } - /// `run_application` installs the services before anything else runs. The authority is read by - /// whatever persists first, and an uninstalled television reads `Files` and would write a - /// plaintext session file, so the install has to come before `exit::entry` runs `enter_application`. - /// Reads the source, like `app::boot`'s `seam_order_tests`, because no host test can run the entry. + /// Every `.rs` file under the application crate's `src`, as text. + fn crate_sources() -> Vec { + fn walk(dir: &std::path::Path, out: &mut Vec) { + for entry in std::fs::read_dir(dir).expect("read a source directory") { + let path = entry.expect("a directory entry").path(); + if path.is_dir() { + walk(&path, out); + } else if path.extension().is_some_and(|ext| ext == "rs") { + out.push(std::fs::read_to_string(&path).expect("read a source file")); + } + } + } + let mut out = Vec::new(); + walk(&std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src"), &mut out); + out + } + + /// `run_application` installs the services as its first statement, before anything can read + /// them: a process that has installed none reads the host-test answers, which for the storage + /// group is `Files`, so a television that persisted ahead of its install would be told it has no + /// helper. One production install, and the only caller of `tv::install` is the `Platform` method + /// it goes through. Reads the source, like `app::boot`'s `seam_order_tests`, because no host test + /// can run the entry. #[test] - fn the_services_are_installed_before_the_application_enters() { - let source = include_str!("app/mod.rs"); - let body = source + fn the_services_are_installed_first_and_only_there() { + let body = include_str!("app/mod.rs") .split_once("fn run_application(") .expect("run_application") .1 - .split_once("\n}\n") - .expect("end of run_application") - .0; - let install = body.find("platform.install_services();").expect("run_application installs the services"); - let enter = body.find("exit::entry(").expect("run_application enters through exit::entry"); - assert!(install < enter, "install_services must run before exit::entry"); + .split_once('{') + .expect("run_application's body") + .1; + let first = body + .lines() + .map(str::trim) + .find(|line| !line.is_empty() && !line.starts_with("//")) + .expect("a first statement"); + let first = first.split_once("//").map_or(first, |(code, _)| code).trim(); + assert_eq!( + first, + concat!("platform.install_", "services();"), + "the install must be run_application's first statement" + ); + let sources = crate_sources(); + let count = |needle: &str| sources.iter().map(|text| text.matches(needle).count()).sum::(); assert_eq!( - source.matches("install_services()").count(), + count(concat!(".install_", "services()")), 1, "one production install; a second would be refused by tv and could hide a missing first" ); + assert_eq!( + count(concat!("tv::", "install(")), + 1, + "`tv::install` is called by `Platform::install_services` and nowhere else" + ); } }