Skip to content

The platform interface is published through one module, host, with an EventSink for input - #1500

Merged
GLinnik21 merged 11 commits into
mainfrom
platform/w7a-host-interface
Nov 21, 2026
Merged

GLinnik21 merged 11 commits into
mainfrom
platform/w7a-host-interface

Conversation

@GLinnik21

@GLinnik21 GLinnik21 commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Step W7a of the platform plan (discussion #1460). The application crate now publishes what a platform crate needs to build its static Platform and hand it over, and it publishes this through one module, plxnative_modules::host. Nothing else of the application is public to a television build. Neither the television nor the simulator behaves differently: the SDL event path is the same bytes through the same poll.

What the interface is

  • rust-modules/src/host.rs (new) re-exports what a platform builds or implements: Platform, Shell, Surface, EventSink, FrameProbe, MediaBoot, Composition, Exit and Release. It also re-exports the lower layers' vocabulary their signatures name: Services (plx_os::tv), MainThread, Edge, Action, RawKey, Lifecycle, PointerEdge, OpenAsk and Placement. With these, a platform crate names the application crate's types through host alone. Some types still come from their own crates, which a platform crate depends on directly:

    • the hook tables Services is built from (plx_os::tv: IdentityHooks, SecureHooks, SystemHooks, StorageHooks, LegacyWebosMedia, LocaleReply);
    • PlayerAdapter (plx_media), which MediaBoot::compose takes.

    host's one function is run(&'static Platform, &CStr, u16) -> Exit, the application's entry.

  • The owner's ruling (Decision 3 amended, 2026-11-21): the eight application-crate items are reachable only through host, never as general pub items:

    • Platform, Shell, Surface and FrameProbe;
    • MediaBoot, Composition, Exit and Release.

    Services is already a pub type of plx_os, and host re-exports it. HostEvent, the loop's own event type, stays private.

  • Input has a public face, EventSink (key, text, pointer, wheel, lifecycle). A platform reports input through Surface::deliver(&self, &mut dyn EventSink), and the application converts each call into its HostEvent in one place, HostQueue in app/events.rs.

    • deliver is required.
    • SDL's Window::deliver delivers nothing, because every SDL event, a synthetic one included, still comes through poll.
    • poll is now defaulted to none and #[doc(hidden)]. It retires when the SDL shells deliver through the sink, at W9 at the latest.
  • Shell (12 methods) and Surface are published as they are. W9 folds the per-window calls that still take a raw handle into Surface.

  • 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 window and GL state live only in the Surface that Shell::open returns on the loop thread.

  • RawKey moves to plx_ui::consts beside Action, so the key vocabulary sits in the layer that names keys.

  • Left for W7b: sdl_init and sdl_open, the SDL helpers the two real platforms need, ship with those platform crates.

How it is held

  • Two source pins in host.rs (surface_pin_tests) hold the ruling inside the crate:

    • The crate root's pub items are a known set: host, plus the simulator's six doors. Each door's cfg must be false in every build that has neither hostsim nor test. A multi-line attribute is joined and evaluated, so all(feature = "hostsim", not(..)) passes, and an any(..) naming another feature (devtriggers is on by default) fails. The test also fails if a known item disappears.
    • host.rs is the only pub use of the application: any other pub use whose tree has app as a path segment fails. That covers crate::, super::, self::, a bare app::, and a group such as crate::{host, app::Exit}. The one exception is lib.rs's hostsim-only synthetic_home_initial.

    Each plant failed or passed as intended, then was reverted:

    • pub use app::platform::Shell; and pub use self::app::platform::Shell; in lib.rs failed both pins;
    • pub mod app; failed the first;
    • a devtriggers any(..) on hud_cli failed the first;
    • pub use super::app::platform::Shell; and pub use crate::{host, app::Exit}; in platform_desktop.rs failed the second;
    • a multi-line feature = "hostsim" attribute and all(feature = "hostsim", not(feature = "devtriggers")) passed.

    The failure message's first remedy is to re-export the item from host.rs; W7b's sdl_init and sdl_open are the example. Only a new simulator door that is not an application item extends the known set, with the reason recorded in the Decision 3 amendment. The pins are textual: they do not see a pub item inside a macro expansion, a glob re-export, or an alias that drops the app segment.

  • rust-modules/tests/host_interface.rs (new) is an integration test. It is a crate of its own, so it can name only the application's pub items. It builds a static Platform from a fake Shell, a !Sync fake Surface and a fake FrameProbe. Four tests:

    • registration data: a Platform is constructible in a static;
    • EventSink from outside: it can be implemented outside the crate and receives events in order;
    • source scan: every plxnative_modules path in this file goes through ::host. That checks only the file's own spelling; the crate's surface is held by the pins above. The scan was shown to fail when a line naming app::platform::Shell was appended;
    • boot to refusal: the boot runs through the real application entry to the fake shell's refusal of the window. It asserts init before open, the OpenAsk (title, Placement::Desktop, high-dpi), the installed Services locale hook, and the returned Exit { code: 73, release: Retained }. Its logs land in a throwaway runtime root. The boot goes no further without a GL context.
  • In-crate tests:

    • HostQueue's conversion has 5 tests.
    • drain_sdl delivering through the sink into the loop has one.
    • So does the SDL surface still delivering nothing through the sink.
  • make test-host-interface is the incremental loop for the integration test, in target-hostsim beside make test-hostsim.

    • Like other cargo targets, it is in DISK_ENTRIES, SIDE_EFFECT_FREE and the HOST-ONLY goals, and it is refused under RELEASE=1.
    • make check runs the same test non-incrementally as a second cargo line in check-cargo-unit-hostsim.
    • The CI split, ARM-profile and host-threads pins count it (ci/test_ci_split.py, ci/test_arm_profile.py, ci/test_host_threads.py), and ci/module-layers.ini places host in [app].
    • No [[test]] entry and no manifest change, so no certificate is re-sealed.
  • Two W6 review minors are done here:

    • the fw-compat reviewer's prompt line;
    • plx_shell_sdl's every_source_file_is_scanned, which now keeps only *.rs files and directories.
  • Docs:

    • docs/platform-ports.md: §1, §2 and §8, the W7 entry, "As landed (W7a)", and the Decision 3 amendment with the Decision 4 pointer;
    • docs/module-layers.md and docs/agent-reference.md.
    • doc-claim-auditor ran twice: round 1 found 8 contradictions and round 2 found 1, all fixed.

