@axpecter/lync 2.3.3 → 3.0.0

package/README.md

@@ -1,381 +1,384 @@
 <h1 align="center">Lync</h1>
-<p align="center">Buffer networking for Roblox.</p>
-<p align="center">
-  <a href="https://github.com/Axp3cter/Lync/releases/latest">Releases</a> ·
-  <a href="#install">Install</a> ·
-  <a href="#example">Example</a> ·
-  <a href="#api">API</a> ·
-  <a href="#codecs">Codecs</a> ·
-  <a href="#benchmarks">Benchmarks</a>
-</p>
-
-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
+<p align="center">Typed buffer networking for Roblox: packets, queries, and replicated sets.</p>
 
-Wally — add to your `wally.toml`:
+Write the schema once. Both sides require it, the Luau types fall out of it, and every value packs
+into bit level buffers that batch into one frame per client on flush.
 
-```toml
-Lync = "axp3cter/lync@2.3.3"
-```
+```lua
+-- Net.luau, required by both sides
+return Lync.define("arena", {
+    Fighters = Lync.replicate(Lync.struct({
+        name  = Lync.str(1, 20),
+        team  = Lync.enum({ "red", "blue" }),
+        score = Lync.int(0, 1000000):monotonic(),
+        pos   = Lync.vec3(Lync.quant(-512, 512, 0.1)):newest(10),
+    })):keyBy("team"),
 
-npm (roblox-ts):
+    Strike = Lync.packet(Lync.vec3(Lync.quant(-512, 512, 0.1))):unreliable(),
 
-```bash
-npm install @axpecter/lync
+    Sell = Lync.query(
+        Lync.struct({ item = Lync.enum({ "sword", "shield" }) }),
+        Lync.struct({ earned = Lync.int(0, 1000000) })
+    ),
+})
 ```
 
-```typescript
-import Lync from "@axpecter/lync";
+```lua
+-- server
+Net.Strike:onServer(function(at, player) end)
+Net.Sell:onServer(function(order, player) return { earned = 25 } end)
+Net.Fighters:add(player.UserId, { name = "Ada", team = "red", score = 0, pos = Vector3.zero })
+
+Lync.start()
+RunService.PostSimulation:Connect(Lync.flush)
 ```
 
-**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.
+```lua
+-- client
+Net.Fighters:onChanged(function(id, record, old) board(id, record.score) end)
 
-## Example
+Lync.start()
+RunService.PostSimulation:Connect(Lync.flush)
 
-**Shared** — `ReplicatedStorage.Net`
+Net.Strike:fireServer(aim())
+local ok, receipt = Net.Sell:request({ item = "sword" })
+```
 
-```luau
-local Lync = require(game.ReplicatedStorage.Lync)
+`record.score` is a `number` and `receipt.earned` is a `number`. Nothing was annotated and nothing
+was generated.
 
-return table.freeze({
-    State = Lync.packet("State", Lync.deltaStruct({
-        position = Lync.vec3,
-        health   = Lync.float(0, 100, 0.5),
-        status   = Lync.enum("idle", "moving", "attacking", "dead"),
-        alive    = Lync.bool,
-    })),
+---
 
-    Hit = Lync.packet("Hit", Lync.struct({
-        targetId = Lync.int(0, 65535),
-        damage   = Lync.float(0, 200, 0.1),
-    }), {
-        rateLimit = { maxPerSecond = 30, burst = 5 },
-        validate  = function(data) return data.damage <= 200, "damage" end,
-    }),
+## Install
 
-    Ping = Lync.query("Ping", Lync.nothing, Lync.f64, { timeout = 3 }),
-})
+```toml
+[dependencies]
+Lync = "axp3cter/lync@3.0.0"
 ```
 
-**Server**
+```bash
+npm install @axpecter/lync
+```
 
-```luau
-local Lync    = require(game.ReplicatedStorage.Lync)
-local Net     = require(game.ReplicatedStorage.Net)
-local Players = game:GetService("Players")
+Or drop `lync.rbxm` from the latest release into `ReplicatedStorage`.
 
