chore: sync pulse-prd (#441)

* docs: describe protoc-gen-bitwise as it actually works; drop dead BitReader/BitWriter

CLAUDE.md still documented the original bit-stream design (BitWriter/
BitReader classes, float fields, "68 bits = 9 bytes on the wire"). The
plugin actually emits quantized-accessor partials (*.Bitwise.cs) over
plain uint32 fields sent as standard protobuf varints, backed only by
Quantize.cs; runtime BitReader.cs/BitWriter.cs were referenced by
nothing and are removed. Also sync README with current generator output
(QuantizedStep consts, AreQuantizedFieldsInRange, EncodePower/
DecodePower, per-proto-file output naming) and drop the incorrect
"cached" accessor wording.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: normalize CRLF when comparing gen:test golden fixtures

With core.autocrlf=true (and no .gitattributes) git materializes the
golden .cs fixtures with CRLF on Windows while the generator always
emits LF, so the strict byte comparison failed on any fresh Windows
checkout. Normalize line endings when reading the goldens.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: add realm in pulse PlayerJoined message

* added realm to teleport performed message

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Lorenzo Ranciaffi <lorenzo.ranciaffi@decentraland.org>

Author: 3 people

CLAUDE.md

@@ -10,15 +10,23 @@ High-performance MMO-style multiplayer networking stack. Protocol is **open** (U
 | Client | Unity (C#) |
 | Server | Custom server |
 | Schema source of truth | `.proto` files |
-| Serialization | Custom protoc plugin (bitwise encoding) |
+| Serialization | Standard protobuf wire format + custom protoc plugin (quantized float accessors) |
 | Auth | Decentraland ECDSA chain validation (local, on HANDSHAKE channel 0) |
 
 ---
 
 ## Serialization: Custom Protoc Plugin
 
 ### What it does
-Reads `.proto` files with custom field options and generates **bitwise encode/decode code** in C#, keeping all client implementations bit-for-bit identical.
+Reads `.proto` files with custom field options and generates C# **partial classes** (`*.Bitwise.cs`) that add typed float accessors on top of quantized `uint32` fields, keeping the quantization math bit-for-bit identical across all client implementations.
+
+The wire format is **standard protobuf** — a quantized value lives in a plain `uint32` field and travels as an ordinary varint. There is no custom bit stream; any protobuf-capable client can parse the messages without this plugin. Per annotated field the plugin emits:
+
+- `float {Field}Quantized` — computed accessor (no backing cache): the getter decodes the stored `uint32`, the setter encodes a float back into it, via the static `Quantize` helpers
+- `const float {Field}QuantizedStep` — the coarsest quantization step of the field, safe as an equality tolerance
+- per message: `bool AreQuantizedFieldsInRange()` — pure-integer check that every stored code fits its declared bit width (`0 .. 2^bits-1`); reject malformed/hostile messages before storing or relaying
+
+Only non-repeated `uint32` fields get accessors; `bit_packed` and unannotated fields pass through with no generated code.
 
 ### Custom Field Options (`options.proto`)
 
@@ -54,25 +62,31 @@ extend google.protobuf.FieldOptions {
 
 ### Usage example
 
+Quantized fields are declared **`uint32`** (not `float`) — the float type exists only in the generated accessor:
+
 ```protobuf
 message PositionDelta {
-  float  dx        = 1 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
-  float  dy        = 2 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
-  float  dz        = 3 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
+  uint32 dx        = 1 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
+  uint32 dy        = 2 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
+  uint32 dz        = 3 [(quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
   uint32 entity_id = 4 [(bit_packed) = { bits: 20 }];
+  uint32 sequence  = 5 [(bit_packed) = { bits: 12 }];
 }
-// Total: 68 bits = 9 bytes on the wire
+// Varint wire cost: dx/dy/dz/entity_id ≤ 4 B each (1 B tag + ≤ 3 B varint),
+// sequence ≤ 3 B — worst-case 19 B, less when proto3 omits zero-valued fields.
 ```
 
+`proto/decentraland/common/quantization_example.proto` is the fully worked reference: per-field wire costs for the linear, power-law, and bit-packed annotations.
+
 ### Plugin structure
 
 ```
 protoc-gen-bitwise/
 ├── plugin.js            # stdin -> CodeGeneratorRequest, stdout -> CodeGeneratorResponse (Node)
-├── generator_csharp.js  # emits C# for Unity
-├── options.js           # parses the custom quantized / bit_packed field options
+├── generator_csharp.js  # emits the *.Bitwise.cs accessor partials for Unity
+├── options.js           # parses the custom quantized / quantized_power / bit_packed field options
 ├── wire.js              # self-contained protobuf wire codec (zero runtime deps)
-└── runtime/cs/          # C# runtime; Quantize.cs is copied into the generated output
+└── runtime/cs/          # C# runtime: Quantize.cs — consumers copy it next to the generated files
 ```
 
 Plugin contract: a protoc plugin that reads a serialized `CodeGeneratorRequest` from stdin and writes a serialized `CodeGeneratorResponse` to stdout. It is a plain Node script — **no `npm install` required, only `node` on PATH**. protoc invokes it through a tiny wrapper that runs `node plugin.js` (`.cmd` on Windows, a shell script elsewhere, since protoc cannot exec a `.js` directly).
@@ -89,85 +103,30 @@ Parity is locked down by `npm run gen:test` (compares generator output against g
 
 ---
 
-## BitWriter / BitReader
+## Quantize Runtime
 
-The C# implementation uses the following bit layout: **big-endian within each byte**, MSB written first. Use **`Round`** (not truncate) when quantizing to minimize error.
+Generated accessors call the static `Quantize` class (`protoc-gen-bitwise/runtime/cs/Quantize.cs`, namespace `Decentraland.Networking.Bitwise`) — the only C# runtime file; consumers copy it next to the generated `*.Bitwise.cs` partials. Quantization uses **`Round`** (not truncate) to minimize error; identical rounding on both sides makes encode -> decode a round-trip no-op.
 
-### Core math — WriteQuantizedFloat
+### Core math — linear (`Quantize.Encode` / `Quantize.Decode`)
 
 ```
-normalized = (clamp(value, min, max) - min) / (max - min)  // -> [0.0, 1.0]
-quantized  = Round(normalized * ((1 << bits) - 1))          // -> integer
+encoded = Round(clamp01((value - min) / (max - min)) * (2^bits - 1))
+decoded = encoded / (2^bits - 1) * (max - min) + min
 ```
 
-### Core math — ReadQuantizedFloat
+### Core math — power-law (`Quantize.EncodePower` / `Quantize.DecodePower`)
+
+For signed fields like velocity that need an exact zero and fine resolution near zero:
 
 ```
-normalized = quantized / ((1 << bits) - 1)
-value      = min + normalized * (max - min)
+u       = clamp01(|value| / max) ^ (1 / pow)
+encoded = (Round(u * (2^(bits-1) - 1)) << 1) | sign     // magnitude in high bits, sign in LSB
+decoded = sign * max * ((encoded >> 1) / (2^(bits-1) - 1)) ^ pow
 ```
 
-### Implementation
-
-```csharp
-public class BitWriter
-{
-    private byte[] _buffer;
-    private int    _bitPos;
-
-    public BitWriter(byte[] buffer) { _buffer = buffer; _bitPos = 0; }
-
-    public void WriteBits(uint value, int bits)
-    {
-        for (int i = bits - 1; i >= 0; i--)
-        {
-            int byteIdx = _bitPos / 8;
-            int bitIdx  = 7 - (_bitPos % 8);
-            if ((value >> i & 1) == 1) _buffer[byteIdx] |=  (byte)(1 << bitIdx);
-            else                       _buffer[byteIdx] &= (byte)~(1 << bitIdx);
-            _bitPos++;
-        }
-    }
-
-    public void WriteQuantizedFloat(float value, float min, float max, int bits)
-    {
-        uint  maxQ       = (1u << bits) - 1;
-        float clamped    = Math.Clamp(value, min, max);
-        float normalized = (clamped - min) / (max - min);
-        uint  quantized  = (uint)Math.Round(normalized * maxQ);
-        WriteBits(quantized, bits);
-    }
-}
-
-public class BitReader
-{
-    private byte[] _buffer;
-    private int    _bitPos;
-
-    public BitReader(byte[] buffer) { _buffer = buffer; _bitPos = 0; }
-
-    public uint ReadBits(int bits)
-    {
-        uint value = 0;
-        for (int i = bits - 1; i >= 0; i--)
-        {
-            int byteIdx = _bitPos / 8;
-            int bitIdx  = 7 - (_bitPos % 8);
-            if ((_buffer[byteIdx] >> bitIdx & 1) == 1) value |= 1u << i;
-            _bitPos++;
-        }
-        return value;
-    }
-
-    public float ReadQuantizedFloat(float min, float max, int bits)
-    {
-        uint  maxQ       = (1u << bits) - 1;
-        uint  quantized  = ReadBits(bits);
-        float normalized = (float)quantized / maxQ;
-        return min + normalized * (max - min);
-    }
-}
-```
+- Zero encodes exactly to code `0` (a zero magnitude never sets the sign bit), so proto3 omits a stopped field entirely
+- `pow > 1` concentrates resolution near zero, coarse near `±max`
+- Sign in the LSB makes the varint cost track magnitude, not direction — a small `|value|` of either sign stays in one varint byte
 
 ---
 
@@ -181,13 +140,24 @@ public class BitReader
 
 Sub-centimeter precision is achievable at 12-16 bits for position deltas.
 
+Wire cost is varint-based — 1 tag byte per present field (field numbers ≤ 15) plus:
+
+| Code bits | Worst-case varint | Worst-case field total |
+|-----------|-------------------|------------------------|
+| ≤ 7       | 1 B               | 2 B                    |
+| ≤ 14      | 2 B               | 3 B                    |
+| ≤ 21      | 3 B               | 4 B                    |
+
+Proto3 omits fields equal to 0, so typical cost is lower than worst-case.
+
 ---
 
 ## Key Design Principles
 
 - `.proto` files are the **single source of truth** for all message schemas
-- The protoc plugin generates **C#** from the schema — never hand-write serialization
+- The protoc plugin generates the **C# quantized accessors** from the schema — never hand-write quantization math; standard protobuf handles the wire encoding
 - Encode -> decode is a **no-op** (round-trip safe) due to consistent use of `Round`
+- Validate inbound quantized messages with `AreQuantizedFieldsInRange()` before storing or relaying — the server relays raw codes verbatim
 - Prefer **client-driven resync** over proactive server corrections
 - Push complexity to clients where appropriate; server maintains authority
 - Channel 0: reliable messages (STATE_FULL snapshots, ACKs, resync requests, HANDSHAKE)

README.md

@@ -90,8 +90,10 @@ Rather than a separate binary packing layer, the plugin leverages this:
 2. `--csharp_out` generates the standard protobuf class with the raw `uint32`
    property (e.g. `PositionX`).
 3. `--bitwise_out` (this plugin) generates a `partial class` extension with a
-   cached float accessor (e.g. `PositionXQuantized`) that encodes/decodes
-   transparently via `Quantize.Encode` / `Quantize.Decode`.
+   computed float accessor (e.g. `PositionXQuantized`) that encodes/decodes
+   transparently via `Quantize.Encode` / `Quantize.Decode` on every access —
+   the raw `uint32` property remains the single source of truth (no cache to
+   go stale when the raw field is mutated directly).
 
 The wire representation is a standard protobuf message — any protobuf-capable
 client can read it without knowledge of the plugin.
@@ -133,8 +135,8 @@ message PositionDelta {
 
 | Annotation | Target type | Parameters | Effect |
 |---|---|---|---|
-| `[(decentraland.common.quantized)]` | `uint32` | `min`, `max`, `bits` | Plugin emits a cached `float {Name}Quantized` accessor |
-| `[(decentraland.common.quantized_power)]` | `uint32` | `max`, `pow`, `bits` | Power-law quantizer over `[-max, max]`: `(bits-1)`-bit magnitude (high bits) + sign (LSB), decoded as `sign·max·u^pow`. Exact zero; `pow>1` gives fine resolution near zero, coarse near `±max`; sign in the LSB keeps small magnitudes one varint byte. Cached `float {Name}Quantized` accessor (`Quantize.EncodePower`/`DecodePower`) |
+| `[(decentraland.common.quantized)]` | `uint32` | `min`, `max`, `bits` | Plugin emits a `float {Name}Quantized` accessor and a `{Name}QuantizedStep` const |
+| `[(decentraland.common.quantized_power)]` | `uint32` | `max`, `pow`, `bits` | Power-law quantizer over `[-max, max]`: `(bits-1)`-bit magnitude (high bits) + sign (LSB), decoded as `sign·max·u^pow`. Exact zero; `pow>1` gives fine resolution near zero, coarse near `±max`; sign in the LSB keeps small magnitudes one varint byte. `float {Name}Quantized` accessor (`Quantize.EncodePower`/`DecodePower`) |
 | `[(decentraland.common.bit_packed)]` | `uint32` | `bits` | Documents the value range; protobuf handles varint compaction automatically |
 
 ### Wire cost at worst-case (all bits set)
@@ -183,13 +185,15 @@ Assets/
 ```
 
 `Quantize.cs` lives in the `Decentraland.Networking.Bitwise` namespace and
-provides two static methods used by the generated accessors:
+provides the static encode/decode methods used by the generated accessors:
 
 ```csharp
 public static class Quantize
 {
     public static uint  Encode(float value, float min, float max, int bits);
     public static float Decode(uint encoded, float min, float max, int bits);
+    public static uint  EncodePower(float value, float max, float pow, int bits);
+    public static float DecodePower(uint encoded, float max, float pow, int bits);
 }
 ```
 
@@ -213,14 +217,18 @@ SendOnChannel1(bytes);
 
 // --- Receive and read ---
 var received = PositionDelta.Parser.ParseFrom(receivedBytes);
+if (!received.AreQuantizedFieldsInRange()) return;   // reject malformed/hostile codes
 float x = received.DxQuantized;   // decoded from the stored uint32 on each access
 float y = received.DyQuantized;
 float z = received.DzQuantized;
 ```
 
 ## Generated file example
 
-For the `PositionDelta` message above the plugin emits `PositionDelta.Bitwise.cs`:
+For the `comms.proto` file above the plugin emits `Comms.Bitwise.cs` (one file
+per `.proto`, named after the proto file). Each quantized field gets a
+`{Name}QuantizedStep` const and a float accessor; each message gets an
+`AreQuantizedFieldsInRange()` guard for validating inbound wire codes:
 
 ```csharp
 // <auto-generated>
@@ -234,23 +242,44 @@ namespace Decentraland.Kernel.Comms.V3
 {
     public partial class PositionDelta
     {
+        /// <summary>Coarsest quantization step of <see cref="DxQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DxQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dx"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
         public float DxQuantized
         {
             get => Quantize.Decode(Dx, -100.0f, 100.0f, 16);
             set => Dx = Quantize.Encode(value, -100.0f, 100.0f, 16);
         }
 
+        /// <summary>Coarsest quantization step of <see cref="DyQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DyQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dy"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
         public float DyQuantized
         {
             get => Quantize.Decode(Dy, -100.0f, 100.0f, 16);
             set => Dy = Quantize.Encode(value, -100.0f, 100.0f, 16);
         }
 
+        /// <summary>Coarsest quantization step of <see cref="DzQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DzQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dz"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
         public float DzQuantized
         {
             get => Quantize.Decode(Dz, -100.0f, 100.0f, 16);
             set => Dz = Quantize.Encode(value, -100.0f, 100.0f, 16);
         }
+
+        /// <summary>
+        ///     True when every quantized field holds a wire code within its declared bit width
+        ///     (<c>0 .. 2^bits-1</c>). The encoder never emits a code above this bound, so a larger
+        ///     value is a malformed/hostile message: decoding it would land far outside the field's
+        ///     <c>[min, max]</c> and, since the server relays raw codes verbatim, poison every observer.
+        ///     Reject before storing or relaying. Pure integer comparison — no decode.
+        /// </summary>
+        public bool AreQuantizedFieldsInRange() =>
+            Dx <= 65535u
+            && Dy <= 65535u
+            && Dz <= 65535u;
     }
 
 } // namespace Decentraland.Kernel.Comms.V3

proto/decentraland/pulse/pulse_server.proto

@@ -84,6 +84,7 @@ message PlayerJoined {
   string user_id = 1;
   int32 profile_version = 2;
   PlayerStateFull state = 3;
+  string realm = 4;
 }
 
 // Notification to the client, that a peer has left, it can mean disconnection or leaving the area of interest
@@ -125,6 +126,7 @@ message TeleportPerformed {
   uint32 sequence = 2;
   uint32 server_tick = 3;
   PlayerState state = 4;
+  string realm = 5;
 }
 
 message ServerMessage {