@axpecter/lync 2.2.1 → 2.3.2

package/src/codec/meta/DeltaScalar.luau

@@ -0,0 +1,390 @@
+--!strict
+--!native
+-- Delta scalars: zigzag-varint diff against previous frame for ints, floats, vec3, CFrame.
+
+local Base = require(script.Parent.Parent.Base)
+local Baseline = require(script.Parent.Parent.Parent.internal.Baseline)
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Quantize = require(script.Parent.Parent.Parent.util.Quantize)
+local Quat = require(script.Parent.Parent.Parent.util.Quat)
+local Shared = require(script.Parent.Parent.composite.Shared)
+local Types = require(script.Parent.Parent.Parent.Types)
+local Varint = require(script.Parent.Parent.primitive.Varint)
+local Zint = require(script.Parent.Parent.primitive.Zint)
+
+-- Constants --------------------------------------------------------------
+
+local I32_MIN = -0x80000000
+local I32_MAX = 0x7FFFFFFF
+
+-- deltaCFrame header bits: which components changed since the last frame.
+local CF_X = 0x01
+local CF_Y = 0x02
+local CF_Z = 0x04
+local CF_ROT = 0x08
+local CF_ALL = 0x0F
+
+-- Private ----------------------------------------------------------------
+
+local ensure = Base.ensure
+local allocDeltaId = Shared.allocDeltaId
+local floor = math.floor
+local clamp = math.clamp
+local round = math.round
+local band = bit32.band
+local bor = bit32.bor
+local readu8 = buffer.readu8
+local writeu8 = buffer.writeu8
+local readu32 = buffer.readu32
+local writeu32 = buffer.writeu32
+local bufLen = buffer.len
+local varintWrite = Varint.write
+local varintRead = Varint.read
+local zigzagEncode = Zint.encode
+local zigzagDecode = Zint.decode
+local quatPack = Quat.pack
+local quatUnpack = Quat.unpack
+local quatFromCFrame = Quat.fromCFrame
+
+local function quantizeVec3(
+    v: Vector3,
+    min: number,
+    delta: number,
+    scale: number
+): (number, number, number)
+    return round(clamp(v.X - min, 0, delta) * scale),
+        round(clamp(v.Y - min, 0, delta) * scale),
+        round(clamp(v.Z - min, 0, delta) * scale)
+end
+
+-- Reject out-of-range components rather than silently snapping via clamp().
+local function validateVec3(v: Vector3, min: number, max: number, label: string): ()
+    if v.X < min or v.X > max or v.Y < min or v.Y > max or v.Z < min or v.Z > max then
+        Log.error(`{label} ({v.X}, {v.Y}, {v.Z}) has component out of range [{min}, {max}]`)
+    end
+end
+
+local function getScalarPrev(ch: Types.ChannelState, id: number, fallback: number): number
+    local cache = ch.deltas[id] :: any
+    return if cache then cache.scalar :: number else fallback
+end
+
+local function setScalarCache(ch: Types.ChannelState, id: number, value: number): ()
+    local cache = ch.deltas[id] :: any
+    if cache then
+        cache.scalar = value
+    else
+        ch.deltas[id] = { scalar = value } :: any
+    end
+end
+
+-- Public -----------------------------------------------------------------
+
+local DeltaScalar = {}
+
+--[[
+    Variable-length integer that emits zigzag varint of (current - previous).
+    First frame uses `min` as the implicit prev so the initial value encodes
+    as (value - min). Reliable transport only — a dropped frame desyncs prev.
+
+    Wire: 1 byte for unchanged or [-96, 95] mutations; up to 5 bytes for full i32.
+]]
+function DeltaScalar.deltaInt(min: number, max: number): Types.InternalCodec<number>
+    if min > max then
+        Log.error(`min ({min}) must be <= max ({max})`)
+    end
+    if floor(min) ~= min or floor(max) ~= max then
+        Log.error("bounds must be integers")
+    end
+    if max - min > I32_MAX then
+        Log.error(`range too wide; (max - min) must fit in i32, got {max - min}`)
+    end
+
+    local deltaId = allocDeltaId()
+
+    return table.freeze({
+        _isDelta = true,
+        _typeCheck = "number",
+        _isInteger = true,
+        _min = min,
+        _max = max,
+
+        write = function(ch: Types.ChannelState, value: number): ()
+            if value < min or value > max then
+                Log.error(`value {value} out of range [{min}, {max}]`)
+            end
+            if floor(value) ~= value then
+                Log.error(`value {value} must be an integer`)
+            end
+            varintWrite(ch, zigzagEncode(value - getScalarPrev(ch, deltaId, min)))
+            setScalarCache(ch, deltaId, value)
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (number, number)
+            local raw, consumed = varintRead(src, pos)
+            if consumed == 0 then
+                Log.error("truncated deltaInt")
+            end
+            local cached = Baseline.getCache(deltaId)
+            local value = (if cached ~= nil then cached :: number else min) + zigzagDecode(raw)
+            if value < min or value > max then
+                Log.error(`deltaInt decoded value {value} out of range [{min}, {max}]`)
+            end
+            Baseline.setCache(deltaId, value)
+            return value, consumed
+        end,
+    }) :: Types.InternalCodec<number>
+end
+
+--[[
+    Quantized float with diffs in integer wire space (post-quantize). Storing
+    the quantized representative — not the float — across frames means
+    accumulating diffs over thousands of frames cannot drift past the grid.
+]]
+function DeltaScalar.deltaFloat(
+    min: number,
+    max: number,
+    precision: number
+): Types.InternalCodec<number>
+    if max - min == 0 then
+        return Base.constant(min)
+    end
+
+    local _, _, _, scale, invScale, delta = Quantize.setup("Lync.deltaFloat", min, max, precision)
+    local deltaId = allocDeltaId()
+
+    return table.freeze({
+        _isDelta = true,
+        _typeCheck = "number",
+        _min = min,
+        _max = max,
+
+        write = function(ch: Types.ChannelState, value: number): ()
+            local q = round(clamp(value - min, 0, delta) * scale)
+            varintWrite(ch, zigzagEncode(q - getScalarPrev(ch, deltaId, 0)))
+            setScalarCache(ch, deltaId, q)
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (number, number)
+            local raw, consumed = varintRead(src, pos)
+            if consumed == 0 then
+                Log.error("truncated deltaFloat")
+            end
+            local cached = Baseline.getCache(deltaId)
+            local q = (if cached ~= nil then cached :: number else 0) + zigzagDecode(raw)
+            Baseline.setCache(deltaId, q)
+            return q * invScale + min, consumed
+        end,
+    }) :: Types.InternalCodec<number>
+end
+
+--[[
+    Quantized Vector3 with per-axis zigzag varint diffs. Static value: 3 bytes
+    (three zero zigzags); typical < 1 stud motion at 0.01-stud precision: 3-6
+    bytes. Baseline vec3 = 12 bytes, so 4x reduction at the static end.
+]]
+function DeltaScalar.deltaVec3(
+    min: number,
+    max: number,
+    precision: number
+): Types.InternalCodec<Vector3>
+    if max - min == 0 then
+        return Base.constant(Vector3.new(min, min, min)) :: Types.InternalCodec<Vector3>
+    end
+
+    local _, _, _, scale, invScale, delta = Quantize.setup("Lync.deltaVec3", min, max, precision)
+    local deltaId = allocDeltaId()
+
+    return table.freeze({
+        _isDelta = true,
+        _typeCheck = "Vector3",
+        _min = min,
+        _max = max,
+
+        write = function(ch: Types.ChannelState, value: Vector3): ()
+            validateVec3(value, min, max, "Vector3")
+            local qx, qy, qz = quantizeVec3(value, min, delta, scale)
+            local cache = ch.deltas[deltaId] :: any
+            local px, py, pz = 0, 0, 0
+            if cache then
+                px, py, pz = cache.qx :: number, cache.qy :: number, cache.qz :: number
+            end
+
+            varintWrite(ch, zigzagEncode(qx - px))
+            varintWrite(ch, zigzagEncode(qy - py))
+            varintWrite(ch, zigzagEncode(qz - pz))
+
+            if cache then
+                cache.qx, cache.qy, cache.qz = qx, qy, qz
+            else
+                ch.deltas[deltaId] = { qx = qx, qy = qy, qz = qz } :: any
+            end
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (Vector3, number)
+            local rx, cx = varintRead(src, pos)
+            if cx == 0 then
+                Log.error("truncated deltaVec3 X")
+            end
+            local ry, cy = varintRead(src, pos + cx)
+            if cy == 0 then
+                Log.error("truncated deltaVec3 Y")
+            end
+            local rz, cz = varintRead(src, pos + cx + cy)
+            if cz == 0 then
+                Log.error("truncated deltaVec3 Z")
+            end
+
+            local cached = Baseline.getCache(deltaId) :: any
+            local px, py, pz = 0, 0, 0
+            if cached then
+                px, py, pz = cached.qx, cached.qy, cached.qz
+            end
+            local qx = px + zigzagDecode(rx)
+            local qy = py + zigzagDecode(ry)
+            local qz = pz + zigzagDecode(rz)
+            Baseline.setCache(deltaId, { qx = qx, qy = qy, qz = qz })
+
+            return Vector3.new(qx * invScale + min, qy * invScale + min, qz * invScale + min),
+                cx + cy + cz
+        end,
+    }) :: Types.InternalCodec<Vector3>
+end
+
+--[[
+    Quantized position + smallest-three quaternion rotation. Wire layout:
+      byte 0   header bits: bit0=Δx, bit1=Δy, bit2=Δz, bit3=Δrot
+      For each set position bit: zigzag varint of quantized diff
+      If rotation bit set: 4-byte packed quat
+
+    Static CFrame: 1 byte. Pos-only motion: 1 + 3 zint bytes (~4-7).
+    Full update: 1 + 3 zint + 4 quat (~8-13). Baseline lossless: 24 bytes.
+]]
+function DeltaScalar.deltaCFrame(
+    posMin: number,
+    posMax: number,
+    posPrecision: number
+): Types.InternalCodec<CFrame>
+    -- Quantize.setup itself rejects min == max; the redundant guard is gone.
+    local _, _, _, scale, invScale, delta =
+        Quantize.setup("Lync.deltaCFrame", posMin, posMax, posPrecision)
+    local deltaId = allocDeltaId()
+
+    return table.freeze({
+        _isDelta = true,
+        _typeCheck = "CFrame",
+
+        write = function(ch: Types.ChannelState, value: CFrame): ()
+            local pos = value.Position
+            validateVec3(pos, posMin, posMax, "CFrame position")
+            local qx, qy, qz = quantizeVec3(pos, posMin, delta, scale)
+            local packed = quatPack(quatFromCFrame(value))
+
+            -- prev = 0 so the first frame writes absolute values; receiver also defaults to 0.
+            local cache = ch.deltas[deltaId] :: any
+            local flag: number
+            local px, py, pz = 0, 0, 0
+            if cache then
+                px = cache.qx :: number
+                py = cache.qy :: number
+                pz = cache.qz :: number
+                local ppacked = cache.qrot :: number
+                flag = 0
+                if qx ~= px then
+                    flag = bor(flag, CF_X)
+                end
+                if qy ~= py then
+                    flag = bor(flag, CF_Y)
+                end
+                if qz ~= pz then
+                    flag = bor(flag, CF_Z)
+                end
+                if packed ~= ppacked then
+                    flag = bor(flag, CF_ROT)
+                end
+            else
+                -- First frame: emit everything so the receiver has a baseline.
+                flag = CF_ALL
+            end
+
+            ensure(ch, 1)
+            writeu8(ch.buff, ch.cursor, flag)
+            ch.cursor += 1
+
+            if band(flag, CF_X) ~= 0 then
+                varintWrite(ch, zigzagEncode(qx - px))
+            end
+            if band(flag, CF_Y) ~= 0 then
+                varintWrite(ch, zigzagEncode(qy - py))
+            end
+            if band(flag, CF_Z) ~= 0 then
+                varintWrite(ch, zigzagEncode(qz - pz))
+            end
+            if band(flag, CF_ROT) ~= 0 then
+                ensure(ch, 4)
+                writeu32(ch.buff, ch.cursor, packed)
+                ch.cursor += 4
+            end
+
+            if cache then
+                cache.qx, cache.qy, cache.qz, cache.qrot = qx, qy, qz, packed
+            else
+                ch.deltas[deltaId] = { qx = qx, qy = qy, qz = qz, qrot = packed } :: any
+            end
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (CFrame, number)
+            if pos >= bufLen(src) then
+                Log.error("truncated deltaCFrame header")
+            end
+            local flag = readu8(src, pos)
+            local total = 1
+
+            local cached = Baseline.getCache(deltaId) :: any
+            local qx, qy, qz, packed = 0, 0, 0, 0
+            if cached then
+                qx, qy, qz, packed = cached.qx, cached.qy, cached.qz, cached.qrot
+            end
+
+            if band(flag, CF_X) ~= 0 then
+                local r, c = varintRead(src, pos + total)
+                if c == 0 then
+                    Log.error("truncated deltaCFrame X")
+                end
+                qx += zigzagDecode(r)
+                total += c
+            end
+            if band(flag, CF_Y) ~= 0 then
+                local r, c = varintRead(src, pos + total)
+                if c == 0 then
+                    Log.error("truncated deltaCFrame Y")
+                end
+                qy += zigzagDecode(r)
+                total += c
+            end
+            if band(flag, CF_Z) ~= 0 then
+                local r, c = varintRead(src, pos + total)
+                if c == 0 then
+                    Log.error("truncated deltaCFrame Z")
+                end
+                qz += zigzagDecode(r)
+                total += c
+            end
+            if band(flag, CF_ROT) ~= 0 then
+                if pos + total + 4 > bufLen(src) then
+                    Log.error("truncated deltaCFrame rotation")
+                end
+                packed = readu32(src, pos + total)
+                total += 4
+            end
+
+            Baseline.setCache(deltaId, { qx = qx, qy = qy, qz = qz, qrot = packed })
+
+            local position =
+                Vector3.new(qx * invScale + posMin, qy * invScale + posMin, qz * invScale + posMin)
+            return CFrame.new(position) * quatUnpack(packed), total
+        end,
+    }) :: Types.InternalCodec<CFrame>
+end
+
+return table.freeze(DeltaScalar)