-local alive = Lync.group("alive")
-Players.PlayerAdded:Connect(function(p) alive:add(p) end)
+---
 
-Net.Hit:on(function(data, sender) end)
-Net.Ping:handle(function() return os.clock() end)
+## Primitives
 
-Lync.start()
+| | Carries | Send | Receive |
+| --- | --- | --- | --- |
+| `packet` | events | `fireServer` `fireClient` | `onServer` `onClient` |
+| `query` | a request and its reply | `request` | `onServer` `onClient` |
+| `replicate` | server owned records | `add` `update` `remove` `clear` | `onAdded` `onChanged` `onRemoved` |
 
-game:GetService("RunService").Heartbeat:Connect(function()
-    Net.State:send(getState(), alive)
-end)
+---
+
+## Codecs
+
+A codec says how one value validates, encodes and decodes. Out of range throws on the way out and
+drops on the way in.
+
+```lua
+local Health = Lync.int(0, 100)   -- 7 bits on the wire, where an f32 is 32
 ```
 
-**Client**
+### Numbers
 
-```luau
-local Lync = require(game.ReplicatedStorage.Lync)
-local Net  = require(game.ReplicatedStorage.Net)
+| | Type | |
+| --- | --- | --- |
+| `int(min, max)` | `number` | A bounded whole number. |
+| `quant(min, max, step)` | `number` | Rounds onto a grid. |
+| `angle(degrees)` | `number` | Cyclic, wrapping at a whole turn. |
+| `f32()` `f64()` | `number` | Roughly 7 and 15 digits. Reach for `quant` to pick the loss yourself. |
+| `vlq()` `vli()` | `number` | Unbounded integers exact to 2^53, unsigned and signed. |
+| `bool()` | `boolean` | One flag. Reach for `bitfield` past one. |
+
+### Text
+
+| | Type | |
+| --- | --- | --- |
+| `str(min, max)` | `string` | Byte length bounded. |
+| `str.alphabet(symbols, min, max)` | `string` | Every character from the set. Smaller set, fewer bits. |
+| `str.alphanum` `.base32` `.base64` `.digits` `.hex` | `string` | Presets over `alphabet`, each `(min, max)`. |
+| `buffer(min, max)` | `buffer` | Opaque bytes. Also how you relay bytes you never open. |
+
+### Roblox
+
+| | Type | |
+| --- | --- | --- |
+| `vec2(c?)` `vec3(c?)` | `Vector2` `Vector3` | `f32` per component, or hand each one a codec. |
+| `vec3.unit(degrees)` | `Vector3` | A direction. Any nonzero vector normalizes at encode. |
+| `vec3.bounded(max, step)` | `Vector3` | A direction plus a quantized magnitude. |
+| `cframe(position, rotation)` | `CFrame` | A position codec paired with a rotation codec. |
+| `rotation.none()` `.axis()` `.direction()` `.quat()` | `CFrame` | Zero, one, two, or three degrees of freedom. |
+| `color3()` `.rgb565()` `.palette(t)` | `Color3` | Floats, one 16 bit word, or an index into `t`. |
+| `inst(class?)` | `Instance?` | Always optional. A receiver that cannot see it gets nil. |
+
+UDim2, Region3, Ray and the rest go over with `:as`.
 
-Lync.start()
+### Composites
 
-local scope = Lync.scope()
-scope:on(Net.State, function(state) end)
+| | Type | |
+| --- | --- | --- |
+| `struct({ k = c })` | `{ k: ... }` | Named fields. An undeclared field throws on encode. |
+| `array(c, min, max)` | `{ T }` | An ordered list, count bounded. |
+| `map(k, v, min, max)` | `{ [K]: V }` | A dictionary, bounded the same way. |
+| `optional(c)` | `T?` | May be absent. |
+| `tagged(field, { k = c })` | union | One struct per variant, the chosen name rides in `field`. |
+| `enum({ "a", "b" })` | `string` | One of a fixed set. |
+| `bitfield({ "a", "b" })` | `{ a: boolean }` | Packed flags, one bit each. |
 
-Net.Hit:send({ targetId = 123, damage = 45 })
-local serverTime = Net.Ping:request(nil)
-```
+### Modifiers
 