Build bench

make build-bench, without the tests and arm rows, 3 runs each. Apple M4 (10 cores), rustc 1.100.0. Before is 7ceb6f76f (this PR's base), after is 8f25da9f5; the two later commits change only doc text and comments. Both trees were clean. Units: 193 → 193.

Scenario median before median after delta rebuilt
No-op host test build 6.99 s 8.55 s +1.6 s 0
Edit leaf plx_base cbuf.rs 50.11 s 50.39 s +1% 37
Edit leaf plx_machine landgate.rs 42.26 s 40.14 s −5% 27
Edit leaf plx_os devcaps.rs 39.90 s 40.38 s +1% 23
Edit leaf plx_gfx overdraw.rs 26.86 s 26.07 s −3% 9
Edit leaf plx_net stream_redirect.rs 41.04 s 42.25 s +3% 19
Edit leaf plx_ui dwell.rs 26.15 s 25.24 s −3% 7
Edit leaf plx_plex retry.rs 39.20 s 41.76 s +7% 15
Edit leaf plx_telemetry window.rs 37.32 s 34.84 s −7% 13
Edit leaf plx_data tape.rs 34.12 s 32.90 s −4% 9
Edit leaf plx_session scripted.rs 22.41 s 22.54 s +1% 5
Edit leaf plx_media units.rs 28.08 s 30.44 s +8% 7
Edit leaf plx_appkit skip_pill.rs 27.77 s 26.74 s −4% 5
Edit leaf plx_screens clock_readout.rs 25.61 s 24.30 s −5% 3
Edit leaf app coldstart.rs 16.54 s 16.24 s −2% 1
Edit hub plx_ui lib.rs 25.32 s 24.80 s −2% 7

The non-incremental rows move between −7% and +8%, and every range overlaps. The rebuilt counts are identical.

The two incremental rows were measured twice, because they disagreed:

incremental before after (lane's long-lived checkout) base, fresh worktree head, fresh worktree
Edit leaf plx_base cbuf.rs 259.2 s 357.4 s (407.5 s on a second run) 282.7 s (258.5..325.1) 245.2 s (208.0..276.0)
Edit hub plx_ui lib.rs 58.5 s 85.5 s (84.8 s) 62.9 s (45.9..71.7) 66.0 s (53.4..66.9)

In fresh worktrees on the same machine the head is not slower, and the unit and rebuilt counts are the same in every run. The slowdown shows only in the long-lived checkout that built the lane. Its cause was not determined, and the incremental cache size was not measured.

Gates (on the committed tree)

The full set ran at 8f25da9f5. At 06d95595b (one commit of doc and comment text) these were re-run: make check-python, make check-cargo-lint, the static gates and the certificate tests.

At b5d4098b8 (the surface pins and the reworded dependency claim) these were re-run:

  • the two pins: test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1499 filtered out each, and 2 passed under hostsim;
  • make test-host-interface, make check-cargo-lint, make check-nodef and make check-python;
  • the static gates (check-module-layers: 20 layers, 2027 modules, one more for the pin module) and the certificate tests.

At 9ce0310c5 (the pins' cfg evaluation, path-segment match and remedy wording) these were re-run:

  • make test-crate C=plxnative_modules T=surface_pin_tests: test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1498 filtered out;

  • make test-hostsim T=surface_pin_tests: 2 passed;

  • make test-host-interface, make check-cargo-lint and make check-python;

  • the static gates and the certificate tests.

  • Default unit pass, three tests that crash on this Mac skipped (below): 20 binaries ok. Among them:

    • the application crate: test result: ok. 1497 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out
    • plx_screens: test result: ok. 2315 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out
    • plx_media: test result: ok. 2165 passed; 0 failed; 104 ignored; 0 measured; 0 filtered out
  • Hostsim pass, the same skips: 12 binaries ok. Among them:

    • the application crate: test result: ok. 1774 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out
    • plx_media: test result: ok. 2485 passed; 0 failed; 104 ignored
  • The host interface test, both as check-cargo-unit-hostsim's second line and as make test-host-interface: test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out.

  • Green: make check-cargo-lint, make check-nodef, make sim-macos and make check-python.

  • Every simulator feature set CI builds was built: ci.yml's two cargo check lines and simulators.yml's macOS app link. The Makefile's screenshot and site-video feature sets were type-checked with cargo check, not built.

  • make check-replay: 6 fixtures, 12 replays, SAME=4 REFUSED_EXPECTED=8 unexpected=0.

  • Static gates:

    • ci/check-deps.sh: all gates green;
    • ci/check-module-layers.py: 20 layers, 2026 modules, 173 Cargo layer declarations, 0 migration entries left;
    • ci/check-ledger-ratchet.py: no count above 7ceb6f76f;
    • ci/check-statics.sh: all gates green.
  • Certificate tests: ci/test_readonly_dependencies.py and ci/test_readonly_generated.py pass (64 and 22 tests).

  • ARM, at 47df75e6e against the base's tvdev binary:

    • DT_NEEDED is 15 entries, identical;
    • the 387 undefined dynamic symbols are identical;
    • the size is +23,224 bytes (40,031,896 → 40,055,120).

    The later commits change doc comments, the test file and a Makefile comment only. There is no FFI, linkage or dynlib! change, so fw-compat-reviewer was not run.

Reproduced on base

  • Three tests crash with SIGSEGV in the macOS system libGL with no context, and were skipped:

    • player_owner_events_record_and_replay_through_the_actual_app_host (hostsim; known since Rename the bottom layer crate plx_platform to plx_os #1474);
    • an_unregistered_product_screen_uses_generic_navigation_and_actual_store_effects;
    • actual_visible_player_paint_reports_typed_watch_without_mutating_it.

    The first two were run directly at head and exit 139. The third is skipped on earlier lanes' records.

  • make test-hostsim at the default thread count fails a_play_landing_behind_a_preview_that_never_returns_gives_up and a_play_landing_waits_for_an_abandoning_preview. Base 7ceb6f76f fails the same two with the identical recipe (1765 passed; 2 failed; head is 1772 passed; 2 failed, base plus the 7 new tests). Both pass at --test-threads=6.

Not covered

  • The boot-to-refusal test has not run on Linux. CI's host-unit-hostsim job is its first Linux run.
  • make check was not run as one invocation. Its pieces ran separately, because of the skips above.
  • The boot test stops at the window. A windowless fake cannot reach the loop or GL. deliver into the loop is covered by the in-crate drain_sdl test instead.
  • No television leg: the SDL path is unchanged, and the ARM binary's linkage equals the base's.
  • No ARM_PROFILE=release size measurement.
  • A stale pin was left alone: the root rust-modules/src/lib.rs pin in ci/proofs/serde-json-immutable.json is not enforced.
  • Carried to W7b, which edits lib.rs and host.rs anyway: the third review's one minor. An attribute and its pub item written on one line (#[doc(hidden)] pub mod app;) are invisible to both surface pins. The fix is to read the text after the attribute's final ] as the item.

🤖 Generated with Claude Code

GLinnik21 and others added 11 commits November 21, 2026 01:46
… 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 <noreply@anthropic.com>
…te, 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 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… SDL delivery test polls both edges of a tap

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…face gate carries

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ed, Services is plx_os's, and the integration test exists

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…, 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 <noreply@anthropic.com>
…ing 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 <noreply@anthropic.com>
…her `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 <noreply@anthropic.com>
@GLinnik21
GLinnik21 merged commit 0c9a64d into main Nov 21, 2026
19 checks passed
@GLinnik21
GLinnik21 deleted the platform/w7a-host-interface branch November 21, 2026 03:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant