feat(control-plane)!: /ws/events says when it is live, over an ordered in-process event bus

.github/workflows/test.yml

@@ -79,7 +79,14 @@ jobs:
       # and cannot live in the proc-macro crate's own lib tests.
       # streamlib-engine's lib tests (host-body tier-1 + engine twin) are a
       # tracked follow-up, pending a fix to a parallel-run test flake.
+      # streamlib-api-server carries the control plane's route-surface, auth-gate
+      # and WebSocket frame locks, and ran nowhere in CI before.
+      # core::pubsub is named explicitly for the same reason python-wheel.yml
+      # names core::signals: the engine lib tests are excluded wholesale, and
+      # without this the subscription-live locks run nowhere.
       - name: Run unit tests
         run: |
           cargo test --locked -p streamlib -p streamlib-macros --lib
           cargo test --locked -p streamlib-engine --test attribute_macro_test
+          cargo test --locked -p streamlib-api-server --lib
+          cargo test --locked -p streamlib-engine --lib -- core::pubsub

docs/decisions/one-monotonic-clock.md

@@ -12,13 +12,18 @@ language, and before writing code that assumes a timestamp starts near zero.
 
 One concept — the machine's monotonic clock — in every language the project speaks, on
 the data plane. Scoped by the owner (2026-08-03) to what a processor stamps, reads, or
-compares: frames, bags, audio ticks, `ctx.time`. Wall clock survives on exactly four
-observability surfaces — log record `host_ts` and `source_ts`, log file naming, and the
-control-plane pubsub event timestamp — because correlating with the outside world and
+compares: frames, bags, audio ticks, `ctx.time`. Wall clock survives on exactly three
+observability surfaces — log record `host_ts` and `source_ts`, and log file naming —
+because correlating with the outside world and
 with other hosts' logs is a job monotonic time cannot do. Everything else is monotonic;
 a wall-clock value never enters the data plane and is never compared against a media
-timestamp. Adding a fifth wall-clock surface is a plan change, not a judgement call, and
+timestamp. Adding a further wall-clock surface is a plan change, not a judgement call, and
 `cargo xtask check-clock-usage` enforces the list mechanically.
+
+> ~~A fourth surface, the control-plane pubsub event timestamp, also keeps wall clock.~~
+> — Superseded 2026-08-13 by #1783. The control-plane event bus became an in-process
+> registry, so its events no longer cross a wire and carry no timestamp to stamp. The
+> surface ceased to exist rather than being retracted.
 Timestamps are raw `clock_gettime(CLOCK_MONOTONIC)` on Linux and `mach_absolute_time`
 on Apple: the same epoch V4L2 and ALSA stamp their buffers with, and the same value any
 other process on the host would read. No process-relative epoch, and exactly one

docs/learnings/README.md

@@ -67,8 +67,11 @@ Avoid the two failure modes:
   Validate camera→display end-to-end via virtual camera + PNG sampling
 - [@docs/learnings/vulkanalia-empty-slice-cast.md](vulkanalia-empty-slice-cast.md) —
   Cryptic `Cast` trait error when passing `&[]` to vulkanalia Vulkan methods
-- [@docs/learnings/pubsub-lazy-init-silent-noop.md](pubsub-lazy-init-silent-noop.md) —
-  Test hangs indefinitely because PUBSUB silently no-ops without `init()`
+- ~~`pubsub-lazy-init-silent-noop.md`~~ — Removed 2026-08-13 by #1783. It taught that
+  `PUBSUB` silently no-ops until `init()` and prescribed a 150 ms sleep before publishing
+  in tests; the control-plane bus became an in-process registry with no `init`, no
+  buffering and no subscriber thread, so every instruction in it was wrong and the failure
+  it described cannot recur.
 - [@docs/learnings/cdylib-make-borrow-cached-fields.md](cdylib-make-borrow-cached-fields.md) —
   Plugin pipeline runs end-to-end clean but produces zero/black output
   when host-side `make_*_borrow` helpers leave the PluginAbiObject's cached

docs/plan/ARCHITECTURE.md

@@ -234,11 +234,15 @@ Legend: **DECIDED** — build exactly this. **OPEN** — do not build; needs an
   (`CLOCK_MONOTONIC` on Linux, `mach_absolute_time` on Apple), the same epoch the V4L2
   and ALSA driver stamps carry, comparable across every node on a host. No
   process-relative epoch anywhere, and each language exports exactly one name for it.