-## API
-
-### Lifecycle
-
-| Function | Description |
-|:---|:---|
-| `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 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 | 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. |
-| `stats` | `false` | — | Enables `:stats()` and `Lync.stats.player()`. |
-
-### Packets
-
-`Lync.packet(name, codec, options?)`
-
-```luau
--- Server
-packet:send(data, player)
-packet:send(data, Lync.all)
-packet:send(data, Lync.except(p1, group1))
-packet:send(data, { p1, p2, p3 })
-packet:send(data, group)
-
--- Client
-packet:send(data)
-
--- Both sides
-local conn = packet:on(function(data, sender, timestamp) end)
-packet:once(fn)
-local data, sender, timestamp = packet:wait()
-packet:name()
-packet:stats() -- requires stats=true
+| | Scope | |
+| --- | --- | --- |
+| `:validate(fn)` | any | `fn(value, ctx)` returns nil to pass or a reason to drop. |
+| `:as(to, from)` | any | Maps the wire type to and from your own. |
+| `:monotonic()` | set fields | Only climbs, so deltas cost less. A decrease throws. |
+| `:newest(hz?)` | set fields | Only the latest matters, and `hz` caps the rate. |
+
+A modifier answers a new codec. A set marker inside a packet or query throws at start.
+
+---
+
+## Packets
+
+```lua
+Move = Lync.packet(Lync.vec3()):unreliable(),
+Aim  = Lync.packet(Lync.rotation.quat(0.2)):newest(20):timestamped(),
 ```
 
-| Option | Type | Description |
-|:---|:---|:---|
-| `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. |
+| | | |
+| --- | --- | --- |
+| server | `fireClient(to, payload)` | Encodes once however many receive it. |
+| server | `onServer(fn)` | `fn(payload, player, sent?)`. Any number of listeners. |
+| client | `fireServer(payload)` | |
+| client | `onClient(fn)` | `fn(payload, sent?)`. Any number of listeners. |
 
-### Queries
+Delivery is reliable and ordered by default. The first two below are alternatives, and
+`:timestamped()` stacks with either.
 
-`Lync.query(name, requestCodec, responseCodec, options?)`
+| | |
+| --- | --- |
+| `:unreliable()` | Lossy and unordered, and every fire still goes out. Must fit the unreliable cap. |
+| `:newest(hz?)` | Lossy, latest wins. Stale arrivals and unchanged values send nothing. |
+| `:timestamped()` | Adds `sent`, an instant on the shared clock. |
+
+`to`, and a set's `audience`, take any of these.
 
-Request-response on top of two paired registrations. Single-target requests yield until reply or timeout; multi-target requests gather a partial map.
+| | |
+| --- | --- |
+| `Lync.all` | Every client. |
+| `Player` | That client. |
+| `{ Player }` | The listed clients. |
+| `Group` | Its members at send time. |
+| `Lync.except(t)` | Everyone but `t`, a player, list, or group. |
 
-```luau
--- Server
-query:handle(function(data, player) return response end)
-local resp = query:request(data, player)        -- response?
-local map  = query:request(data, group)         -- { [Player]: response? }
+Firing at nobody is reported and throws in Studio. Listeners may yield, and one that throws does
+not stop the others.
 
--- Client
-query:handle(function(data) return response end)
-local resp = query:request(data)                -- yields; nil on timeout
+---
+
+## Queries
+
+```lua
+local ok, res, data = Net.Sell:request({ item = "sword" })
+if ok then print(res.earned) else print(res, data.elapsed) end
 ```
 