package/src/codec/meta/Enum.luau

@@ -1,8 +1,9 @@
 --!strict
---!optimize 2
+--!native
 -- String-keyed enum codec. Maps values to u8 indices at definition time.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Public -----------------------------------------------------------------
@@ -12,11 +13,9 @@ local EnumCodec = {}
 function EnumCodec.define(...: string): Types.InternalCodec<string>
     local values = { ... }
     local count = #values
-    if count == 0 then
-        error("[Lync] Lync.enum: requires at least one value")
-    end
+    Log.assert(count > 0, "requires at least one variant")
     if count > 256 then
-        error("[Lync] Lync.enum: exceeds 256 variants")
+        Log.error(`exceeds 256 variants ({count})`)
     end
 
     local toIndex: { [string]: number } = {}
@@ -24,7 +23,7 @@ function EnumCodec.define(...: string): Types.InternalCodec<string>
     for i = 1, count do
         local val = values[i]
         if toIndex[val] then
-            error(`[Lync] Lync.enum: duplicate value "{val}"`)
+            Log.error(`duplicate value "{val}"`)
         end
         toIndex[val] = i - 1
         toValue[i] = val
@@ -35,13 +34,14 @@ function EnumCodec.define(...: string): Types.InternalCodec<string>
     return Base.define(1, function(b: buffer, off: number, value: string): ()
         local idx = toIndex[value]
         if idx == nil then
-            error(`[Lync] Enum.write: invalid value "{value}"`)
+            Log.error(`invalid value "{value}"`)
         end
         buffer.writeu8(b, off, idx)
     end, function(b: buffer, off: number): string
-        local val = toValue[buffer.readu8(b, off) + 1]
+        local raw = buffer.readu8(b, off)
+        local val = toValue[raw + 1]
         if val == nil then
-            error(`[Lync] Enum.read: invalid index`)
+            Log.error(`invalid index {raw}`)
         end
         return val
     end, { _typeCheck = "string", _isEnum = true, _enumValues = toIndex })

