fix(manifest): a key the schema does not define is now a load error

ROOT CAUSE of the busbar-150 mislabelling, not a workaround for it.

Runtime::Docker has no 'image' field - the image lives on 'launch' - but serde
ignored unknown keys, so writing runtime.image parsed cleanly, was read by
nothing, and changed nothing. A box ran getbusbar/busbar:1.4.1 for 25 minutes
under the gateway key busbar-150, and would have published 1.4.1's numbers in a
row labelled 1.5.0: two columns of the same binary presented as a version
comparison, with deltas in the noise that read as 'no regression'.

Nothing in the harness objected, because from serde's point of view nothing was
wrong. deny_unknown_fields on Manifest and Runtime turns that class of mistake
into a parse error naming the field, at load, where the fix costs seconds.

It proved itself immediately: applying it caught a SECOND phantom key I had
added in the same edit - a top-level 'version' that no other gateway declares
and the Rust schema never had. Both are now gone from busbar-150, whose
launch.image is the only image field and reads 1.5.0.

The cost of the silent version was a run. 609 engine tests, fmt and clippy
clean, and every shipped manifest still parses - asserted by a test, since a
guard that rejects the board is worth no more than one that rejects nothing.

Author: MattJackson

engine/src/manifest.rs

@@ -14,8 +14,18 @@ use serde::{Deserialize, Serialize};
 
 /// How the gateway runs, and therefore how its process tree is found. This is the single declaration
 /// every memory reader and the stop path derive from.
+/* AN UNKNOWN KEY IS A SILENT NO-OP, AND THAT COSTS A RUN.
+`Runtime::Docker` has no `image` field - the image lives on `launch` - but serde ignored unknown
+keys, so a `runtime.image` written into a manifest parsed cleanly, was read by nothing, and
+changed nothing. On 2026-08-02 that produced a box running getbusbar/busbar:1.4.1 for 25 minutes
+under the gateway key `busbar-150`, which would have published 1.4.1's numbers in a row labelled
+1.5.0 and shown two columns of the same binary as if they were a version comparison. Nothing in
+the harness objected, because from serde's point of view nothing was wrong.
+
+A manifest field nobody reads is either a typo or a stale key, and both should fail at load where
+the fix is cheap - not at publish, where the evidence is a box that no longer exists. */
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(tag = "kind", rename_all = "snake_case")]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum Runtime {
     /// A container. The root pid comes from the container runtime, and the tree walk starts there.
     Docker {
@@ -182,7 +192,10 @@ pub struct ConfigSetting {
     pub note: String,
 }
 
+// Same rule as `Runtime` above, for the same reason: a key the schema does not define is a defect,
+// and one that parses is a defect nobody sees.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
 pub struct Manifest {
     /// Directory name. The gateway's identity on the board.
     pub name: String,
@@ -2559,3 +2572,69 @@ mod unresolvable_header_tests {
         );
     }
 }
+
+#[cfg(test)]
+mod unknown_field_tests {
+    use super::*;
+
+    /* A MANIFEST KEY NOBODY READS MUST FAIL AT LOAD. Serde ignored unknown fields, so writing
+    `runtime.image` - a field `Runtime::Docker` does not have, because the image lives on `launch`
+    - parsed cleanly and changed nothing. The box ran getbusbar/busbar:1.4.1 for 25 minutes under
+    the gateway key `busbar-150`, and the only reason it was caught was a human asking to log in
+    and look at the container rather than trusting the config.
+
+    The cost of the silent version is a run; the cost of the loud version is a parse error naming
+    the field. */
+    #[test]
+    fn an_image_written_where_the_schema_has_none_is_refused() {
+        let json = r#"{
+            "name": "x", "display": "X", "lang": "Rust", "class": "Gateway",
+            "port": 8000, "model": "m", "auth": "t",
+            "runtime": { "kind": "docker", "container": "c", "image": "getbusbar/busbar:9.9.9" },
+            "egress": ["openai"]
+        }"#;
+        let err = serde_json::from_str::<Manifest>(json)
+            .unwrap_err()
+            .to_string();
+        assert!(
+            err.contains("image"),
+            "the error must name the field that was ignored, got: {err}"
+        );
+    }
+
+    /// And a stray top-level key is refused for the same reason - a typo'd or stale field is a
+    /// defect whichever level it sits at.
+    #[test]
+    fn a_stray_top_level_key_is_refused() {
+        let json = r#"{
+            "name": "x", "display": "X", "lang": "Rust", "class": "Gateway",
+            "port": 8000, "model": "m", "auth": "t",
+            "runtime": { "kind": "docker", "container": "c" },
+            "egress": ["openai"],
+            "verison": "1.5.0"
+        }"#;
+        let err = serde_json::from_str::<Manifest>(json)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("verison"), "got: {err}");
+    }
+
+    /// The real manifests must still parse - a guard that rejects the field is worthless if it also
+    /// rejects the board.
+    #[test]
+    fn every_shipped_manifest_still_parses_under_the_stricter_schema() {
+        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../gateways");
+        let mut n = 0;
+        for e in std::fs::read_dir(&dir).expect("gateways/") {
+            let p = e.expect("entry").path().join("definition.json");
+            if !p.exists() {
+                continue;
+            }
+            let text = std::fs::read_to_string(&p).expect("read");
+            serde_json::from_str::<Manifest>(&text)
+                .unwrap_or_else(|err| panic!("{} no longer parses: {err}", p.display()));
+            n += 1;
+        }
+        assert!(n >= 14, "expected the whole field, saw {n}");
+    }
+}

gateways/busbar-150/definition.json

@@ -63,8 +63,6 @@
   "repo": "https://github.com/GetBusbar/busbar",
   "runtime": {
     "container": "busbar-bench",
-    "image": "getbusbar/busbar:1.5.0",
     "kind": "docker"
-  },
-  "version": "1.5.0"
+  }
 }