-| Option | Default | Description |
-|:---|:---|:---|
-| `timeout` | 5 | Seconds before yielding `nil`. |
-| `rateLimit` | `{ maxPerSecond = 30 }` | Server-side. |
-| `validate` | none | `(data, player) → (bool, string?)` |
+No ending raises. A reply, a deadline, and a counterparty that never answered all arrive the same
+way.
+
+| | | |
+| --- | --- | --- |
+| client | `request(value, timeout?)` | Yields for the reply. Timeout defaults to 10 s. |
+| server | `request(client, value, fn, timeout?)` | `fn(ok, res, data)` on completion. Never yields. |
+| server | `onServer(fn)` | The lone responder. What it returns is the reply. |
+| client | `onClient(fn)` | The lone responder. |
 
-### Groups
+Four outcomes: `timeout`, `unanswered` when the other side registered none, `leave` when the
+counterparty goes, and `shutdown` when `close` runs first. A domain failure like insufficient funds
+is a value in your response codec, not an outcome.
 
-`Lync.group(name)` — named player set. Members auto-removed on `PlayerRemoving`. Iterable: `for player in group do`.
+---
 
-| Method | Returns | Description |
-|:---|:---|:---|
-| `:add(p)` / `:remove(p)` | `boolean` | `true` if membership changed. |
-| `:has(p)` | `boolean` | |
-| `:count()` | `number` | |
-| `:destroy()` | — | Clear members and free the name. |
+## Sets
 
-### Scope
+```lua
+Net.Fighters:add(id, { name = "Ada", team = "red", score = 0, pos = Vector3.zero })
+Net.Fighters:update(id, { score = 10 })   -- only score is sent
+```
 
-`Lync.scope()` — batches connections for a single `:destroy()`.
+The server owns the set and each client holds exactly the records its audiences allow. Without
+`keyBy` the whole set goes to everyone. `keyBy(field)` splits records by that field's value, and
+`audience(key, to)` gives each key its viewers.
 
-```luau
-local scope = Lync.scope()
-scope:on(packet, fn)
-scope:once(packet, fn)
-scope:add(rbxConnection)
-scope:destroy()
+```lua
+Net.Fighters:audience("red", redTeam)
+Net.Fighters:update(id, { team = "blue" })   -- migrates atomically inside this flush
+-- viewers of "red" alone   -> onRemoved(id, "removed")
+-- viewers of "blue" alone  -> onAdded(id, record)
+-- viewers of both keys     -> onChanged(id, record, old)
 ```
 
-### Targets
+| Server | |
+| --- | --- |
+| `add(id, record)` | Throws if the id is live. |
+| `update(id, fields)` | Only the named fields. `Lync.none` clears an optional one. |
+| `remove(id)` `clear()` | Throws on an absent id. |
+| `audience(key, to)` | Keyed sets only. |
 
-Server-side `:send` second arg.
+| Both sides | |
+| --- | --- |
+| `get(id)` | The live record or nil. Borrowed, so copy what you keep. |
+| `#set`, iteration | Count and walk the local view. |
+| `onAdded(fn)` | `fn(id, record)` on first sight: an add, a late join, a visibility gain. |
+| `onChanged(fn)` | `fn(id, record, old)`. The net record after a flush against the one before. |
+| `onRemoved(fn)` | `fn(id, cause)` with `"removed"` or `"cleared"`. |
 
-| Target | Description |
-|:---|:---|
-| `Player` | One player. |
-| `Lync.all` | All connected. |
-| `Lync.except(...)` | Everyone except given Players or Groups. |
-| `{ p1, p2 }` | Array of players. |
-| `group` | All members. |
+Only changed fields go out, and only to viewers. Two updates in one flush ship once. An add and a
+remove in one flush ship nothing. Ids are exact to 2^53, so UserIds work as they are, Studio's
+negative test ids included.
 
-### Middleware
+---
 
-```luau
--- 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)
-```
+## Lifecycle
 
