fix(serde): reject structs with missing required fields during deserialization

Previously, if a non-optional struct field was absent from the input,
it was silently default-constructed. This broke variant backtracking:
when deserializing variant<A, B>, if A's required fields were missing,
A would still "succeed" and B would never be tried.

Semantics aligned with Rust's serde:
- Default strict: missing non-optional field → error
- std::optional<T> fields are automatically allowed to be absent
  (like Rust's Option<T>)
- schema::default_value attribute (like Rust's #[serde(default)])
  allows a field to be absent, keeping its default-constructed value
- defaulted<T> convenience alias for annotation<T, schema::default_value>

Implementation:
- Add required_field_mask<T>() — compile-time bitmask of required
  field indices (non-excluded, non-optional, no default_value attr)
- Track seen_fields in deserialize_reflectable and reject if any
  required field is missing
- Strip cv from refl::field_type before specialization checks
- Add forwarding operator= to inherit_use_type annotation for
  move-only types (e.g. unique_ptr)

Also:
- Fix json_rpc_incoming::result to use defaulted<RawValue>
- Update test structs to use defaulted<T> on nullable fields
- Add 8 required field check tests (strict, optional, defaulted)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 16bit-ykiko

include/eventide/serde/serde/annotation.h

@@ -6,6 +6,7 @@
 #include <utility>
 
 #include "eventide/serde/serde/attrs/behavior.h"
+#include "eventide/serde/serde/attrs/schema.h"
 
 namespace eventide::serde {
 
@@ -69,6 +70,14 @@ struct annotation<T, Attrs...> : T {
     static_assert(detail::validate_attrs<std::tuple<Attrs...>>(), "Invalid attribute combination");
 
     using T::T;
+
+    template <typename U>
+        requires (!std::same_as<std::remove_cvref_t<U>, annotation> && std::assignable_from<T&, U>)
+    constexpr annotation& operator=(U&& raw) {
+        T::operator=(std::forward<U>(raw));
+        return *this;
+    }
+
     using annotated_type = T;
     using attrs = std::tuple<Attrs...>;
 };
@@ -119,4 +128,10 @@ constexpr auto operator==(const L& lhs, const R& rhs) -> bool {
     return lhs == annotated_value(rhs);
 }
 
+/// Convenience alias: annotation<T, schema::default_value>.
+/// Marks a field as allowed to be absent during deserialization,
+/// keeping its default-constructed value. Like Rust's #[serde(default)].
+template <typename T>
+using defaulted = annotation<T, schema::default_value>;
+
 }  // namespace eventide::serde

include/eventide/serde/serde/attrs/schema.h

@@ -113,6 +113,11 @@ struct skip {};
 
 struct flatten {};
 
+/// Allow a field to be absent during deserialization.
+/// When missing, the field keeps its default-constructed value.
+/// Equivalent to Rust's #[serde(default)].
+struct default_value {};
+
 template <fixed_string Name>
 struct rename {
     constexpr inline static std::string_view name = Name;

include/eventide/serde/serde/utils/reflectable.h

@@ -295,9 +295,11 @@ constexpr auto serialize_reflectable(S& s, const V& v) -> std::expected<typename
     return s_struct.end();
 }
 
-/// True if field I of struct T may be absent from JSON without error.
-/// A field is optional if it is excluded (skip/flatten) or its underlying
-/// value type is std::optional<T>.
+/// True if field I of struct T may be absent during deserialization.
+/// A field is optional if:
+///   - excluded (skip/flatten)
+///   - its underlying type is std::optional<T>  (like Rust's Option<T>)
+///   - annotated with schema::default_value      (like Rust's #[serde(default)])
 template <typename T, std::size_t I>
 consteval bool is_field_optional() {
     if constexpr(schema::is_field_excluded<T, I>()) {
@@ -307,6 +309,10 @@ consteval bool is_field_optional() {
         // so strip cv before checking specialization.
         using field_t = std::remove_cv_t<refl::field_type<T, I>>;
         if constexpr(serde::annotated_type<field_t>) {
+            using attrs_t = typename field_t::attrs;
+            if constexpr(tuple_has_v<attrs_t, schema::default_value>) {
+                return true;
+            }
             return is_specialization_of<std::optional, typename field_t::annotated_type>;
         } else {
             return is_specialization_of<std::optional, field_t>;
@@ -379,6 +385,7 @@ constexpr auto deserialize_reflectable(D& d, V& v) -> std::expected<void, E> {
     }
 
     // Verify all required (non-optional, non-excluded) fields were present.
+    // This enables correct variant backtracking and catches malformed input.
     constexpr std::uint64_t required = required_field_mask<value_t>();
     if((seen_fields & required) != required) {
         return std::unexpected(E::type_mismatch);

pixi.toml

@@ -98,14 +98,14 @@ fd -H -e yaml -e yml -E pnpm-lock.yaml -x prettier --write && \
 fd -H "^\\.clang-(format|tidy)$" -x prettier --write --parser yaml
 """
 format = { depends-on = [
-  "format-cpp",
-  "format-python",
-  "format-lua",
-  "format-web",
-  "format-markdown",
-  "format-json",
-  "format-toml",
-  "format-yaml"
+    "format-cpp",
+    "format-python",
+    "format-lua",
+    "format-web",
+    "format-markdown",
+    "format-json",
+    "format-toml",
+    "format-yaml"
 ] }
 
 [feature.format.target.win-64.tasks]
@@ -129,7 +129,7 @@ cmd = "xmake config --clean --yes --mode={{ build_type }}{% if pixi.is_osx %} --
 [tasks.ci-xmake-build]
 args = ["build_type"]
 depends-on = [
-  { task = "ci-xmake-configure", args = ["{{ build_type }}"] },
-  { task = "xmake-build" },
-  { task = "xmake-test" },
+    { task = "ci-xmake-configure", args = ["{{ build_type }}"] },
+    { task = "xmake-build" },
+    { task = "xmake-test" },
 ]

src/ipc/json_codec.cpp

@@ -54,7 +54,10 @@ struct json_rpc_incoming {
     std::optional<protocol::RequestID> id;
     std::optional<std::string> method;
     std::optional<serde::RawValue> params;
-    std::optional<serde::RawValue> result;
+    // Not optional<RawValue> because "result": null is a valid success
+    // response — optional would lose it as nullopt. defaulted<RawValue>
+    // keeps absent → empty(), null → "null" text.
+    serde::defaulted<serde::RawValue> result;
     std::optional<Error> error;
 };
 
@@ -82,14 +85,14 @@ IncomingMessage JsonCodec::parse_message(std::string_view payload) {
 
     // No method + has id → response
     if(envelope->id.has_value()) {
-        auto has_result = envelope->result.has_value() && !envelope->result->empty();
+        auto has_result = !envelope->result.empty();
         auto has_error = envelope->error.has_value();
 
         if(has_error && !has_result) {
             return IncomingErrorResponse{*envelope->id, std::move(*envelope->error)};
         }
         if(has_result && !has_error) {
-            return IncomingResponse{*envelope->id, std::move(envelope->result->data)};
+            return IncomingResponse{*envelope->id, std::move(envelope->result.data)};
         }
         return IncomingErrorResponse{*envelope->id,
                                      Error(protocol::ErrorCode::InvalidRequest,

tests/unit/serde/json/simdjson_tests.cpp

@@ -13,6 +13,7 @@
 #include "eventide/zest/zest.h"
 #include "eventide/serde/json/deserializer.h"
 #include "eventide/serde/json/serializer.h"
+#include "eventide/serde/serde/annotation.h"
 #include "eventide/serde/serde/serde.h"
 
 namespace eventide::serde {
@@ -379,6 +380,81 @@ TEST_CASE(misc_behavior) {
 
 };  // TEST_SUITE(serde_simdjson)
 
+// ═══════════════════════════════════════════════════════════════════════
+// Required field checks
+// ═══════════════════════════════════════════════════════════════════════
+
+struct StrictStruct {
+    int x{};
+    std::string name;
+};
+
+struct MixedStruct {
+    int required_field{};
+    std::optional<int> optional_field;
+    defaulted<std::string> defaulted_field;
+};
+
+struct AllOptional {
+    std::optional<int> a;
+    std::optional<std::string> b;
+};
+
+TEST_SUITE(serde_required_fields) {
+
+TEST_CASE(missing_required_field_fails) {
+    // "name" is required (non-optional), missing → error
+    auto result = from_json<StrictStruct>(R"({"x": 42})");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(all_required_fields_present_succeeds) {
+    auto result = from_json<StrictStruct>(R"({"x": 42, "name": "hello"})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->x, 42);
+    EXPECT_EQ(result->name, "hello");
+}
+
+TEST_CASE(empty_json_object_fails_if_required_fields) {
+    auto result = from_json<StrictStruct>(R"({})");
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(optional_field_can_be_absent) {
+    auto result = from_json<MixedStruct>(R"({"required_field": 7})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->required_field, 7);
+    EXPECT_FALSE(result->optional_field.has_value());
+    EXPECT_EQ(result->defaulted_field, std::string{});
+}
+
+TEST_CASE(defaulted_field_can_be_absent) {
+    auto result = from_json<MixedStruct>(R"({"required_field": 1})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->defaulted_field, std::string{});
+}
+
+TEST_CASE(defaulted_field_present_is_used) {
+    auto result = from_json<MixedStruct>(R"({"required_field": 1, "defaulted_field": "hi"})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->defaulted_field, std::string{"hi"});
+}
+
+TEST_CASE(all_optional_struct_empty_object_succeeds) {
+    auto result = from_json<AllOptional>(R"({})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_FALSE(result->a.has_value());
+    EXPECT_FALSE(result->b.has_value());
+}
+
+TEST_CASE(unknown_fields_ignored_by_default) {
+    auto result = from_json<StrictStruct>(R"({"x": 1, "name": "ok", "extra": true})");
+    ASSERT_TRUE(result.has_value());
+    EXPECT_EQ(result->x, 1);
+}
+
+};  // TEST_SUITE(serde_required_fields)
+
 }  // namespace
 
 }  // namespace eventide::serde

tests/unit/serde/json/simdjson_variant_detail_tests.cpp

@@ -718,13 +718,24 @@ TEST_CASE(in_optional) {
     EXPECT_FALSE(out.has_value());
 }
 
-TEST_CASE(default_field_values_preserved) {
-    // When a struct field is missing in the JSON, it should keep its default
+TEST_CASE(missing_required_field_rejects_tagged_candidate) {
+    // Missing non-optional field in a tagged variant should fail deserialization
     IntTagShape out{};
-    ASSERT_TRUE(from_json(R"({"type":"rect","width":5.0})", out).has_value());
-    auto& rect = std::get<Rect>(out);
-    EXPECT_EQ(rect.width, 5.0);
-    EXPECT_EQ(rect.height, 0.0);  // default
+    auto result = from_json(R"({"type":"rect","width":5.0})", out);
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST_CASE(missing_required_field_rejects_untagged_variant_candidate) {
+    // In untagged variant probing, a missing required field should reject
+    // the candidate and try the next alternative.
+    // Circle has field "radius", Rect has "width" + "height".
+    // {"width": 5.0} is missing "height" so Rect should be rejected.
+    using UntaggedShape = std::variant<Rect, Circle>;
+    UntaggedShape out{};
+    // This should fail because Rect needs both width+height, and Circle
+    // doesn't match either (no "radius" field).
+    auto result = from_json(R"({"width":5.0})", out);
+    EXPECT_FALSE(result.has_value());
 }
 
 };  // TEST_SUITE(serde_variant_int_tag)

tests/unit/serde/standard_case_suite.h

@@ -39,10 +39,13 @@
 #include <variant>
 #include <vector>
 
+#include "eventide/serde/serde/annotation.h"
 #include "eventide/serde/serde/attrs.h"
 
 namespace eventide::serde::standard_case {
 
+using eventide::serde::defaulted;
+
 struct Basic {
     bool is_valid{};
     std::int32_t i32{};
@@ -63,7 +66,7 @@ struct Compound {
 struct Nullables {
     std::optional<int> opt_value;
     std::optional<std::string> opt_empty;
-    std::unique_ptr<Basic> heap_allocated;
+    defaulted<std::unique_ptr<Basic>> heap_allocated;
 
     auto operator==(const Nullables& other) const -> bool {
         if(opt_value != other.opt_value || opt_empty != other.opt_empty) {
@@ -87,7 +90,7 @@ enum class Role : std::uint8_t {
 
 struct ADTs {
     Role role{};
-    std::variant<std::monostate, int, std::string, Basic> multi_variant;
+    defaulted<std::variant<std::monostate, int, std::string, Basic>> multi_variant;
 
     auto operator==(const ADTs&) const -> bool = default;
 };
@@ -178,10 +181,10 @@ inline auto pointer_value_equal(const Ptr& lhs, const Ptr& rhs) -> bool {
 }
 
 struct SmartPointers {
-    std::unique_ptr<Basic> unique_basic;
-    std::shared_ptr<Basic> shared_basic;
-    std::shared_ptr<Basic> shared_empty;
-    std::vector<std::shared_ptr<Basic>> shared_list;
+    defaulted<std::unique_ptr<Basic>> unique_basic;
+    defaulted<std::shared_ptr<Basic>> shared_basic;
+    defaulted<std::shared_ptr<Basic>> shared_empty;
+    defaulted<std::vector<std::shared_ptr<Basic>>> shared_list;
     std::optional<std::shared_ptr<Basic>> opt_shared;
 
     auto operator==(const SmartPointers& other) const -> bool {
@@ -368,16 +371,14 @@ inline auto make_ultimate() -> Ultimate {
         .heterogeneous_tuple = std::tuple<int, bool, std::string>{7,       true,   "tuple"},
     };
 
-    out.nullables = Nullables{
-        .opt_value = 17,
-        .opt_empty = std::nullopt,
-        .heap_allocated = std::make_unique<Basic>(Basic{
-            .is_valid = false,
-            .i32 = 128,
-            .f64 = -9.75,
-            .text = "heap",
-        }),
-    };
+    out.nullables.opt_value = 17;
+    out.nullables.opt_empty = std::nullopt;
+    out.nullables.heap_allocated = std::make_unique<Basic>(Basic{
+        .is_valid = false,
+        .i32 = 128,
+        .f64 = -9.75,
+        .text = "heap",
+    });
 
     out.adts = ADTs{
         .role = Role::user,