package/src/codec/meta/Float.luau

@@ -1,17 +1,15 @@
 --!strict
 --!native
--- Fixed-point quantization codec. Maps a float range to u8/u16/u32.
+-- Fixed-point float quantizer. Maps a float range to u8/u16/u32.
 
 local Base = require(script.Parent.Parent.Base)
+local Quantize = require(script.Parent.Parent.Parent.util.Quantize)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
 
-local ceil = math.ceil
 local clamp = math.clamp
 local round = math.round
-local maxN = math.max
-local minN = math.min
 
 -- Public -----------------------------------------------------------------
 
@@ -22,33 +20,13 @@ function Float.float(
     rangeMax: number,
     precision: number
 ): Types.InternalCodec<number>
-    if rangeMin > rangeMax then
-        error(`[Lync] Lync.float: min ({rangeMin}) must be <= max ({rangeMax})`)
-    end
-    if precision <= 0 then
-        error("[Lync] Lync.float: precision must be positive")
-    end
-
-    local delta = rangeMax - rangeMin
-    if delta == 0 then
+    -- Degenerate range: emit nothing, decode to the constant.
+    if rangeMax - rangeMin == 0 then
         return Base.constant(rangeMin)
     end
 
-    local maxInt = minN(0xFFFFFFFF, maxN(1, ceil(delta / precision)))
-
-    local compBytes: number
-    local wfn: (buffer, number, number) -> ()
-    local rfn: (buffer, number) -> number
-    if maxInt <= 0xFF then
-        compBytes, wfn, rfn = 1, buffer.writeu8, buffer.readu8
-    elseif maxInt <= 0xFFFF then
-        compBytes, wfn, rfn = 2, buffer.writeu16, buffer.readu16
-    else
-        compBytes, wfn, rfn = 4, buffer.writeu32, buffer.readu32
-    end
-
-    local scale = maxInt / delta
-    local invScale = delta / maxInt
+    local compBytes, wfn, rfn, scale, invScale, delta =
+        Quantize.setup("Lync.float", rangeMin, rangeMax, precision)
 
     return Base.define(compBytes, function(b: buffer, off: number, value: number): ()
         wfn(b, off, round(clamp(value - rangeMin, 0, delta) * scale))

package/src/codec/meta/Nothing.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- Zero-byte codec. Reads nil. For fire-and-forget signals.
+-- 0-byte codec. Reads nil. For fire-and-forget signals.
 
 local Base = require(script.Parent.Parent.Base)
 

package/src/codec/meta/Unknown.luau

@@ -1,8 +1,9 @@
 --!strict
---!optimize 2
--- Bypasses buffer serialization. Uses Roblox remote sidecar refs.
+--!native
+-- Bypass codec. Stashes the value in the channel sidecar refs (no schema).
 
 local Channel = require(script.Parent.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -15,20 +16,22 @@ local function writeUnknown(ch: Types.ChannelState, value: any): ()
 end
 
 local function readUnknown(src: buffer, pos: number, refs: { Instance }?): (any, number)
-    if not refs then
-        error("[Lync] Unknown.read: refs array is required")
+    local r = refs
+    if not r then
+        Log.error("refs array is required")
     end
     local idx = readu16(src, pos)
-    if idx < 1 or idx > #refs then
-        error(`[Lync] Unknown.read: ref index {idx} out of bounds`)
+    if idx < 1 or idx > #r then
+        Log.error(`ref index {idx} out of bounds`)
     end
-    return refs[idx], 2
+    return r[idx], 2
 end
 
 -- Public -----------------------------------------------------------------
 
 local Unknown = {}
 
+-- _hasUnknown propagates upward so containers warn when used without validate.
 Unknown.unknown = table.freeze({
     _hasUnknown = true,
     write = writeUnknown,

package/src/codec/primitive/Bool.luau

@@ -1,12 +1,10 @@
 --!strict
 --!optimize 2
--- Single-byte boolean codec. _isBool flag enables struct/array bit packing.
+-- 1-byte boolean codec. _isBool flag opts struct/array into bit packing.
 
 local Base = require(script.Parent.Parent.Base)
 
--- Public -----------------------------------------------------------------
-
-local Bool = {}
+-- Private ----------------------------------------------------------------
 
 local function writeBool(b: buffer, off: number, value: boolean): ()
     buffer.writeu8(b, off, if value then 1 else 0)
@@ -16,6 +14,10 @@ local function readBool(b: buffer, off: number): boolean
     return buffer.readu8(b, off) ~= 0
 end
 
+-- Public -----------------------------------------------------------------
+
+local Bool = {}
+
 Bool.bool = Base.define(1, writeBool, readBool, {
     _isBool = true,
     _typeCheck = "boolean",

package/src/codec/primitive/Float16.luau

@@ -1,6 +1,6 @@
 --!strict
 --!native
--- IEEE 754 binary16 codec. 2 bytes, +/- 65504, ~3 decimal digits of precision.
+-- IEEE 754 binary16 codec. 2 bytes, +/-65504 finite range, ~3 decimal digits.
 
 local Base = require(script.Parent.Parent.Base)
 
@@ -20,9 +20,10 @@ local frexp = math.frexp
 local ldexp = math.ldexp
 local round = math.round
 local huge = math.huge
+local isnan = math.isnan
 
 local function encode(value: number): number
-    if value ~= value then
+    if isnan(value) then
         return NAN_BITS
     end
     if value == 0 then
@@ -42,6 +43,7 @@ local function encode(value: number): number
     local mantissa, exponent = frexp(value)
     local biasedExp = exponent + 14
 
+    -- Subnormal: shift mantissa into the 10-bit fraction with the implicit bit gone.
     if biasedExp <= 0 then
         local frac = round(ldexp(mantissa, biasedExp + 10))
         if frac >= 1024 then
@@ -54,6 +56,7 @@ local function encode(value: number): number
     end
 
     local frac = round((mantissa * 2 - 1) * 1024)
+    -- Rounding can carry into the exponent; absorb it.
     if frac >= 1024 then
         frac = 0
         biasedExp += 1

package/src/codec/primitive/Int.luau

@@ -1,8 +1,9 @@
 --!strict
 --!optimize 2
--- Range-typed integer codec. Picks the narrowest u8/u16/u32/i8/i16/i32 wire form.
+-- Range-typed integer codec. Picks the narrowest u8/u16/u32/i8/i16/i32 form.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Signed = require(script.Parent.Signed)
 local Types = require(script.Parent.Parent.Parent.Types)
 
@@ -19,11 +20,9 @@ local Int = {}
 
 function Int.int(min: number, max: number): Types.InternalCodec<number>
     if min > max then
-        error(`[Lync] Lync.int: min ({min}) must be <= max ({max})`)
-    end
-    if floor(min) ~= min or floor(max) ~= max then
-        error("[Lync] Lync.int: bounds must be integers")
+        Log.error(`min ({min}) must be <= max ({max})`)
     end
+    Log.assert(floor(min) == min and floor(max) == max, "bounds must be integers")
 
     local meta = {
         _min = min,
@@ -54,7 +53,7 @@ function Int.int(min: number, max: number): Types.InternalCodec<number>
         end
     end
 
-    error(`[Lync] Lync.int: range [{min}, {max}] exceeds i32 bounds`)
+    Log.error(`range [{min}, {max}] exceeds i32 bounds`)
 end
 
 return table.freeze(Int)

package/src/codec/primitive/Number.luau

@@ -1,13 +1,15 @@
 --!strict
 --!optimize 2
--- Explicit-precision float codecs: f32 and f64.
+-- Explicit-precision float codecs: f32 (4B) and f64 (8B).
 
 local Base = require(script.Parent.Parent.Base)
 
--- Constants --------------------------------------------------------------
+-- State ------------------------------------------------------------------
 
--- Shared scratch for Auto codec's f32 round-trip test. Roblox is
--- single-threaded so a module-level scratch cannot be aliased.
+--[[
+    Roblox is single-threaded, so a module-level scratch is safe to alias.
+    Auto codec uses this to round-trip a float through f32 and check fidelity.
+]]
 local F32_SCRATCH = buffer.create(4)
 
 -- Public -----------------------------------------------------------------

package/src/codec/primitive/Signed.luau

@@ -1,7 +1,6 @@
 --!strict
 --!native
--- Signed integer buffer helpers. Reads use FASTCALL2 readi*; writes
--- emulate via writeu* + two's complement (writei* is not FASTCALL).
+-- Signed integer writers via writeu* + two's complement (writei* is not FASTCALL).
 
 -- Private ----------------------------------------------------------------
 
@@ -25,6 +24,7 @@ function Signed.writeI32(b: buffer, off: number, value: number): ()
     writeu32(b, off, if value < 0 then value + 0x100000000 else value)
 end
 
+-- Reads stay on buffer.readi* (already FASTCALL).
 Signed.readI8 = buffer.readi8
 Signed.readI16 = buffer.readi16
 Signed.readI32 = buffer.readi32