-All return a `Connection`. A throwing hook surfaces to the caller and aborts the chain at that point.
+| | |
+| --- | --- |
+| `Lync.start()` | Seals definitions and responders. Once per side, after every definition. |
+| `Lync.flush()` | Sends everything buffered. Nothing sends without it, and empty flushes are free. |
+| `Lync.close()` | A final flush, resolves outstanding requests as `shutdown`, releases the transports. |
+| `Lync.stats(name)` | A frozen snapshot of a namespace's counters. Monotonic, so two diff into rates. |
+
+```lua
+Lync.flush(8192)            -- every namespace, 8 KB of state per client
+Lync.flush("arena", 8192)   -- one namespace, on its own cadence
+```
 
-### Connection
+The budget throttles state replication only, so packets, requests and responses always send in
+full. Under 1024 throws. Give latency critical traffic its own namespace.
 
 | | |
-|:---|:---|
-| `c.connected` | `boolean` |
-| `c:disconnect()` | Idempotent. |
+| --- | --- |
+| `Lync.group()` | A mutable membership set that goes anywhere a recipient does. |
+| `add` `remove` `has` | Manage membership. `#group` and iteration cover the set. |
+| `destroy()` | Empties it and releases it. Any later use throws. |
 
-### Stats
+A group thins out as players leave, and audiences store the group itself.
 
-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 }`. Aggregated across the request + response registrations on queries. |
+## Validation
 
-### Debug
+Inbound checking has two stages, and a rejection at the first is a drop.
 
-| Function | Description |
-|:---|:---|
-| `Lync.debug.pending()` | In-flight query correlation IDs. |
-| `Lync.debug.registrations()` | Frozen `{ name, id, kind, isUnreliable }` per registration. |
+```lua
+Damage = Lync.int(0, 500):validate(function(amount, ctx)
+    -- ctx.player, ctx.now, ctx.last
+    if ctx.last ~= nil and ctx.now - ctx.last < 0.1 then return "faster than 10 Hz" end
+    return nil
+end)
+```
 
-`capture` / `stop` / `dump` are reserved no-ops for capture/replay tooling.
+`last` is stamped on every arrival, accepted or not, so a flood of junk cannot reset a sender's
+clock. The table is reused, so copy anything you keep. A rejected payload is dropped before your
+code sees it and logged as one warning. A rejected request is answered by nothing, so the requester
+times out.
 
-## Codecs
+---
 
-### Numbers
+## Errors and logging
 
-| Codec | Bytes | Notes |
-|:---|---:|:---|
-| `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
-
-| Codec | Notes |
-|:---|:---|
-| `string` | Variable length. Binary-safe. |
-| `string(maxLength)` | Bounded. Rejects on read if exceeded. |
-| `buff` | Variable-length raw `buffer`. |
-
-### Roblox types
-
-| Codec | Bytes |
-|:---|---:|
-| `vec2` / `vec3` | 8 / 12 |
-| `cframe` | 24 |
-| `color3` | 3 |
-| `inst` | 2 (sidecar ref index) |
-| `udim` / `udim2` | 8 / 16 |
-| `numberRange` | 8 |
-| `rect` | 16 |
-| `ray` | 24 |
-| `vec2int16` / `vec3int16` | 4 / 6 |
-| `region3` / `region3int16` | 24 / 12 |
-| `numberSequence` / `colorSequence` | variable |
-
-### Quantized variants
-
-Call as a function for compression.
-
-| Codec | Bytes | Notes |
-|:---|---:|:---|
-| `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. |
+| | |
+| --- | --- |
+| Programmer error | A call on the wrong side, a second responder, a second `start`. Throws on the spot. |
+| Dropped input | A validate reason, a payload the schema turns away. A warning, never thrown. |
+| Environmental | A listener or responder that throws. Reported with its trace, and never stalls the rest. |
+| Transport | Timeout, a leaver, shutdown. An outcome code handed back, never thrown. |
+
+Every `on*` returns a connection with `:disconnect()`. When a player leaves, each pending request
+touching them resolves as `leave`.
+
+```lua
+Lync.onLog(function(kind, message, data)
+    if data.player ~= nil then flagSuspicious(data.player, data) end
+end)
+```
 
-### Composites
+`kind` is `warn` for something dropped, `error` for a fault contained, or `debug` in Studio only.
+`data` always carries a file and a line. `Lync.console` is the default printer and is itself a
+connection, so disconnect it to format records yourself. Match on `data`, never on the message.
 
-| Codec | Notes |
-|:---|:---|
-| `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
+## Types
 
