@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-module-macros/src/lib.rs

@@ -0,0 +1,225 @@
+//! Proc-macros for KROMA modules. [`embedded_module!`] finds a module's
+//! `module.json` and `icon.<ext>` by convention - the module root is the parent
+//! of the server crate - and expands to the right `EmbeddedModule` constructor.
+//! [`embedded_locales!`] finds its `locales/<code>.json` the same way.
+
+use proc_macro::TokenStream;
+use std::path::{Path, PathBuf};
+
+/// Builds the `MODULE` const for a module server crate. Takes no arguments.
+#[proc_macro]
+pub fn embedded_module(_input: TokenStream) -> TokenStream {
+    // The proc-macro runs inside the caller's rustc, so CARGO_MANIFEST_DIR is the
+    // CALLER's crate dir: `<module>/server`, whose parent is the module root.
+    expansion(std::env::var("CARGO_MANIFEST_DIR").ok())
+        .parse()
+        .expect("embedded_module!(): generated a valid const expression")
+}
+
+fn expansion(manifest_dir: Option<String>) -> String {
+    let Some(manifest_dir) = manifest_dir else {
+        return compile_error("embedded_module!(): CARGO_MANIFEST_DIR is not set");
+    };
+    let Some(module_root) = Path::new(&manifest_dir).parent().map(Path::to_path_buf) else {
+        return compile_error("embedded_module!(): the server crate has no parent dir");
+    };
+
+    let manifest_json = module_root.join("module.json");
+    if !manifest_json.exists() {
+        return compile_error(&format!(
+            "embedded_module!(): no module.json at {}",
+            manifest_json.display()
+        ));
+    }
+    let json_path = manifest_json.to_string_lossy();
+
+    // `EmbeddedModule` is emitted unqualified so it resolves against whatever the
+    // caller has in scope; the parsed tokens carry call-site hygiene, so the macro
+    // never has to hardcode a crate path.
+    match find_icon(&module_root) {
+        Some((icon_path, mime)) => {
+            let icon_path = icon_path.to_string_lossy();
+            format!(
+                "EmbeddedModule::with_icon(include_str!({json:?}), include_bytes!({icon:?}), {mime:?})"
+            , json = json_path, icon = icon_path, mime = mime)
+        }
+        None => format!(
+            "EmbeddedModule::iconless(include_str!({json:?}))",
+            json = json_path
+        ),
+    }
+}
+
+/// Builds the catalog list for a module server crate: every
+/// `locales/<code>.json` beside its `module.json`, as `&[(code, json)]` ready
+/// for `kroma_module_sdk::i18n::engine`. Takes no arguments, and a module with
+/// no `locales/` gets an empty slice.
+#[proc_macro]
+pub fn embedded_locales(_input: TokenStream) -> TokenStream {
+    locales_expansion(std::env::var("CARGO_MANIFEST_DIR").ok())
+        .parse()
+        .expect("embedded_locales!(): generated a valid const expression")
+}
+
+fn locales_expansion(manifest_dir: Option<String>) -> String {
+    let Some(manifest_dir) = manifest_dir else {
+        return compile_error("embedded_locales!(): CARGO_MANIFEST_DIR is not set");
+    };
+    let Some(module_root) = Path::new(&manifest_dir).parent() else {
+        return compile_error("embedded_locales!(): the server crate has no parent dir");
+    };
+    let catalogs: Vec<String> = find_catalogs(&module_root.join("locales"))
+        .iter()
+        .map(|(code, path)| format!("({code:?}, include_str!({:?}))", path.to_string_lossy()))
+        .collect();
+    format!("&[{}]", catalogs.join(", "))
+}
+
+fn find_catalogs(dir: &Path) -> Vec<(String, PathBuf)> {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+    let mut catalogs: Vec<(String, PathBuf)> = entries
+        .flatten()
+        .map(|entry| entry.path())
+        .filter(|path| path.extension().is_some_and(|ext| ext == "json"))
+        .filter_map(|path| {
+            let code = path.file_stem()?.to_string_lossy().into_owned();
+            Some((code, path))
+        })
+        .collect();
+    catalogs.sort();
+    catalogs
+}
+
+fn find_icon(dir: &Path) -> Option<(PathBuf, &'static str)> {
+    const CANDIDATES: &[(&str, &str)] = &[
+        ("svg", "image/svg+xml"),
+        ("png", "image/png"),
+        ("webp", "image/webp"),
+        ("jpg", "image/jpeg"),
+        ("jpeg", "image/jpeg"),
+        ("gif", "image/gif"),
+        ("avif", "image/avif"),
+        ("ico", "image/x-icon"),
+    ];
+    for (ext, mime) in CANDIDATES {
+        let path = dir.join(format!("icon.{ext}"));
+        if path.exists() {
+            return Some((path, mime));
+        }
+    }
+    None
+}
+
+fn compile_error(message: &str) -> String {
+    format!("compile_error!({message:?})")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct Scratch(kroma_testing::TempDir);
+
+    impl Scratch {
+        fn new(tag: &str) -> Self {
+            let scratch = Self(kroma_testing::temp_dir(tag));
+            std::fs::create_dir_all(scratch.0.path().join("server")).expect("scratch dir");
+            scratch
+        }
+
+        fn write(&self, name: &str, bytes: &[u8]) {
+            std::fs::write(self.0.path().join(name), bytes).expect("write");
+        }
+
+        fn write_locale(&self, name: &str, bytes: &[u8]) {
+            let dir = self.0.path().join("locales");
+            std::fs::create_dir_all(&dir).expect("locales dir");
+            std::fs::write(dir.join(name), bytes).expect("write");
+        }
+
+        fn expand(&self) -> String {
+            expansion(Some(self.server_dir()))
+        }
+
+        fn expand_locales(&self) -> String {
+            locales_expansion(Some(self.server_dir()))
+        }
+
+        fn server_dir(&self) -> String {
+            self.0.path().join("server").to_string_lossy().to_string()
+        }
+    }
+
+    #[test]
+    fn a_module_root_with_no_icon_file_is_not_an_error() {
+        assert!(find_icon(Path::new(env!("CARGO_MANIFEST_DIR"))).is_none());
+    }
+
+    #[test]
+    fn a_build_that_names_no_crate_directory_fails_the_compile_by_name() {
+        let out = expansion(None);
+        assert!(out.starts_with("compile_error!"), "{out}");
+        assert!(out.contains("CARGO_MANIFEST_DIR"), "{out}");
+    }
+
+    #[test]
+    fn a_crate_directory_with_nothing_above_it_cannot_hold_a_module() {
+        let out = expansion(Some(String::new()));
+        assert!(out.contains("no parent dir"), "{out}");
+    }
+
+    #[test]
+    fn a_server_crate_with_no_module_beside_it_says_where_it_looked() {
+        let scratch = Scratch::new("no-manifest");
+        let out = scratch.expand();
+        assert!(out.starts_with("compile_error!"), "{out}");
+        assert!(out.contains("module.json"), "{out}");
+    }
+
+    #[test]
+    fn a_module_without_an_icon_still_embeds_its_manifest() {
+        let scratch = Scratch::new("iconless");
+        scratch.write("module.json", br#"{"id":"com.example.demo"}"#);
+
+        let out = scratch.expand();
+        assert!(out.starts_with("EmbeddedModule::iconless("), "{out}");
+        assert!(out.contains("module.json"), "{out}");
+    }
+
+    #[test]
+    fn every_catalogue_beside_the_manifest_is_embedded_under_its_locale_code() {
+        let scratch = Scratch::new("locales");
+        scratch.write_locale("fr.json", br#"{"a":"un"}"#);
+        scratch.write_locale("en.json", br#"{"a":"one"}"#);
+        scratch.write_locale("notes.md", b"not a catalogue");
+
+        let out = scratch.expand_locales();
+        assert!(out.starts_with(r#"&[("en", include_str!("#), "{out}");
+        assert!(out.contains(r#"("fr", include_str!("#), "{out}");
+        assert!(!out.contains("notes"), "{out}");
+    }
+
+    #[test]
+    fn a_module_that_ships_no_catalogue_gets_an_empty_list_rather_than_an_error() {
+        let scratch = Scratch::new("no-locales");
+
+        assert_eq!(scratch.expand_locales(), "&[]");
+        assert!(locales_expansion(None).starts_with("compile_error!"));
+        assert!(locales_expansion(Some(String::new())).contains("no parent dir"));
+    }
+
+    #[test]
+    fn the_first_icon_extension_that_exists_is_the_one_embedded() {
+        let scratch = Scratch::new("icon");
+        scratch.write("module.json", br#"{"id":"com.example.demo"}"#);
+        scratch.write("icon.png", b"\x89PNG");
+        scratch.write("icon.svg", b"<svg/>");
+
+        let out = scratch.expand();
+        assert!(out.starts_with("EmbeddedModule::with_icon("), "{out}");
+        assert!(out.contains("icon.svg"), "svg outranks png: {out}");
+        assert!(out.contains("\"image/svg+xml\""), "{out}");
+    }
+}

package/rust/kroma-module-manifest/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "kroma-module-manifest"
+version = "0.1.39-canary.3579809"
+edition = "2021"
+rust-version = "1.88"
+description = "Low-level module manifest/registry/embedded types (below kroma-engine). Modules use the kroma-module-sdk facade; this is the shared manifest layer engine/kernel/wasm build on."
+license = "AGPL-3.0-or-later"
+
+[dependencies]
+# The embedded_module!() proc-macro, re-exported for the below-facade modules.
+kroma-module-macros = { path = "../kroma-module-macros" }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+# Semver range checks for versioned module dependencies (dependsOn version reqs).
+semver = "1"

package/rust/kroma-module-manifest/src/compat.rs

@@ -0,0 +1,203 @@
+//! Module <-> server compatibility checks, shared by the supervisor (install /
+//! spawn gate) and the store endpoints (catalog "compatible" flag).
+//!
+//! The RANGE helpers are permissive, mirroring the dependency-range policy in
+//! [`crate::Registry`]: an unparseable declaration or version is treated as
+//! "no constraint" rather than a mismatch, so a typo'd range degrades to
+//! installable instead of bricking the module everywhere. [`engines_satisfied`]
+//! is the exception, and deliberately: a requirement this build cannot even
+//! name is refused rather than ignored.
+
+use std::collections::BTreeMap;
+
+/// The engines this build knows how to check. A module may only require what a
+/// server can verify: ignoring an unknown requirement is how a module gets
+/// installed onto a host that cannot run it, and then fails somewhere else.
+pub const KNOWN_ENGINES: &[&str] = &["server"];
+
+/// Why a module's `engines` map refuses this build.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EngineRefusal {
+    /// The module requires an engine this build cannot check.
+    Unknown { engine: String },
+    /// The module requires `engine` within `range`, and this build, at
+    /// `server_version`, is not.
+    Unsatisfied {
+        engine: String,
+        range: String,
+        server_version: String,
+    },
+}
+
+impl std::fmt::Display for EngineRefusal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Unknown { engine } => write!(
+                f,
+                "requires an engine this server cannot check: {engine:?} (known: {})",
+                KNOWN_ENGINES.join(", "),
+            ),
+            Self::Unsatisfied {
+                engine,
+                range,
+                server_version,
+            } => write!(
+                f,
+                "requires {engine} {range} (this server is {server_version})"
+            ),
+        }
+    }
+}
+
+/// A module's `engines` map against what this build provides.
+///
+/// An empty map is no constraint; a range that will not parse is (like every
+/// other range here) treated as no constraint rather than a refusal.
+pub fn engines_satisfied(
+    engines: &BTreeMap<String, String>,
+    server_version: &str,
+) -> Result<(), EngineRefusal> {
+    for (engine, range) in engines {
+        if !KNOWN_ENGINES.contains(&engine.as_str()) {
+            return Err(EngineRefusal::Unknown {
+                engine: engine.clone(),
+            });
+        }
+        if !version_satisfies(Some(range), server_version) {
+            return Err(EngineRefusal::Unsatisfied {
+                engine: engine.clone(),
+                range: range.clone(),
+                server_version: server_version.to_owned(),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// Whether `version` satisfies a declaration that accepts a bare version
+/// (`"0.2.0"`, meaning "at least 0.2.0") or a full dtolnay semver range
+/// (`">=0.2, <0.4"`). `None`, blank and `"*"` all mean "anything".
+pub fn version_satisfies(decl: Option<&str>, version: &str) -> bool {
+    let Some(decl) = decl.map(str::trim).filter(|s| !s.is_empty() && *s != "*") else {
+        return true;
+    };
+    let Ok(server) = semver::Version::parse(version) else {
+        return true;
+    };
+    if let Ok(min) = semver::Version::parse(decl) {
+        return server >= min;
+    }
+    if let Ok(req) = semver::VersionReq::parse(decl) {
+        return req.matches(&server);
+    }
+    true
+}
+
+/// Whether `version` satisfies a dependency `range` (dtolnay semver syntax).
+/// Blank / `"*"` ranges match anything; unparseable inputs never block.
+pub fn range_matches(range: &str, version: &str) -> bool {
+    let range = range.trim();
+    if range.is_empty() || range == "*" {
+        return true;
+    }
+    match (
+        semver::VersionReq::parse(range),
+        semver::Version::parse(version),
+    ) {
+        (Ok(req), Ok(v)) => req.matches(&v),
+        _ => true,
+    }
+}
+
+/// Whether `candidate` is a strictly newer version than `current` (the store's
+/// "update available" test). Falls back to plain inequality when either side
+/// is not semver, so a registry with odd versions still surfaces changes.
+pub fn is_newer(candidate: &str, current: &str) -> bool {
+    match (
+        semver::Version::parse(candidate.trim()),
+        semver::Version::parse(current.trim()),
+    ) {
+        (Ok(c), Ok(i)) => c > i,
+        _ => candidate.trim() != current.trim(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn engines(pairs: &[(&str, &str)]) -> BTreeMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn an_engine_range_is_checked_against_this_server() {
+        assert!(engines_satisfied(&engines(&[("server", ">=0.1.4")]), "0.2.0").is_ok());
+        assert!(engines_satisfied(&engines(&[]), "0.1.0").is_ok());
+
+        let err = engines_satisfied(&engines(&[("server", ">=0.9")]), "0.2.0").unwrap_err();
+        assert_eq!(
+            err,
+            EngineRefusal::Unsatisfied {
+                engine: "server".into(),
+                range: ">=0.9".into(),
+                server_version: "0.2.0".into(),
+            }
+        );
+        assert_eq!(
+            err.to_string(),
+            "requires server >=0.9 (this server is 0.2.0)"
+        );
+    }
+
+    #[test]
+    fn an_engine_this_build_cannot_check_is_refused_rather_than_ignored() {
+        let err = engines_satisfied(&engines(&[("ffmpeg", ">=6")]), "0.2.0")
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("cannot check"), "{err}");
+        assert!(err.contains("ffmpeg"), "{err}");
+        assert!(err.contains("known: server"), "{err}");
+    }
+
+    #[test]
+    fn is_newer_compares_semver_then_falls_back() {
+        assert!(is_newer("0.2.0", "0.1.9"));
+        assert!(!is_newer("0.1.9", "0.2.0"));
+        assert!(!is_newer("0.2.0", "0.2.0"));
+        assert!(is_newer("nightly-2", "nightly-1"));
+    }
+
+    #[test]
+    fn bare_min_server_means_at_least() {
+        assert!(version_satisfies(Some("0.1.4"), "0.1.4"));
+        assert!(version_satisfies(Some("0.1.4"), "0.2.0"));
+        assert!(!version_satisfies(Some("0.2.0"), "0.1.4"));
+    }
+
+    #[test]
+    fn ranges_and_wildcards_work() {
+        assert!(version_satisfies(Some(">=0.1, <0.3"), "0.2.9"));
+        assert!(!version_satisfies(Some(">=0.3"), "0.2.9"));
+        assert!(version_satisfies(Some("*"), "0.0.1"));
+        assert!(version_satisfies(Some("  "), "0.0.1"));
+        assert!(version_satisfies(None, "0.0.1"));
+    }
+
+    #[test]
+    fn unparseable_declarations_never_block() {
+        assert!(version_satisfies(Some("not-a-version"), "0.1.4"));
+        assert!(version_satisfies(Some("1.0.0"), "not-a-version"));
+        assert!(range_matches("garbage", "0.1.0"));
+    }
+
+    #[test]
+    fn dependency_ranges() {
+        assert!(range_matches("^0.1.0", "0.1.9"));
+        assert!(!range_matches("^0.1.0", "0.2.0"));
+        assert!(range_matches("*", "9.9.9"));
+    }
+}

package/rust/kroma-module-manifest/src/embedded.rs

@@ -0,0 +1,160 @@
+//! A ready-made [`Module`] backed by a module's embedded `module.json` + icon.
+//!
+//! `include_str!`/`include_bytes!` stay at the module crate so their paths
+//! resolve there — a cross-crate `macro_rules!` would resolve them against
+//! this crate instead.
+
+use crate::{Module, ModuleIcon, ModuleManifest};
+
+#[derive(Clone, Copy)]
+struct EmbeddedIcon {
+    content_type: &'static str,
+    bytes: &'static [u8],
+}
+
+/// A module whose manifest and icon are embedded at compile time.
+#[derive(Clone, Copy)]
+pub struct EmbeddedModule {
+    manifest_json: &'static str,
+    icon: Option<EmbeddedIcon>,
+}
+
+impl EmbeddedModule {
+    /// A module with an embedded SVG icon (the common case).
+    pub const fn new(manifest_json: &'static str, icon_svg: &'static [u8]) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type: "image/svg+xml",
+                bytes: icon_svg,
+            }),
+        }
+    }
+
+    /// A module with an embedded PNG icon.
+    pub const fn with_png(manifest_json: &'static str, icon_png: &'static [u8]) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type: "image/png",
+                bytes: icon_png,
+            }),
+        }
+    }
+
+    /// A module with an embedded icon of an explicit content type. Used by the
+    /// `embedded_module!()` macro, which discovers the icon file at compile time
+    /// and passes the MIME derived from its extension.
+    pub const fn with_icon(
+        manifest_json: &'static str,
+        icon_bytes: &'static [u8],
+        content_type: &'static str,
+    ) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type,
+                bytes: icon_bytes,
+            }),
+        }
+    }
+
+    /// A module with no packaged icon.
+    pub const fn iconless(manifest_json: &'static str) -> Self {
+        Self {
+            manifest_json,
+            icon: None,
+        }
+    }
+}
+
+impl Module for EmbeddedModule {
+    fn manifest(&self) -> ModuleManifest {
+        serde_json::from_str(self.manifest_json).expect("valid embedded module.json")
+    }
+
+    // Deliberately no `register` override: `ModuleRegistration::contribute`
+    // records only `(point, id)`, so re-declaring would drop the `label` /
+    // `fields` / `flow` the manifest declared.
+
+    fn icon(&self) -> Option<ModuleIcon> {
+        self.icon.map(|i| ModuleIcon {
+            content_type: i.content_type,
+            bytes: i.bytes,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Registry;
+
+    #[test]
+    fn embedded_contributions_keep_ui_metadata() {
+        const MANIFEST: &str = r#"{
+            "id": "tv.kroma.engine.example",
+            "name": "Example engine",
+            "version": "0.1.0",
+            "contributes": [{
+                "point": "tv.kroma.torrents/download-client",
+                "id": "example",
+                "label": "Example",
+                "fields": [
+                    { "key": "url", "label": "field.url", "type": "string", "required": true },
+                    { "key": "password", "label": "field.password", "type": "string", "secret": true }
+                ]
+            }]
+        }"#;
+        let mut reg = Registry::new();
+        reg.register(Box::new(EmbeddedModule::iconless(MANIFEST)));
+        let m = reg
+            .manifests()
+            .into_iter()
+            .find(|m| m.id == "tv.kroma.engine.example")
+            .unwrap();
+        let contribution = &m.contributes[0];
+        assert_eq!(contribution.point, "tv.kroma.torrents/download-client");
+        assert_eq!(contribution.label.as_deref(), Some("Example"));
+        assert_eq!(contribution.fields.len(), 2);
+        assert!(
+            contribution.fields[1].secret,
+            "the secret flag must survive registration"
+        );
+    }
+
+    const BARE: &str = r#"{ "id": "tv.kroma.example", "name": "Example", "version": "0.1.0" }"#;
+
+    #[test]
+    fn each_constructor_labels_the_icon_with_the_content_type_the_route_will_serve() {
+        let svg = EmbeddedModule::new(BARE, b"<svg/>")
+            .icon()
+            .expect("an svg icon");
+        assert_eq!(svg.content_type, "image/svg+xml");
+        assert_eq!(svg.bytes, b"<svg/>");
+
+        let png = EmbeddedModule::with_png(BARE, b"\x89PNG")
+            .icon()
+            .expect("a png icon");
+        assert_eq!(png.content_type, "image/png");
+        assert_eq!(png.bytes, b"\x89PNG");
+
+        let webp = EmbeddedModule::with_icon(BARE, b"RIFF", "image/webp")
+            .icon()
+            .expect("a webp icon");
+        assert_eq!(webp.content_type, "image/webp");
+
+        assert!(EmbeddedModule::iconless(BARE).icon().is_none());
+    }
+
+    #[test]
+    fn the_registry_serves_an_embedded_modules_icon_by_id() {
+        let mut reg = Registry::new();
+        reg.register(Box::new(EmbeddedModule::new(BARE, b"<svg/>")));
+        assert_eq!(
+            reg.icon_of("tv.kroma.example").expect("icon").content_type,
+            "image/svg+xml"
+        );
+        assert!(reg.icon_of("tv.kroma.absent").is_none());
+    }
+}

package/rust/kroma-module-manifest/src/event.rs

@@ -0,0 +1,74 @@
+//! The open, module-authored event envelope.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// An event emitted by a module.
+///
+/// The server's broadcast bus carries a *closed* `ServerEvent` enum today, so a
+/// module cannot introduce its own event without editing that enum. This
+/// envelope is the open alternative: a module publishes `{ module, tag,
+/// payload }` and any subscriber filters by `module` / `tag`. The existing
+/// typed events keep flowing unchanged; module events ride alongside them on
+/// the same broadcast channel (serialized to JSON like the rest).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ModuleEvent {
+    pub module: String,
+    pub tag: String,
+    #[serde(default)]
+    pub payload: Value,
+}
+
+impl ModuleEvent {
+    pub fn new(module: impl Into<String>, tag: impl Into<String>, payload: Value) -> Self {
+        Self {
+            module: module.into(),
+            tag: tag.into(),
+            payload,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn new_sets_the_three_fields() {
+        let ev = ModuleEvent::new(
+            "tv.kroma.downloads",
+            "download.progress",
+            json!({ "pct": 12 }),
+        );
+        assert_eq!(ev.module, "tv.kroma.downloads");
+        assert_eq!(ev.tag, "download.progress");
+        assert_eq!(ev.payload["pct"], 12);
+    }
+
+    #[test]
+    fn serializes_to_the_wire_envelope() {
+        let ev = ModuleEvent::new("m", "t", json!({ "a": 1 }));
+        let v = serde_json::to_value(&ev).unwrap();
+        assert_eq!(
+            v,
+            json!({ "module": "m", "tag": "t", "payload": { "a": 1 } })
+        );
+    }
+
+    #[test]
+    fn payload_defaults_to_null_when_absent() {
+        // The `#[serde(default)]` on `payload` lets a producer omit it entirely.
+        let ev: ModuleEvent = serde_json::from_value(json!({ "module": "m", "tag": "t" })).unwrap();
+        assert_eq!(ev.module, "m");
+        assert_eq!(ev.tag, "t");
+        assert!(ev.payload.is_null());
+    }
+
+    #[test]
+    fn round_trips_through_json() {
+        let ev = ModuleEvent::new("m", "t", json!([1, 2, 3]));
+        let back: ModuleEvent = serde_json::from_str(&serde_json::to_string(&ev).unwrap()).unwrap();
+        assert_eq!(back, ev);
+    }
+}