-  Wall clock is permitted on exactly four observability surfaces and nowhere else: log
-  record `host_ts` and `source_ts`, log file naming, and the control-plane pubsub event
-  timestamp — their job is correlating with the outside world, which monotonic time
-  cannot do. A wall-clock value never enters the data plane and is never compared against
-  a media timestamp; a fifth surface is a plan change, not a judgement call.
+  Wall clock is permitted on exactly three observability surfaces and nowhere else: log
+  record `host_ts` and `source_ts`, and log file naming — their job is correlating with
+  the outside world, which monotonic time cannot do. A wall-clock value never enters the
+  data plane and is never compared against a media timestamp; a further surface is a plan
+  change, not a judgement call.
+  ~~The control-plane pubsub event timestamp is a fourth permitted surface.~~ — Superseded
+  2026-08-13 by #1783: the control-plane event bus became an in-process registry, so its
+  events no longer cross a wire and carry no timestamp to stamp. The surface ceased to
+  exist rather than being retracted; the rule it was an instance of is unchanged.
   [one-monotonic-clock]
 - **OPEN** — Audio backend: PipeWire-native on Linux is the intent (the current
   CPAL → ALSA path is interim); do not build until a research memo settles it. A/V

docs/plan/changes/one-monotonic-clock.md

@@ -70,10 +70,14 @@ driver stamp. Rust reaches it through `MediaClock`; Python through `monotonic_no
    siblings).
 3. Log file naming — `started_at_millis` (`core/logging/init.rs:185`,
    `core/logging/paths.rs:22`) and the CLI's rendering of both (`commands/logs.rs:222`).
-4. Control-plane pubsub event `timestamp_ns` (`core/pubsub/bus.rs:263-268`).
+4. ~~Control-plane pubsub event `timestamp_ns` (`core/pubsub/bus.rs:263-268`).~~ —
+   Superseded 2026-08-13 by #1783: the control-plane event bus became an in-process
+   registry, so its events no longer cross a wire and carry no timestamp to stamp. The
+   surface ceased to exist rather than being retracted; `check-clock-usage` now permits
+   three.
 
 Their job is correlating StreamLib with the outside world and with other hosts' logs — a
-job monotonic time cannot do. Adding a fifth surface is a plan change, not a judgement
+job monotonic time cannot do. Adding a further surface is a plan change, not a judgement
 call.
 
 ### The rule that keeps the two from mixing

runtime/streamlib-api-server/Cargo.toml

@@ -62,3 +62,8 @@ streamlib = { path = "../../sdk/streamlib-sdk", version = "0.17.0", features = [
 tempfile = "3"
 tower = {version = "0.5", features = ["util"]}
 serial_test = "3.2"
+# Real WebSocket client for the /ws/events frame-ordering test: `tower::oneshot`
+# drives a router but never completes an upgrade, so it cannot observe frames.
+# Pinned to the generation axum itself speaks, so the test client and the server
+# under test share one tungstenite rather than forking a second into the lock.
+tokio-tungstenite = "0.29"

runtime/streamlib-api-server/src/control_plane_stub_support.rs

@@ -87,3 +87,31 @@ macro_rules! graph_mutation_ops_are_unreachable {
 }
 
 pub(crate) use graph_mutation_ops_are_unreachable;
+
+/// Implement the observation half of [`RuntimeOperations`] — the ops every stub
+/// answers the same way — with an empty graph and an unreachable shutdown
+/// naming `$who`.
+///
+/// Paired with [`graph_mutation_ops_are_unreachable`]: between them a new
+/// `RuntimeOperations` method is one edit here rather than several
+/// near-identical stubs drifting apart across the crate's test modules.
+macro_rules! observation_ops_answer_an_empty_graph {
+    ($who:literal) => {
+        fn to_json_async(
+            &self,
+        ) -> ::streamlib::sdk::runtime::BoxFuture<
+            '_,
+            ::streamlib::sdk::error::Result<::serde_json::Value>,
+        > {
+            Box::pin(async { Ok(::serde_json::json!({})) })
+        }
+        fn to_json(&self) -> ::streamlib::sdk::error::Result<::serde_json::Value> {
+            Ok(::serde_json::json!({}))
+        }
+        fn request_runtime_shutdown(&self, _reason: &str) -> ::streamlib::sdk::error::Result<()> {
+            unreachable!(concat!($who, " never shuts the runtime down"))
+        }
+    };
+}
+
+pub(crate) use observation_ops_answer_an_empty_graph;