Document why storage object types must stay out of shared client assemblies

[allister-beamable]

Gap

The CLI guides explain how to share types between a Microservice and a Unity client, but never warn which types must not be shared. ms-troubleshooting.md says:

Types used in [ClientCallable] methods must be available to both server and client… Move shared types (DTOs, Enums, etc.) to a shared project referenced by both Unity and the server.

There is no complementary guidance about storage object types. ms-storage.md covers creating a Storage Object but says nothing about type sharing or the client boundary. A search of the docs finds no mention of BsonElement, "shared assembly", or the DSO/DTO distinction.

The phenomenon to document

Storage object types (DSOs) are decorated with MongoDB BSON attributes (e.g. [BsonElement], [BsonId]) from the MongoDB.Bson namespace. The shared/Common Library project is consumed by the Unity client, which has no MongoDB.Bson reference — so if a DSO is placed in that shared assembly, Unity builds fail to compile.

The takeaway for developers: DTOs go into the shared project; DSOs stay out of it (keep storage document types in the Storage/Microservice project only).

Risk

The existing "move shared types to a shared project" advice can actively mislead — a developer may reasonably drop their Mongo document classes into the Common Library, hitting exactly this failure.

Suggested fix

• Primary: a warning in ms-storage.md (where DSOs are defined) — keep storage document types out of shared/Common Library projects, with a one-line "why" (Unity has no BSON reference)
• Optional: a cross-link sentence in the ms-troubleshooting.md shared-types section noting the inverse (DTOs in, DSOs out)

These are core-owned guides, so the fix lands on the core branches and auto-syncs downstream. Verify the exact attribute names / assembly-reference model against the SDK source (beamable/BeamableProduct, project new common-lib) before writing.