-Tracks the previous frame's value and ships only what changed. Rejected on `unreliable = true`.
+Handlers, records and replies come out typed from the schema alone.
 
-| 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 |
+```lua
+type Fighter = Types.Infer<typeof(Codec)>   -- { name: string, score: number, tag: string? }
+```
 
-- `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.
+`Infer` reads a codec, `Schema` reads a table of codecs as the record it describes, and `Update`
+types the argument to a set update. All three live in the `Types` module beside `Lync`. Everything
+else is on `Lync` directly, for signatures at module boundaries.
+
+```lua
+local codec: Lync.Codec<number>
+local packet: Lync.Packet<Vector3>
+local query: Lync.Query<Order, Receipt>
+local set: Lync.Set<Fighter>
+local group: Lync.Group
+local conn: Lync.Connection
+local to: Lync.Recipient           -- Lync.All | Player | { Player } | Group | Lync.Except
+local kind: Lync.LogKind           -- "warn" | "error" | "debug"
+local cause: Lync.Cause            -- "removed" | "cleared"
+local code: Lync.OutcomeCode       -- "timeout" | "unanswered" | "leave" | "shutdown"
+local ctx: Lync.ValidateContext    -- player, now, last
+local log: Lync.LogData            -- file, line, player?, definition?
+local why: Lync.OutcomeData        -- definition, elapsed?
+local done: Lync.Outcome<Receipt>  -- a server request's completion callback
+local snap: Lync.Stats             -- flushes, sentBytes, receivedBytes, drops, definitions
+local row: Lync.DefinitionStats    -- one definition's line in that snapshot
+local clear: Lync.None             -- the type of Lync.none
+```
 
-### Meta
+### roblox-ts
 
-| Codec | Notes |
-|:---|:---|
-| `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. |
+The same surface, with five differences.
 
-## Rate limiting
+| | Luau | roblox-ts |
+| --- | --- | --- |
+| calls | `set:add(id, r)` | `set.add(id, r)` |
+| count | `#set` | `set.size()` |
+| helpers | `Types.Infer<C>` | `Lync.Infer<C>` |
+| instance class | `Lync.inst("Player")` | `Lync.inst<Player>()` |
+| audience key | untyped | typed, so `audience` before `keyBy` is a compile error |
 
-Per-packet, pick one mode:
+The package is scoped, so add both roots in `tsconfig.json` and both folders in your project file.
 
-- Token bucket: `{ maxPerSecond = N, burst = M }`
-- Cooldown: `{ cooldown = seconds }`
+```json
+"typeRoots": ["node_modules/@rbxts", "node_modules/@axpecter"]
+```
 
-Global per-player cap: `Lync.configure({ globalRateLimit = { maxPerSecond = N } })`.
+---
 
 ## Limits
 
-| | |
-|:---|---:|
-| Packet + query IDs (combined) | 127 |
-| Buffer per frame | 1 MB max |
-| 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.
-
-### Cross-library — 1000 fires/frame, 10 s
-
-[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** |
+| | | |
+| --- | --- | --- |
+| set fields | 64 | Nest the extras in a `struct`, which counts as one field. |
+| ids and integers | exact to 2^53 | Past it, carry the value as a `str` or a `buffer`. |
+| request timeout | 10 s | Pass a timeout per call. |
+| in flight requests | 32768 per namespace | You are leaking requests, and the cap is a detector. |
+| state budget | 32 KB/s per client | Raise it with a flush budget, or split the traffic. |
+| unreliable schema | just under 1 KB | Drop `:unreliable()`, or narrow the codec. Checked at start. |
+| one frame | 1 MB | A loop that fires and never flushes. The throw names the size. |
+
+---
 
 ## License