docs: add ADR-012 and MessagePack serialization guidelines

- Update design.md with MessagePack component requirements
- Add ADR-012 to architecture.md regarding public type requirements
- Add MessagePackAnalyzer to OECS.csproj for compile-time validation

design.md

@@ -10,9 +10,18 @@ Divided into identifer bits and version bits.
 
 ## Component
 
-c# structs marked for [MessagePack](https://github.com/MessagePack-CSharp/MessagePack-CSharp) serialization.
+C# structs/classes marked with `[MessagePackObject]` and `[Key]` attributes for
+[MessagePack-CSharp](https://github.com/MessagePack-CSharp/MessagePack-CSharp) serialization.
 
-Components are in sparse-sets so they can cheaply be added/removed.
+- Types must be `public` — MessagePack requires public accessibility.
+- Use indexed integer keys (`[Key(0)]`) for best performance and smallest binary
+  size. String keys are available for debugging/interop but slower.
+- For contractless usage, `[MessagePackObject(keyAsPropertyName: true)]` is
+  available.
+- The `MessagePackAnalyzer` package provides compile-time validation and AOT-safe
+  source-generated formatters.
+
+Components are stored in sparse-sets so they can cheaply be added/removed.
 
 ## Relationship
 

docs/architecture.md

@@ -334,3 +334,32 @@ no parallel scheduling.
 
 - Consumers must be on .NET 8 or later.
 - Can use `ref` returns, `readonly struct`, and other modern C# features.
+
+---
+
+## ADR-012: Public Types Required for MessagePack Serialization
+
+**Status:** Accepted
+
+**Context:** Component types must be serializable by MessagePack-CSharp. The
+library imposes constraints on type design.
+
+**Decision:** Component types must be `public` and annotated with
+`[MessagePackObject]` and `[Key]` attributes. The `MessagePackAnalyzer` NuGet
+package is included for compile-time validation.
+
+**Rationale:**
+
+- MessagePack-CSharp requires public types for its dynamic formatter generation
+  and source-generated formatters.
+- `MessagePackAnalyzer` provides AOT-safe source-generated formatters (critical
+  for Unity IL2CPP) and catches misconfigured types at compile time.
+- Indexed integer keys (`[Key(0)]`) produce the fastest and most compact
+  serialization, which aligns with the ECS performance goal.
+
+**Consequences:**
+
+- Component authors cannot use `private` or `internal` types.
+- The `MessagePackAnalyzer` package is a compile-time dependency.
+- `[Key]` indices should be sequential starting from 0 to avoid null
+  placeholders in the binary output.

src/OECS/OECS.csproj

@@ -15,7 +15,11 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="MessagePack" Version="3.1.3" />
+    <PackageReference Include="MessagePack" Version="3.1.7" />
+    <PackageReference Include="MessagePackAnalyzer" Version="3.1.7">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
     <PackageReference Include="R3" Version="1.2.9" />
   </ItemGroup>