@axpecter/lync 2.2.1 → 2.3.2

package/README.md

@@ -9,18 +9,17 @@
   <a href="#benchmarks">Benchmarks</a>
 </p>
 
-Packets, queries, groups, validation, and rate limiting — all batched into one buffer per player per frame. No code generation.
+Schemas, packets, queries, groups, validation, rate limiting. Every send batches into one buffer per player per frame; identical frames XOR to ones already in flight; delta codecs collapse unchanged state to a single byte. No code generation.
 
 ## Install
 
-**Wally**
+Wally — add to your `wally.toml`:
 
 ```toml
-[dependencies]
-Lync = "axp3cter/lync@2.2.1"
+Lync = "axp3cter/lync@2.3.2"
 ```
 
-**npm (roblox-ts)**
+npm (roblox-ts):
 
 ```bash
 npm install @axpecter/lync
@@ -30,10 +29,7 @@ npm install @axpecter/lync
 import Lync from "@axpecter/lync";
 ```
 
-Or grab the `.rbxm` from [Releases](https://github.com/Axp3cter/Lync/releases/latest).
-
-> [!IMPORTANT]
-> Define all packets, queries, and groups before calling `Lync.start()`.
+**Important.** Define every packet, query, and group before `Lync.start()`. Definitions assign sequential 7-bit IDs that both peers must agree on; defining late on one side desyncs the wire.
 
 ## Example
 
@@ -72,7 +68,7 @@ local Players = game:GetService("Players")
 local alive = Lync.group("alive")
 Players.PlayerAdded:Connect(function(p) alive:add(p) end)
 
-Net.Hit:on(function(data, sender) -- ... end)
+Net.Hit:on(function(data, sender) end)
 Net.Ping:handle(function() return os.clock() end)
 
 Lync.start()
@@ -91,7 +87,7 @@ local Net  = require(game.ReplicatedStorage.Net)
 Lync.start()
 
 local scope = Lync.scope()
-scope:on(Net.State, function(state) -- ... end)
+scope:on(Net.State, function(state) end)
 
 Net.Hit:send({ targetId = 123, damage = 45 })
 local serverTime = Net.Ping:request(nil)
@@ -103,18 +99,19 @@ local serverTime = Net.Ping:request(nil)
 
 | Function | Description |
 |:---|:---|
-| `Lync.configure(opts)` | Set options. Must precede `start()`. |
+| `Lync.configure(opts)` | Apply options. Must precede `start()`. |
 | `Lync.start()` | Initialize transport. Call once. |
 | `Lync.isStarted()` | `true` after `start()`. |
 | `Lync.flush()` | Force an immediate send. |
-| `Lync.flushRate(hz)` | 1–60. Default 60. |
+| `Lync.flushRate(hz)` | 1–60 Hz. Default 60. |
+| `Lync.reset()` | Restore module state to post-require defaults. For tests / hot reload. |
 
 ### Configure options
 
 | Option | Default | Range | Description |
 |:---|---:|:---|:---|
-| `channelMaxSize` | 262144 | 4 KB – 1 MB | Max buffer bytes per frame. |
-| `validationDepth` | 16 | 4–32 | Max recursion depth for input validation. |
+| `channelMaxSize` | 262144 | 4 KB – 1 MB | Per-frame buffer cap. |
+| `validationDepth` | 16 | 4–32 | Schema-walk recursion limit. |
 | `poolSize` | 16 | 2–128 | Reusable channel-state pool. |
 | `bandwidthLimit` | none | — | `{ softLimit, maxStrikes }` per-player throttle. |
 | `globalRateLimit` | none | — | `{ maxPerSecond }` across all packets per player. |
@@ -128,44 +125,44 @@ local serverTime = Net.Ping:request(nil)
 -- Server
 packet:send(data, player)
 packet:send(data, Lync.all)
-packet:send(data, Lync.except(p1, p2))
+packet:send(data, Lync.except(p1, group1))
 packet:send(data, { p1, p2, p3 })
 packet:send(data, group)
 
 -- Client
 packet:send(data)
 
--- Both
-packet:on(function(data, sender, timestamp?) end)  -- returns Connection
+-- Both sides
+local conn = packet:on(function(data, sender, timestamp) end)
 packet:once(fn)
-packet:wait()                                       -- yields, returns data, sender, timestamp?
+local data, sender, timestamp = packet:wait()
 packet:name()
-packet:stats()                                      -- requires stats=true
+packet:stats() -- requires stats=true
 ```
 
 | Option | Type | Description |
 |:---|:---|:---|
-| `unreliable` | boolean | Use `UnreliableRemoteEvent`. Disallowed with delta codecs. |
-| `rateLimit` | `RateLimitConfig` | Server-side per-player limit. |
-| `validate` | `(data, player) → (bool, string?)` | Drop on `false`. |
-| `maxPayloadBytes` | number | Reject oversize incoming payloads. |
-| `timestamp` | `"frame"` / `"offset"` / `"full"` | Append 1B / 2B / 8B timestamp. Read as third arg. |
+| `unreliable` | boolean | Use `UnreliableRemoteEvent`. Rejected with delta codecs (a dropped frame would desync the baseline). |
+| `rateLimit` | `RateLimitConfig` | Server-side per-player. |
+| `validate` | `(data, player) → (bool, string?)` | Drop on `false`. Reason is forwarded to `onDrop`. |
+| `maxPayloadBytes` | number | Reject oversize incoming payloads early. |
+| `timestamp` | `"frame"`, `"offset"`, `"full"` | Append 1B / 2B / 8B timestamp. Read as the third arg. |
 
 ### Queries
 
 `Lync.query(name, requestCodec, responseCodec, options?)`
 
-Request-response on top of two packet IDs.
+Request-response on top of two paired registrations. Single-target requests yield until reply or timeout; multi-target requests gather a partial map.
 
 ```luau
 -- Server
 query:handle(function(data, player) return response end)
-query:request(data, player)             -- → response?
-query:request(data, target)             -- → { [Player]: response? }
+local resp = query:request(data, player)        -- response?
+local map  = query:request(data, group)         -- { [Player]: response? }
 
 -- Client
 query:handle(function(data) return response end)
-query:request(data)                     -- yields, → response? (nil on timeout)
+local resp = query:request(data)                -- yields; nil on timeout
 ```
 
 | Option | Default | Description |
@@ -180,14 +177,14 @@ query:request(data)                     -- yields, → response? (nil on timeout
 
 | Method | Returns | Description |
 |:---|:---|:---|
-| `group:add(p)` / `:remove(p)` | boolean | `true` if changed. |
-| `group:has(p)` | boolean | Membership. |
-| `group:count()` | number | |
-| `group:destroy()` | — | Clear and free name. |
+| `:add(p)` / `:remove(p)` | `boolean` | `true` if membership changed. |
+| `:has(p)` | `boolean` | |
+| `:count()` | `number` | |
+| `:destroy()` | — | Clear members and free the name. |
 
 ### Scope
 
-`Lync.scope()` — batches connections for cleanup.
+`Lync.scope()` — batches connections for a single `:destroy()`.
 
 ```luau
 local scope = Lync.scope()
@@ -205,43 +202,46 @@ Server-side `:send` second arg.
 |:---|:---|
 | `Player` | One player. |
 | `Lync.all` | All connected. |
-| `Lync.except(...)` | Everyone except given players or groups. |
+| `Lync.except(...)` | Everyone except given Players or Groups. |
 | `{ p1, p2 }` | Array of players. |
 | `group` | All members. |
 
 ### Middleware
 
 ```luau
-Lync.onSend(function(data, name, player)    return data end)  -- return Lync.DROP to discard
+-- Return Lync.DROP from onSend to discard a packet.
+Lync.onSend(function(data, name, player) return data end)
 Lync.onReceive(function(data, name, player) return data end)
 Lync.onDrop(function(player, reason, name, data) end)
 ```
 
-All return a `Connection`.
+All return a `Connection`. A throwing hook surfaces to the caller and aborts the chain at that point.
 
 ### Connection
 
 | | |
 |:---|:---|
-| `c.connected` | boolean |
+| `c.connected` | `boolean` |
 | `c:disconnect()` | Idempotent. |
 
 ### Stats
 
-`Lync.configure({ stats = true })`.
+Enable with `Lync.configure({ stats = true })`.
 
 | Function | Description |
 |:---|:---|
 | `Lync.stats.player(p)` | `{ bytesSent, bytesReceived }`. Server only. |
 | `Lync.stats.reset()` | Zero all counters. |
-| `packet:stats()` | `{ bytesSent, bytesReceived, fires, recvFires, drops }` |
+| `packet:stats()` | `{ bytesSent, bytesReceived, fires, recvFires, drops }`. Aggregated across the request + response registrations on queries. |
 
 ### Debug
 
 | Function | Description |
 |:---|:---|
-| `Lync.debug.pending()` | In-flight query requests. |
-| `Lync.debug.registrations()` | Frozen array of `{ name, id, kind, isUnreliable }`. |
+| `Lync.debug.pending()` | In-flight query correlation IDs. |
+| `Lync.debug.registrations()` | Frozen `{ name, id, kind, isUnreliable }` per registration. |
+
+`capture` / `stop` / `dump` are reserved no-ops for capture/replay tooling.
 
 ## Codecs
 
@@ -249,9 +249,10 @@ All return a `Connection`.
 
 | Codec | Bytes | Notes |
 |:---|---:|:---|
-| `int(min, max)` | 1 / 2 / 4 | Picks smallest u8/u16/u32/i8/i16/i32. |
-| `f16` / `f32` / `f64` | 2 / 4 / 8 | f16: ±65504, ~3 digits. |
-| `float(min, max, precision)` | 1–4 | Quantized. Clamped. |
+| `int(min, max)` | 1 / 2 / 4 | Picks narrowest u8/u16/u32/i8/i16/i32. |
+| `zint(min?, max?)` | 1 – 5 | Variable-length signed via zigzag varint. 1 byte for [-96, 95]. |
+| `f16` / `f32` / `f64` | 2 / 4 / 8 | `f16` ≈ ±65504, ~3 digits. |
+| `float(min, max, precision)` | 1 / 2 / 3 / 4 | Quantized; picks u8 / u16 / u24 / u32 wire form. |
 | `bool` | 1 | Auto-bitpacked inside `struct` and `array`. |
 
 ### Strings & buffers
@@ -260,7 +261,7 @@ All return a `Connection`.
 |:---|:---|
 | `string` | Variable length. Binary-safe. |
 | `string(maxLength)` | Bounded. Rejects on read if exceeded. |
-| `buff` | Variable-length buffer. |
+| `buff` | Variable-length raw `buffer`. |
 
 ### Roblox types
 
@@ -269,7 +270,7 @@ All return a `Connection`.
 | `vec2` / `vec3` | 8 / 12 |
 | `cframe` | 24 |
 | `color3` | 3 |
-| `inst` | 2 |
+| `inst` | 2 (sidecar ref index) |
 | `udim` / `udim2` | 8 / 16 |
 | `numberRange` | 8 |
 | `rect` | 16 |
@@ -284,136 +285,97 @@ Call as a function for compression.
 
 | Codec | Bytes | Notes |
 |:---|---:|:---|
-| `vec2(min, max, precision)` | 2–8 | Per-component. |
-| `vec3(min, max, precision)` | 3–12 | Per-component. |
-| `cframe()` | 16 | Smallest-three quaternion. ≤0.16° rotation error. |
+| `vec2(min, max, precision)` | 2 / 4 / 6 / 8 | Per-component, narrowest fitting width. |
+| `vec3(min, max, precision)` | 3 / 6 / 9 / 12 | Per-component, narrowest fitting width. |
+| `cframe()` | 16 | Smallest-three quaternion. ≤ 0.16° rotation error. |
 
 ### Composites
 
 | Codec | Notes |
 |:---|:---|
-| `struct({k = c})` | Named fields. Bools auto-bitpacked. |
-| `array(c, max?)` | List. Bool arrays bitpacked. |
-| `map(k, v, max?)` | Key-value pairs. |
-| `optional(c)` | 1B nil flag + value. |
-| `tuple(...)` | Positional. |
-| `tagged(field, {name = c})` | Discriminated union. 1B tag. ≤256 variants. |
-
-### Delta — reliable only
-
-Sends 1 byte when unchanged.
-
-| Codec |
-|:---|
-| `deltaStruct(schema)` |
-| `deltaArray(c, max?)` |
-| `deltaMap(k, v, max?)` |
+| `struct({k = c})` | Named fields. Bools auto-bitpacked into a tail block. |
+| `array(c, max?)` | List. Bool arrays bitpacked. Direct path for fixed-size elements. |
+| `map(k, v, max?)` | Key-value pairs; keys sorted at encode for stable wire bytes. |
+| `optional(c)` | 1B presence flag + value. |
+| `tuple(...)` | Positional. All-direct fast path when every element is fixed-size. |
+| `tagged(field, {name = c})` | Discriminated union. 1B tag. Up to 256 variants. |
+
+### Delta — reliable transport only
+
+Tracks the previous frame's value and ships only what changed. Rejected on `unreliable = true`.
+
+| Codec | Static | Mutation |
+|:---|:---:|:---:|
+| `deltaStruct(schema)` | 1 B | per-field |
+| `deltaArray(c, max?)` | 1 B | per-changed-index |
+| `deltaMap(k, v, max?)` | 1 B | per-changed-key |
+| `deltaInt(min, max)` | 1 B | 1–5 B |
+| `deltaFloat(min, max, precision)` | 1 B | 1–5 B |
+| `deltaVec3(min, max, precision)` | 3 B | 3–15 B |
+| `deltaCFrame(posMin, posMax, precision)` | 1 B | 4–13 B |
+
+- `deltaArray` element / `deltaMap` key+value cannot themselves contain delta state. Use `deltaStruct` for per-field deltas inside.
+- `deltaVec3` and `deltaCFrame` error on out-of-range components.
 
 ### Meta
 
 | Codec | Notes |
 |:---|:---|
-| `enum(...)` | String enum. ≤256 variants. 1B. |
-| `bitfield(schema)` | 1–32 bits. Sub-byte packing. |
-| `custom(size, write, read, typeCheck?)` | User-defined fixed-size. |
-| `nothing` | 0 bytes. Reads `nil`. |
-| `unknown` | Bypass serialization. Use with `validate`. |
-| `auto` | Self-describing. nil/bool/numbers/strings/buffers/Roblox types. |
+| `enum(...)` | String enum. ≤ 256 variants. 1B u8 index. |
+| `bitfield(schema)` | 1–32 bits total. `{ type = "bool" }`, `{ type = "uint", width }`, `{ type = "int", width }`. |
+| `custom(size, write, read, typeCheck?)` | User-defined fixed-size codec. |
+| `nothing` | 0 bytes; reads `nil`. For fire-and-forget signals. |
+| `unknown` | Bypasses serialization through the channel sidecar. Must be paired with `validate`. |
+| `auto` | Self-describing: nil / bool / numbers / strings / buffers / Roblox datatypes. 1B type tag + payload. |
 
 ## Rate limiting
 
 Per-packet, pick one mode:
 
-```luau
-{ maxPerSecond = N, burst = M }   -- token bucket
-{ cooldown = seconds }             -- cooldown
-```
+- Token bucket: `{ maxPerSecond = N, burst = M }`
+- Cooldown: `{ cooldown = seconds }`
 
-Global per-player: `Lync.configure({ globalRateLimit = { maxPerSecond = N } })`.
+Global per-player cap: `Lync.configure({ globalRateLimit = { maxPerSecond = N } })`.
 
 ## Limits
 
 | | |
 |:---|---:|
-| Packet + query IDs | 127 |
+| Packet + query IDs (combined) | 127 |
 | Buffer per frame | 1 MB max |
-| In-flight queries | 65,536 |
+| In-flight queries | 65,535 |
 | Enum / tagged variants | 256 |
 | Bitfield total bits | 32 |
+| Sidecar refs per frame | 65,535 |
 
 ## Benchmarks
 
 `rojo serve bench.project.json` with one server + one client.
 
-CPU benches run a fixed 1000 iterations per case.
-
-### Codec throughput
-
-| Codec | Encode | Decode | RT/s |
-|:---|---:|---:|---:|
-| `bool` | 43 ns | 28 ns | 14.1 M |
-| `int(0, 255)` | 41 ns | 25 ns | 15.2 M |
-| `int(0, 65535)` | 40 ns | 25 ns | 15.3 M |
-| `f16` | 60 ns | 42 ns | 9.7 M |
-| `f32` | 41 ns | 26 ns | 14.9 M |
-| `f64` | 41 ns | 25 ns | 15.3 M |
-| `string` (10 chars) | 45 ns | 73 ns | 8.4 M |
-| `string` (1000 chars) | 74 ns | 250 ns | 3.1 M |
-| `vec3` | 56 ns | 27 ns | 12.1 M |
-| `vec3` quantized | 121 ns | 85 ns | 4.9 M |
-| `cframe` | 88 ns | 186 ns | 3.6 M |
-| `cframe()` | 118 ns | 214 ns | 3.0 M |
-| entity struct (6 fields) | 234 ns | 476 ns | 1.4 M |
-| 100× entities | 15.3 µs | 34.6 µs | 20 K |
-| 1000× bools (bitpacked) | 4.3 µs | 5.3 µs | 104 K |
-
-### Wire sizes
+### Cross-library — 1000 fires/frame, 10 s
 
-| Codec | Bytes |
-|:---|---:|
-| entity struct (6 fields, lossless) | 34 |
-| entity compact (quantized) | 13 |
-| 100× entities | 601 |
-| 1000× bools (bitpacked) | 127 |
-| bitfield flags | 2 |
-| `tuple(u8, vec3, bool)` | 14 |
-
-### Delta savings
-
-| Codec | Full | Unchanged |
-|:---|---:|---:|
-| `deltaStruct` (entity) | 35 B | 1 B |
-| `deltaStruct` (compact) | 14 B | 1 B |
-| `deltaArray` (100× entity) | 602 B | 1 B |
-| `deltaArray` (1000× bool) | 128 B | 1 B |
-| `deltaMap` (string → u8) | 19 B | 1 B |
-
-### Cross-library comparison
-
-Same methodology as [Blink](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md): 1000 fires/frame, identical data, 10 s. Other-tool numbers from Blink v0.17.1.
-
-> [!NOTE]
-> Lync batches all sends into one buffer per frame and bitpacks bools (1000 = 127 B vs ~1002 B). Delta compression isn't exercised here.
-
-**100× struct(6× u8) entities**
-
-| Tool | FPS | Kbps |
-|:---|---:|---:|
-| roblox | 16 | 559,364 |
-| **lync** | **60** | **3.47** |
-| blink | 42 | 41.81 |
-| zap | 39 | 41.71 |
-| bytenet | 32 | 41.64 |
-
-**1000× bool**
-
-| Tool | FPS | Kbps |
-|:---|---:|---:|
-| roblox | 21 | 353,107 |
-| **lync** | **60** | **2.33** |
-| blink | 97 | 7.91 |
-| zap | 52 | 8.10 |
-| bytenet | 35 | 8.11 |
+[Blink's methodology](https://github.com/1Axen/blink/blob/main/benchmark/Benchmarks.md): same payload reused every frame, identical entity / bool shapes. Other tools from Blink v0.17.1.
+
+| Tool | `array<entity>[100]` | `array<bool>[1000]` |
+|:---|:---|:---|
+| roblox | 16 fps · 559,364 Kbps | 21 fps · 353,107 Kbps |
+| **lync** | **59 fps · 3.37 Kbps** | **61 fps · 2.45 Kbps** |
+| blink | 42 fps · 41.81 Kbps | 97 fps · 7.91 Kbps |
+| zap | 39 fps · 41.71 Kbps | 52 fps · 8.10 Kbps |
+| bytenet | 32 fps · 41.64 Kbps | 35 fps · 8.11 Kbps |
+
+### Network bandwidth — 100 fires/frame, 8 s
+
+| Workload | Naive Kbps | Optimized | Savings |
+|:---|---:|:---|---:|
+| `array<entity>[100]` random | 3,607 | `deltaArray` 3 of 100 mutated | **154** (–96%) |
+| `array<entity>[100]` reused | 3,607 | XOR baseline (identical frames) | **2.4** (–99.9%) |
+| `array<bool>[1000]` random | 762 | XOR baseline (1 bit flipped) | **20.4** (–97%) |
+| `struct(state)` random | 201 | `deltaStruct` 1 field mutated | **29.0** (–86%) |
+| `map<id, vec3>[200]` 5 keys mutated | 657 | `deltaMap` 5 keys mutated | **393** (–40%) |
+| `array<cframe>[50]` random | 4,585 | — | — |
+| `vec3` walking motion (continuous diff) | — | `deltaVec3` | **19.5** |
+| `CFrame` walking pose (pos + rot) | — | `deltaCFrame` | **41.1** |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@axpecter/lync",
-    "version": "2.2.1",
+    "version": "2.3.2",
     "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security",
     "main": "src/init.luau",
     "types": "src/index.d.ts",

package/src/Types.luau

@@ -12,26 +12,26 @@ export type ChannelState = {
     itemCount: number,
     singleMode: boolean,
     singlePos: number,
-    deltas: { [number]: DeltaCacheEntry },
+    --[[
+        Per-codec write-side delta state, keyed by deltaId. Shape is opaque
+        and codec-internal: deltaStruct stores `{raw, len, segOff, segLen}`,
+        deltaArray stores `{perIdx, length}`, deltaMap stores `{perKey}`,
+        delta scalars store quantized previous values.
+    ]]
+    deltas: { [number]: any },
     prevDump: buffer?,
     prevDumpLen: number,
     currentPacket: string?,
 }
 
-export type DeltaCacheEntry = {
-    raw: buffer,
-    len: number,
-}
-
 export type Codec<T> = {
     write: (ch: ChannelState, value: T) -> (),
     read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
 }
 
 --[[
-    InternalCodec carries optional metadata used by Gate (validation),
-    Reader (max-item bound), Auto (type dispatch), and composite codecs
-    (direct write/read fast path).
+    Optional metadata used by Gate (validation), Reader (max-item bound),
+    Auto (type dispatch), and composite codecs (direct write/read fast path).
 ]]
 export type InternalCodec<T> = {
     write: (ch: ChannelState, value: T) -> (),
@@ -40,32 +40,38 @@ export type InternalCodec<T> = {
     _directWrite: ((b: buffer, offset: number, value: T) -> ())?,
     _directRead: ((b: buffer, offset: number) -> T)?,
     _isDelta: boolean?,
+    --[[
+        True if any nested codec is delta. Lets the broadcast hot path skip
+        encode-once when delta state would diverge per-receiver.
+    ]]
+    _hasDelta: boolean?,
     _isBool: boolean?,
     _hasUnknown: boolean?,
     _min: number?,
     _max: number?,
     _isInteger: boolean?,
-    _schema: { [string]: InternalCodec<any> }?,
+    _schema: { [string]: InternalCodec<T> }?,
     _typeCheck: string?,
     --[[
-        Composite-codec metadata. Gate uses these to recurse element /
-        variant validation rather than fall through to a generic NaN scan.
+        Composite metadata: lets Gate recurse element/variant validation
+        instead of falling through to the generic NaN/inf scan.
     ]]
     _isOptional: boolean?,
-    _inner: InternalCodec<any>?,
+    _inner: InternalCodec<T>?,
     _isTagged: boolean?,
-    _variants: { [string]: InternalCodec<any> }?,
+    _variants: { [string]: InternalCodec<T> }?,
     _tagField: string?,
     _isArray: boolean?,
-    _element: InternalCodec<any>?,
+    _element: InternalCodec<T>?,
     _maxCount: number?,
     _isMap: boolean?,
-    _keyCodec: InternalCodec<any>?,
-    _valueCodec: InternalCodec<any>?,
+    _keyCodec: InternalCodec<T>?,
+    _valueCodec: InternalCodec<T>?,
     _isTuple: boolean?,
-    _elements: { InternalCodec<any> }?,
+    _elements: { InternalCodec<T> }?,
     _isEnum: boolean?,
     _enumValues: { [string]: number }?,
+    _maxStringLength: number?,
 }
 
 export type RateLimitState = {
@@ -76,7 +82,7 @@ export type RateLimitState = {
 
 --[[
     Token-bucket (maxPerSecond + optional burst) or cooldown (cooldown
-    seconds between accepts). Mixing both forms is undefined.
+    seconds between accepts). Mixing both forms is undefined behavior.
 ]]
 export type RateLimitConfig = {
     maxPerSecond: number?,
@@ -84,6 +90,10 @@ export type RateLimitConfig = {
     cooldown: number?,
 }
 
+--[[
+    User-supplied per-packet validator. Returns (true, nil) on accept;
+    (false, reason) on reject — the reason is forwarded to onDrop hooks.
+]]
 export type ValidateFn = (data: any, player: Player) -> (boolean, string?)
 
 export type PacketOptions = {
@@ -106,6 +116,7 @@ export type Registration = {
     kind: number,
     codec: InternalCodec<any>,
     isUnreliable: boolean,
+    -- Response registration id; set on REQUEST regs only.
     partner: number?,
     signal: SignalLike,
     rateLimit: RateLimitConfig?,
@@ -160,9 +171,10 @@ export type PlayerStats = {
 }
 
 --[[
-    Server keys baselines per Player; client uses `false` since booleans
-    are valid table keys but Players never collide with that.
+    Server keys baselines per Player; client uses `false` since booleans are
+    valid table keys but Players never collide with that.
 ]]
 export type BaselineKey = Player | false
 
-return nil
+-- Type-only module: runtime table is empty so re-requires are cheap.
+return table.freeze({})