@rbxts/scribe 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. package/types/schema.d.ts +276 -0
@@ -0,0 +1,1283 @@
1
+ --!strict
2
+ -- Buffer wire format. Transports carry opaque buffers; both sides derive an
3
+ -- identical schema from the shared template, so paths intern to field IDs and
4
+ -- values pack by declared type. A 1-byte header per value lets anything the
5
+ -- schema cannot describe fall back to the generic codec.
6
+
7
+ local Template = require(script.Parent.Template)
8
+
9
+ type SchemaNode = Template.SchemaNode
10
+ type Compiled = Template.Compiled
11
+
12
+ local Wire = {}
13
+
14
+ -- Bump on any frame layout change, even a purely additive one. The server's Hello
15
+ -- version check is all that stands between a mixed deploy and mis-decoded frames.
16
+ Wire.PROTOCOL_VERSION = 6
17
+
18
+ -- Max arguments a command frame carries. Shared so the client's encode cap and the
19
+ -- server's decode guard cannot drift.
20
+ Wire.MAX_COMMAND_ARGS = 16
21
+
22
+ -- Built-in purchase prompt request; it uses the existing Command/CommandReply layout.
23
+ -- A game cannot register over it and replace the server's purchase checks.
24
+ Wire.PURCHASE_PROMPT_COMMAND = "__scribe_prompt_purchase"
25
+
26
+ -- Max bytes in an idempotency key, enforced on both sides. It governs a Command
27
+ -- frame's key and the persisted Data.Purchase key, so raising it raises what a
28
+ -- profile can carry. The number is repeated in prose nothing binds to this line:
29
+ -- Client/init, Server/init and Types.luau doc-comments, plus
30
+ -- docgen/guides/monetization.md and docgen/guides/log-codes.md.
31
+ Wire.MAX_IDEMPOTENCY_KEY_BYTES = 64
32
+
33
+ Wire.Frames = {
34
+ Hello = 1,
35
+ Init = 2,
36
+ Diff = 3,
37
+ Command = 4,
38
+ CommandReply = 5,
39
+ Status = 6,
40
+ SharedInit = 7,
41
+ SharedDiff = 8,
42
+ SharedGone = 9,
43
+ Leaderboard = 10,
44
+ Fragment = 11,
45
+ }
46
+
47
+ local KIND_TO_ID: { [string]: number } = { Set = 1, Insert = 2, Remove = 3, Clear = 4 }
48
+ local ID_TO_KIND: { [number]: string } = { "Set", "Insert", "Remove", "Clear" }
49
+
50
+ local FLAG_VALUE = 0x10
51
+ local FLAG_INDEX = 0x20
52
+
53
+ -- Writer ----------------------------------------------------------------------
54
+
55
+ export type Writer = {
56
+ buf: buffer,
57
+ len: number,
58
+ cap: number,
59
+ }
60
+
61
+ function Wire.NewWriter(capacity: number?): Writer
62
+ local cap = capacity or 128
63
+ return { buf = buffer.create(cap), len = 0, cap = cap }
64
+ end
65
+
66
+ local function ensure(w: Writer, n: number)
67
+ if w.len + n <= w.cap then
68
+ return
69
+ end
70
+ local newCap = math.max(w.cap * 2, w.len + n)
71
+ local newBuf = buffer.create(newCap)
72
+ buffer.copy(newBuf, 0, w.buf, 0, w.len)
73
+ w.buf = newBuf
74
+ w.cap = newCap
75
+ end
76
+
77
+ local function wu8(w: Writer, v: number)
78
+ ensure(w, 1)
79
+ buffer.writeu8(w.buf, w.len, v)
80
+ w.len += 1
81
+ end
82
+
83
+ local function wu16(w: Writer, v: number)
84
+ ensure(w, 2)
85
+ buffer.writeu16(w.buf, w.len, v)
86
+ w.len += 2
87
+ end
88
+
89
+ local function wu32(w: Writer, v: number)
90
+ ensure(w, 4)
91
+ buffer.writeu32(w.buf, w.len, v)
92
+ w.len += 4
93
+ end
94
+
95
+ local function wf64(w: Writer, v: number)
96
+ ensure(w, 8)
97
+ buffer.writef64(w.buf, w.len, v)
98
+ w.len += 8
99
+ end
100
+
101
+ -- Only reached for a value canSchemaEncode has already proved binary32 can hold
102
+ -- within the declared error bound.
103
+ local function wf32(w: Writer, v: number)
104
+ ensure(w, 4)
105
+ buffer.writef32(w.buf, w.len, v)
106
+ w.len += 4
107
+ end
108
+
109
+ -- Largest value the writer will encode. A Luau number is only an exact integer to
110
+ -- 2^53; past it the arithmetic below loses digits the reader cannot recover.
111
+ local MAX_VARINT = 2 ^ 53
112
+
113
+ -- Unsigned LEB128; arithmetic (not bit32) so values up to 2^53 round-trip.
114
+ local function wvarint(w: Writer, v: number)
115
+ -- Refuse rather than loop: math.floor(inf) is inf, so a non-finite input grows
116
+ -- the buffer until the process dies, and a negative wraps writeu8 into garbage.
117
+ if v ~= v or v == math.huge or v == -math.huge or v < 0 or v > MAX_VARINT then
118
+ error(`Scribe: cannot encode {tostring(v)} as a varint (expected an integer from 0 to 2^53)`, 0)
119
+ end
120
+ v = math.floor(v)
121
+ while v >= 128 do
122
+ wu8(w, v % 128 + 128)
123
+ v = math.floor(v / 128)
124
+ end
125
+ wu8(w, v)
126
+ end
127
+
128
+ local function wzigzag(w: Writer, v: number)
129
+ wvarint(w, if v >= 0 then v * 2 else -v * 2 - 1)
130
+ end
131
+
132
+ local function wstr(w: Writer, s: string)
133
+ wvarint(w, #s)
134
+ ensure(w, #s)
135
+ buffer.writestring(w.buf, w.len, s)
136
+ w.len += #s
137
+ end
138
+
139
+ local function wbuf(w: Writer, value: buffer)
140
+ local length = buffer.len(value)
141
+ wvarint(w, length)
142
+ ensure(w, length)
143
+ buffer.copy(w.buf, w.len, value)
144
+ w.len += length
145
+ end
146
+
147
+ function Wire.Finish(w: Writer): buffer
148
+ local out = buffer.create(w.len)
149
+ buffer.copy(out, 0, w.buf, 0, w.len)
150
+ return out
151
+ end
152
+
153
+ Wire.U8 = wu8
154
+ Wire.U16 = wu16
155
+ Wire.U32 = wu32
156
+ Wire.F64 = wf64
157
+ Wire.Varint = wvarint
158
+ Wire.Str = wstr
159
+
160
+ -- Reader ----------------------------------------------------------------------
161
+
162
+ export type Reader = {
163
+ buf: buffer,
164
+ pos: number,
165
+ size: number,
166
+ -- Remaining allocations this frame may still produce, nil for unlimited.
167
+ budget: number?,
168
+ -- Set when the budget ran out, so the caller can tell "too expensive" from
169
+ -- "malformed" without matching on error text a crafted frame controls.
170
+ overBudget: boolean?,
171
+ }
172
+
173
+ --- A reader over `buf`. `retainBudget` caps how many bytes the decoder may retain
174
+ --- from this frame, modelled per object; nil means unlimited.
175
+ ---
176
+ --- Caller-supplied on purpose: the same decoder runs on the client over Init
177
+ --- frames the size of a whole profile, so a module-level budget would refuse a
178
+ --- legitimate snapshot. Only the server's untrusted inbound path passes one.
179
+ function Wire.NewReader(buf: buffer, retainBudget: number?): Reader
180
+ return { buf = buf, pos = 0, size = buffer.len(buf), budget = retainBudget }
181
+ end
182
+
183
+ local function ru8(r: Reader): number
184
+ local v = buffer.readu8(r.buf, r.pos)
185
+ r.pos += 1
186
+ return v
187
+ end
188
+
189
+ local function ru16(r: Reader): number
190
+ local v = buffer.readu16(r.buf, r.pos)
191
+ r.pos += 2
192
+ return v
193
+ end
194
+
195
+ local function ru32(r: Reader): number
196
+ local v = buffer.readu32(r.buf, r.pos)
197
+ r.pos += 4
198
+ return v
199
+ end
200
+
201
+ local function rf64(r: Reader): number
202
+ local v = buffer.readf64(r.buf, r.pos)
203
+ r.pos += 8
204
+ return v
205
+ end
206
+
207
+ local function rf32(r: Reader): number
208
+ local v = buffer.readf32(r.buf, r.pos)
209
+ r.pos += 4
210
+ return v
211
+ end
212
+
213
+ local function rvarint(r: Reader): number
214
+ local result = 0
215
+ local multiplier = 1
216
+ -- 10 groups = 70 bits. A valid varint never exceeds ~8 groups; the extra
217
+ -- headroom just bounds a malicious one.
218
+ for _ = 1, 10 do
219
+ local byte = ru8(r)
220
+ result += (byte % 128) * multiplier
221
+ if byte < 128 then
222
+ return result
223
+ end
224
+ multiplier *= 128
225
+ end
226
+ error("Scribe: varint too long")
227
+ end
228
+
229
+ local function rzigzag(r: Reader): number
230
+ local v = rvarint(r)
231
+ if v % 2 == 0 then
232
+ return v / 2
233
+ end
234
+ return -(v + 1) / 2
235
+ end
236
+
237
+ -- What one decoded object retains, in bytes. Denominated in bytes rather than
238
+ -- object counts because an array slot costs the same whether it holds `true` or a
239
+ -- string pointer, while the two differ 2.5x in input bytes. Rounded up, and the two
240
+ -- Luau grows by doubling are counted at twice their unit size.
241
+ local SLOT_BYTES = 32 -- a 16-byte TValue, doubled for power-of-two array growth
242
+ local TABLE_BYTES = 64 -- the Table struct, ~56, rounded
243
+ local HASH_BYTES = 64 -- a 32-byte LuaNode, doubled for power-of-two node growth
244
+ local STRING_BYTES = 24 -- TString header, excluding the payload
245
+ local BUFFER_BYTES = 24 -- Buffer header, excluding the payload
246
+
247
+ -- The default budget of MaxInboundBytes * 16 (Replication.luau) is a ceiling, not
248
+ -- a per-byte figure: a nested empty table costs the sender two bytes and retains a
249
+ -- whole Table struct on top of the slot holding it, so table-valued elements
250
+ -- amplify well past 16:1 (WireBitmask.spec pins each path's worst case). Nothing
251
+ -- untrusted reaches the schema-typed decoder today; re-derive the multiplier from
252
+ -- those figures before one does.
253
+
254
+ -- Charge what one decoded object will retain, refusing the frame when the budget
255
+ -- runs out. Depth alone does not bound this: a flat table of four thousand empty
256
+ -- buffers is depth 1 and two bytes each. Raises rather than returning early, since
257
+ -- everything downstream assumes a failed decode discards the whole frame.
258
+ local function charge(r: Reader, bytes: number)
259
+ local left = r.budget
260
+ if left == nil then
261
+ return
262
+ end
263
+ if left < bytes then
264
+ r.overBudget = true
265
+ error("Scribe: inbound frame exceeded its retention budget")
266
+ end
267
+ r.budget = left - bytes
268
+ end
269
+
270
+ --- Read a string, refusing it from its length prefix instead of after the fact: a
271
+ --- cap applied to the result has already paid for the allocation.
272
+ local function rstrBounded(r: Reader, maxBytes: number): string
273
+ local len = rvarint(r)
274
+ if len > maxBytes then
275
+ error(`Scribe: string field of {len} bytes exceeds its {maxBytes}-byte limit`)
276
+ end
277
+ if r.pos + len > r.size then
278
+ error("Scribe: string overruns buffer")
279
+ end
280
+ local s = buffer.readstring(r.buf, r.pos, len)
281
+ r.pos += len
282
+ return s
283
+ end
284
+
285
+ --- `headerBytes` is the fixed per-object overhead charged against the frame's
286
+ --- retention budget, plus the payload length taken from the length prefix. Omitted
287
+ --- by callers not decoding untrusted generic data.
288
+ local function rstr(r: Reader, headerBytes: number?): string
289
+ local len = rvarint(r)
290
+ if headerBytes ~= nil then
291
+ charge(r, headerBytes + len)
292
+ end
293
+ if r.pos + len > r.size then
294
+ error("Scribe: string overruns buffer")
295
+ end
296
+ local s = buffer.readstring(r.buf, r.pos, len)
297
+ r.pos += len
298
+ return s
299
+ end
300
+
301
+ local function rbuf(r: Reader, headerBytes: number?): buffer
302
+ local length = rvarint(r)
303
+ if headerBytes ~= nil then
304
+ charge(r, headerBytes + length)
305
+ end
306
+ if r.pos + length > r.size then
307
+ error("Scribe: buffer overruns frame")
308
+ end
309
+ local out = buffer.create(length)
310
+ buffer.copy(out, 0, r.buf, r.pos, length)
311
+ r.pos += length
312
+ return out
313
+ end
314
+
315
+ Wire.RU8 = ru8
316
+ Wire.RU16 = ru16
317
+ Wire.RU32 = ru32
318
+ Wire.RF64 = rf64
319
+ Wire.RVarint = rvarint
320
+ Wire.RStr = rstr
321
+ Wire.RStrBounded = rstrBounded
322
+
323
+ function Wire.Remaining(r: Reader): number
324
+ return r.size - r.pos
325
+ end
326
+
327
+ -- Generic tagged value codec ---------------------------------------------------
328
+
329
+ local TAG_NIL, TAG_FALSE, TAG_TRUE, TAG_NUMBER, TAG_STRING, TAG_TABLE, TAG_BUFFER = 0, 1, 2, 3, 4, 5, 6
330
+
331
+ local function encodeGeneric(w: Writer, value: any, depth: number)
332
+ if depth > 24 then
333
+ error("Scribe: value too deep to serialize")
334
+ end
335
+ local t = type(value)
336
+ if value == nil then
337
+ wu8(w, TAG_NIL)
338
+ elseif t == "boolean" then
339
+ wu8(w, if value then TAG_TRUE else TAG_FALSE)
340
+ elseif t == "number" then
341
+ wu8(w, TAG_NUMBER)
342
+ wf64(w, value)
343
+ elseif t == "string" then
344
+ wu8(w, TAG_STRING)
345
+ wstr(w, value)
346
+ elseif t == "buffer" then
347
+ wu8(w, TAG_BUFFER)
348
+ wbuf(w, value)
349
+ elseif t == "table" then
350
+ wu8(w, TAG_TABLE)
351
+ -- Contiguous array part, then hash part.
352
+ local arrayLen = 0
353
+ while (value :: any)[arrayLen + 1] ~= nil do
354
+ arrayLen += 1
355
+ end
356
+ wvarint(w, arrayLen)
357
+ for i = 1, arrayLen do
358
+ encodeGeneric(w, value[i], depth + 1)
359
+ end
360
+ local hashCount = 0
361
+ for k in value do
362
+ if not (type(k) == "number" and k % 1 == 0 and k >= 1 and k <= arrayLen) then
363
+ hashCount += 1
364
+ end
365
+ end
366
+ wvarint(w, hashCount)
367
+ for k, v in value do
368
+ if not (type(k) == "number" and k % 1 == 0 and k >= 1 and k <= arrayLen) then
369
+ encodeGeneric(w, k, depth + 1)
370
+ encodeGeneric(w, v, depth + 1)
371
+ end
372
+ end
373
+ else
374
+ error(`Scribe: cannot serialize value of type "{t}"`)
375
+ end
376
+ end
377
+
378
+ local function decodeGeneric(r: Reader, depth: number): any
379
+ if depth > 24 then
380
+ error("Scribe: value too deep to deserialize")
381
+ end
382
+ local tag = ru8(r)
383
+ if tag == TAG_NIL then
384
+ return nil
385
+ elseif tag == TAG_FALSE then
386
+ return false
387
+ elseif tag == TAG_TRUE then
388
+ return true
389
+ elseif tag == TAG_NUMBER then
390
+ return rf64(r)
391
+ elseif tag == TAG_STRING then
392
+ return rstr(r, STRING_BYTES)
393
+ elseif tag == TAG_BUFFER then
394
+ return rbuf(r, BUFFER_BYTES)
395
+ elseif tag == TAG_TABLE then
396
+ charge(r, TABLE_BYTES)
397
+ local out = {}
398
+ local arrayLen = rvarint(r)
399
+ for i = 1, arrayLen do
400
+ -- Charged per slot, not just per table: a table of N booleans would
401
+ -- otherwise cost one charge while allocating N slots, at one byte each.
402
+ -- Charged before the recursive decode so the refusal precedes it.
403
+ charge(r, SLOT_BYTES)
404
+ out[i] = decodeGeneric(r, depth + 1)
405
+ end
406
+ local hashCount = rvarint(r)
407
+ for _ = 1, hashCount do
408
+ -- Same reasoning; a hash pair costs at least as much as an array slot.
409
+ charge(r, HASH_BYTES)
410
+ local k = decodeGeneric(r, depth + 1)
411
+ local v = decodeGeneric(r, depth + 1)
412
+ if k ~= nil and k == k then
413
+ out[k] = v
414
+ end
415
+ end
416
+ return out
417
+ end
418
+ error(`Scribe: unknown generic tag {tag}`)
419
+ end
420
+
421
+ function Wire.EncodeGeneric(w: Writer, value: any)
422
+ encodeGeneric(w, value, 0)
423
+ end
424
+
425
+ function Wire.DecodeGeneric(r: Reader): any
426
+ return decodeGeneric(r, 0)
427
+ end
428
+
429
+ -- Schema-typed value codec -------------------------------------------------------
430
+
431
+ -- The value header byte, in front of every encoded value.
432
+ -- bits 0-1 mode: GENERIC (the schema cannot describe it; self-describing codec),
433
+ -- DENSE (keys exactly 1..n; values positional, no key), STATIC (all declared
434
+ -- children; a presence bitmask over ChildOrder, then values in order), or
435
+ -- TAGGED (the fallback, and the only mode that can carry an unknown key).
436
+ -- bits 2-3 key tag, present only for an entry of a tagged table.
437
+ -- bits 4-7 reserved and refused: a set bit is a drifted encoder or a crafted frame.
438
+ -- A standalone header is 0..3 and a table entry's 0..15. DENSE and STATIC are refused on
439
+ -- a non-table node, which the scalar readers would otherwise accept in silence.
440
+ local VH_TAGGED = 0x00
441
+ local VH_GENERIC = 0x01
442
+ local VH_DENSE = 0x02
443
+ local VH_STATIC = 0x03
444
+ -- The key tag lives in bits 2-3, so it is scaled by 4 rather than shifted, which
445
+ -- makes VH_KEY_SCALE double as the modulus that extracts the mode. Bit work here
446
+ -- is arithmetic so that nothing depends on 32-bit truncation.
447
+ local VH_KEY_SCALE = 4
448
+ local VH_ENTRY_MAX = 16 -- one past the largest legal table-entry header
449
+ local VH_VALUE_MAX = 4 -- one past the largest legal standalone value header
450
+
451
+ local function intWidth(node: SchemaNode): number?
452
+ if node.Min ~= nil and node.Max ~= nil then
453
+ local range = node.Max - node.Min
454
+ if range < 256 then
455
+ return 1
456
+ elseif range < 65536 then
457
+ return 2
458
+ elseif range < 4294967296 then
459
+ return 4
460
+ end
461
+ end
462
+ return nil
463
+ end
464
+
465
+ -- Narrowed floats. The plan, the constants and the step count come from Template,
466
+ -- so the compiler, the encoder and the decoder share one derivation.
467
+ local FLOAT_F64 = Template.FLOAT_F64
468
+ local FLOAT_F32 = Template.FLOAT_F32
469
+ local FLOAT_Q8 = Template.FLOAT_Q8
470
+ local FLOAT_Q16 = Template.FLOAT_Q16
471
+ -- FLOAT_Q32 is deliberately absent: it is the fall-through plan in both the
472
+ -- encoder and the decoder below.
473
+ local F32_MAX = Template.F32_MAX
474
+ local F32_MIN_NORMAL = Template.F32_MIN_NORMAL
475
+ local floatPlan = Template.FloatPlan
476
+
477
+ --- The grid index of `v` on this node's fixed-point grid, rounded to nearest.
478
+ --- Truncating instead would double the worst-case error and bias it, so a quantized
479
+ --- field would drift downward over repeated round trips.
480
+ ---
481
+ --- The clamp is unreachable while canSchemaEncode holds, and stays: without it a
482
+ --- value just past Max reaches buffer.writeu8 as 256, wraps, and comes back as Min.
483
+ local function quantIndex(node: SchemaNode, v: number, steps: number): number
484
+ local q = math.floor((v - (node.Min :: number)) / (node.Precision :: number) + 0.5)
485
+ if q < 0 then
486
+ return 0
487
+ elseif q > steps then
488
+ return steps
489
+ end
490
+ return q
491
+ end
492
+
493
+ --- The grid point `q` names, clamped to Max.
494
+ ---
495
+ --- Not about crafted frames: `steps` is ceil((Max - Min)/Precision), so when
496
+ --- Precision does not divide the range the top index sits one grid point past Max
497
+ --- and quantIndex rounds Max itself onto it. Min=0, Max=100, Precision=0.6 gives
498
+ --- 167 steps and 167*0.6 = 100.2 for a legal, in-range 100. The int path has no
499
+ --- legitimate overshoot to correct. Max is never nil here: a numeric Precision
500
+ --- requires both bounds.
501
+ local function quantValue(node: SchemaNode, q: number): number
502
+ local v = (node.Min :: number) + q * (node.Precision :: number)
503
+ local max = node.Max :: number
504
+ if v > max then
505
+ return max
506
+ end
507
+ return v
508
+ end
509
+
510
+ local function canSchemaEncode(node: SchemaNode, value: any): boolean
511
+ local vt = node.ValueType
512
+ if vt == "boolean" then
513
+ return type(value) == "boolean"
514
+ elseif vt == "int" then
515
+ if type(value) ~= "number" or value % 1 ~= 0 then
516
+ return false
517
+ end
518
+ -- Beyond 2^52 the varint/zigzag arithmetic loses precision; fall back
519
+ -- to the generic f64 path, which round-trips any finite double.
520
+ if value > 0x10000000000000 or value < -0x10000000000000 then
521
+ return false
522
+ end
523
+ if node.Min ~= nil and node.Max ~= nil then
524
+ return value >= node.Min and value <= node.Max
525
+ end
526
+ if node.Min ~= nil and node.Min >= 0 then
527
+ return value >= 0
528
+ end
529
+ return true
530
+ elseif vt == "number" then
531
+ if type(value) ~= "number" then
532
+ return false
533
+ end
534
+ local plan = floatPlan(node)
535
+ if plan == FLOAT_F64 then
536
+ -- The default, and the only arm an undeclared Scribe.Number reaches: any
537
+ -- double at all, NaN and both infinities included.
538
+ return true
539
+ end
540
+ -- Narrowed, so the tests below are the precision guarantee: anything outside
541
+ -- the stated error bound is refused here and takes the generic path, where it
542
+ -- round-trips as an exact f64. NaN and the infinities fall out of the same
543
+ -- comparisons.
544
+ if plan == FLOAT_F32 then
545
+ local magnitude = math.abs(value)
546
+ -- Zero is exact in binary32. Above F32_MAX the nearest binary32 is
547
+ -- infinity; below F32_MIN_NORMAL the relative error blows past the 2^-24
548
+ -- the width promises.
549
+ return magnitude == 0 or (magnitude >= F32_MIN_NORMAL and magnitude <= F32_MAX)
550
+ end
551
+ -- Fixed-point. The grid only exists between the declared bounds, and both are
552
+ -- finite, so this also rejects the infinities and NaN.
553
+ return value >= (node.Min :: number) and value <= (node.Max :: number)
554
+ elseif vt == "enum" then
555
+ return type(value) == "string" and node.MemberIndex ~= nil and node.MemberIndex[value] ~= nil
556
+ elseif vt == "big" then
557
+ return type(value) == "table" and type(value[1]) == "number" and type(value[2]) == "number"
558
+ elseif vt == "flags" then
559
+ if type(value) ~= "table" or node.MemberIndex == nil then
560
+ return false
561
+ end
562
+ for _, name in value :: { any } do
563
+ if type(name) ~= "string" or node.MemberIndex[name] == nil then
564
+ return false
565
+ end
566
+ end
567
+ return true
568
+ elseif vt == "string" then
569
+ return type(value) == "string"
570
+ elseif vt == "buffer" or vt == "datatype" then
571
+ -- Datatype fields store (and travel as) their packed buffer form.
572
+ return type(value) == "buffer"
573
+ elseif vt == "table" then
574
+ return type(value) == "table"
575
+ end
576
+ return false
577
+ end
578
+
579
+ local TAG_KEY_STATIC, TAG_KEY_STRING, TAG_KEY_UINT, TAG_KEY_F64 = 0, 1, 2, 3
580
+
581
+ --- Whether `value`'s keys are exactly 1..count, so its body can be written
582
+ --- positionally. The only thing that may set the dense bit.
583
+ ---
584
+ --- `#value == count` is not equivalent: `#` on a holey table may return either
585
+ --- boundary, so `{[1]=1,[3]=3}` can answer 3 and would be written as three
586
+ --- positional values and read back as a different table. Probing every index costs
587
+ --- O(count) against an iteration that is already O(count).
588
+ local function isDenseArray(value: any, count: number): boolean
589
+ if count == 0 then
590
+ -- An empty table is trivially dense, but the flag saves nothing and costs
591
+ -- the decoder a shape it need not model.
592
+ return false
593
+ end
594
+ for i = 1, count do
595
+ if value[i] == nil then
596
+ return false
597
+ end
598
+ end
599
+ return true
600
+ end
601
+
602
+ --- The number of bytes wvarint spends on `v`, for comparing two candidate
603
+ --- encodings before either is written.
604
+ local function varintLen(v: number): number
605
+ local n = 1
606
+ while v >= 128 do
607
+ v = math.floor(v / 128)
608
+ n += 1
609
+ end
610
+ return n
611
+ end
612
+
613
+ --- Whether every key of `value` is a static child `node` declares, and whether a
614
+ --- presence bitmask costs fewer bytes than tagging each key. The only thing that
615
+ --- may set the static mode.
616
+ ---
617
+ --- The test is over the table's keys, not the schema's: walking ChildOrder instead
618
+ --- and finding every declared child present would pass a table that also carried
619
+ --- undeclared keys, and those would vanish from the frame in silence. No
620
+ --- empty-table guard is needed, unlike isDenseArray: no mask fits in fewer than
621
+ --- two bytes, so the cost comparison below already refuses one.
622
+ local function isStaticStruct(node: SchemaNode, value: any, count: number): boolean
623
+ local children = node.Children
624
+ local order = node.ChildOrder
625
+ if children == nil or order == nil then
626
+ return false
627
+ end
628
+ -- Unreachable for a compiled node that has Children, but it is the precondition
629
+ -- the encoder's `math.ceil(declared / 8) - 1` loop bound depends on.
630
+ local declared = #order
631
+ if declared == 0 then
632
+ return false
633
+ end
634
+ for k in value do
635
+ if type(k) ~= "string" or children[k] == nil then
636
+ return false
637
+ end
638
+ end
639
+ -- Static spends a width varint plus the mask; tagged spends a count varint plus
640
+ -- one ordinal varint per entry. Header and payload per field cancel. A tie goes
641
+ -- to tagged.
642
+ local staticBytes = varintLen(declared) + math.ceil(declared / 8)
643
+ local taggedBytes = varintLen(count) + count
644
+ return staticBytes < taggedBytes
645
+ end
646
+
647
+ --- The header bits for `value` under `node`, the node its payload is written
648
+ --- against (nil means the generic codec), and a table's entry count, so the payload
649
+ --- writer need not walk it again.
650
+ ---
651
+ --- Split out because a table entry writes its key between the header and the
652
+ --- payload: returning the bits lets the caller fold in the key tag and emit one byte.
653
+ local function valueHeaderBits(node: SchemaNode?, value: any): (number, SchemaNode?, number)
654
+ if node == nil or not canSchemaEncode(node, value) then
655
+ return VH_GENERIC, nil, 0
656
+ end
657
+ if node.ValueType == "table" then
658
+ local count = 0
659
+ for _ in value do
660
+ count += 1
661
+ end
662
+ if isDenseArray(value, count) then
663
+ return VH_DENSE, node, count
664
+ end
665
+ if isStaticStruct(node, value, count) then
666
+ return VH_STATIC, node, count
667
+ end
668
+ return VH_TAGGED, node, count
669
+ end
670
+ return VH_TAGGED, node, 0
671
+ end
672
+
673
+ local encodeValuePayload: (Writer, SchemaNode?, any, number, number, number) -> ()
674
+
675
+ --- Writes the value header (with no key tag; see the entry loop for the folded
676
+ --- form) and then the payload.
677
+ local function encodeValue(w: Writer, node: SchemaNode?, value: any, depth: number)
678
+ local bits, target, count = valueHeaderBits(node, value)
679
+ wu8(w, bits)
680
+ encodeValuePayload(w, target, value, depth, bits, count)
681
+ end
682
+
683
+ --- `bits` and `count` come from valueHeaderBits rather than being recomputed: the
684
+ --- header is already written, so the mode here has to be the one it announced.
685
+ function encodeValuePayload(w: Writer, node: SchemaNode?, value: any, depth: number, bits: number, count: number)
686
+ if node == nil then
687
+ encodeGeneric(w, value, depth)
688
+ return
689
+ end
690
+ local vt = node.ValueType
691
+ if vt == "boolean" then
692
+ wu8(w, if value then 1 else 0)
693
+ elseif vt == "int" then
694
+ local width = intWidth(node)
695
+ if width == 1 then
696
+ wu8(w, value - (node.Min :: number))
697
+ elseif width == 2 then
698
+ wu16(w, value - (node.Min :: number))
699
+ elseif width == 4 then
700
+ wu32(w, value - (node.Min :: number))
701
+ elseif node.Min ~= nil and node.Min >= 0 then
702
+ wvarint(w, value)
703
+ else
704
+ wzigzag(w, value)
705
+ end
706
+ elseif vt == "number" then
707
+ local plan = floatPlan(node)
708
+ if plan == FLOAT_F64 then
709
+ wf64(w, value)
710
+ elseif plan == FLOAT_F32 then
711
+ wf32(w, value)
712
+ else
713
+ local steps = Template.QuantSteps(node.Min :: number, node.Max :: number, node.Precision :: number)
714
+ local q = quantIndex(node, value, steps)
715
+ if plan == FLOAT_Q8 then
716
+ wu8(w, q)
717
+ elseif plan == FLOAT_Q16 then
718
+ wu16(w, q)
719
+ else
720
+ wu32(w, q) -- FLOAT_Q32
721
+ end
722
+ end
723
+ elseif vt == "enum" then
724
+ wu8(w, (node.MemberIndex :: { [string]: number })[value])
725
+ elseif vt == "big" then
726
+ -- The mantissa needs full double precision; the exponent is a small signed
727
+ -- integer, so a zigzag varint is one or two bytes for any realistic value.
728
+ wf64(w, value[1])
729
+ wzigzag(w, value[2])
730
+ elseif vt == "flags" then
731
+ -- One bit per declared member, LSB = first member. Positional only within a
732
+ -- frame; the stored form is the member names.
733
+ local index = node.MemberIndex :: { [string]: number }
734
+ local mask = 0
735
+ for _, name in value :: { string } do
736
+ -- MemberIndex is 0-based, so the first member owns bit 0.
737
+ mask += 2 ^ index[name]
738
+ end
739
+ local memberCount = #(node.Members :: { string })
740
+ if memberCount <= 8 then
741
+ wu8(w, mask)
742
+ elseif memberCount <= 16 then
743
+ wu16(w, mask)
744
+ else
745
+ wu32(w, mask)
746
+ end
747
+ elseif vt == "string" then
748
+ wstr(w, value)
749
+ elseif vt == "buffer" or vt == "datatype" then
750
+ wbuf(w, value)
751
+ elseif vt == "table" then
752
+ if depth > 24 then
753
+ error("Scribe: value too deep to serialize")
754
+ end
755
+ local mode = bits % VH_KEY_SCALE
756
+ if mode == VH_STATIC then
757
+ -- One bit per declared child replaces the keys, then the present values in
758
+ -- ordinal order. No entry count: it would restate the mask's popcount. Each
759
+ -- child still carries its own header, so a value the schema cannot describe
760
+ -- degrades to generic in place; only an undeclared key forces the tagged path.
761
+ local order = node.ChildOrder :: { string }
762
+ local children = node.Children :: { [string]: SchemaNode }
763
+ local declared = #order
764
+ wvarint(w, declared)
765
+ -- LSB of the first byte is ordinal 1. Padding bits past `declared` are
766
+ -- written zero and refused on the way back in.
767
+ for byteIndex = 0, math.ceil(declared / 8) - 1 do
768
+ local mask = 0
769
+ for bit = 0, 7 do
770
+ local ordinal = byteIndex * 8 + bit + 1
771
+ if ordinal <= declared and value[order[ordinal]] ~= nil then
772
+ mask += 2 ^ bit
773
+ end
774
+ end
775
+ wu8(w, mask)
776
+ end
777
+ for i = 1, declared do
778
+ local name = order[i]
779
+ local v = value[name]
780
+ if v ~= nil then
781
+ local ebits, etarget, ecount = valueHeaderBits(children[name], v)
782
+ wu8(w, ebits)
783
+ encodeValuePayload(w, etarget, v, depth + 1, ebits, ecount)
784
+ end
785
+ end
786
+ elseif mode == VH_DENSE then
787
+ wvarint(w, count)
788
+ -- Keys are 1..count and inferable from position, so nothing is written for
789
+ -- them. Each element still carries a header and can degrade to generic.
790
+ for i = 1, count do
791
+ local child = Template.ChildSchema(node, i)
792
+ local element = value[i]
793
+ local ebits, etarget, ecount = valueHeaderBits(child, element)
794
+ wu8(w, ebits)
795
+ encodeValuePayload(w, etarget, element, depth + 1, ebits, ecount)
796
+ end
797
+ else
798
+ wvarint(w, count)
799
+ for k, v in value do
800
+ local child: SchemaNode? = nil
801
+ local keyTag: number
802
+ if type(k) == "string" and node.Children and node.Children[k] then
803
+ child = node.Children[k]
804
+ keyTag = TAG_KEY_STATIC
805
+ elseif type(k) == "string" then
806
+ child = Template.ChildSchema(node, k)
807
+ keyTag = TAG_KEY_STRING
808
+ elseif type(k) == "number" and k % 1 == 0 and k >= 0 then
809
+ child = Template.ChildSchema(node, k)
810
+ keyTag = TAG_KEY_UINT
811
+ else
812
+ child = Template.ChildSchema(node, k)
813
+ keyTag = TAG_KEY_F64
814
+ end
815
+ local ebits, etarget, ecount = valueHeaderBits(child, v)
816
+ -- The fold: key tag and value mode share one byte.
817
+ wu8(w, ebits + keyTag * VH_KEY_SCALE)
818
+ if keyTag == TAG_KEY_STATIC then
819
+ wvarint(w, (node.ChildOrdinal :: { [string]: number })[k])
820
+ elseif keyTag == TAG_KEY_STRING then
821
+ wstr(w, k :: string)
822
+ elseif keyTag == TAG_KEY_UINT then
823
+ wvarint(w, k :: number)
824
+ else
825
+ wf64(w, k :: number)
826
+ end
827
+ encodeValuePayload(w, etarget, v, depth + 1, ebits, ecount)
828
+ end
829
+ end
830
+ end
831
+ end
832
+
833
+ local decodeValuePayload: (Reader, SchemaNode?, number, number) -> any
834
+
835
+ --- Reads a standalone value header (no key tag) and its payload.
836
+ local function decodeValue(r: Reader, node: SchemaNode?, depth: number): any
837
+ local header = ru8(r)
838
+ -- A standalone header owns bits 0-1 only. Key-tag bits here mean the writer and
839
+ -- the reader disagree about whether this value sits in a table.
840
+ if header >= VH_VALUE_MAX then
841
+ error("Scribe: malformed value header")
842
+ end
843
+ return decodeValuePayload(r, node, depth, header)
844
+ end
845
+
846
+ --- `header` carries the mode and dense bits (bits 0-1); the caller has already
847
+ --- stripped any key tag and validated the reserved range.
848
+ function decodeValuePayload(r: Reader, node: SchemaNode?, depth: number, header: number): any
849
+ -- An enumeration, not a set of flags: VH_STATIC is 3, so a `header % 2` test
850
+ -- for genericness would decode a presence bitmask as a generic type tag.
851
+ local mode = header % VH_KEY_SCALE
852
+ if mode == VH_GENERIC then
853
+ return decodeGeneric(r, depth)
854
+ end
855
+ if node == nil then
856
+ error("Scribe: malformed value mode")
857
+ end
858
+ local vt = node.ValueType
859
+ -- DENSE and STATIC describe a table's body, so either over a scalar node is a
860
+ -- drifted encoder or a crafted header. Refused rather than ignored: none of the
861
+ -- scalar readers below looks at the mode.
862
+ if mode >= VH_DENSE and vt ~= "table" then
863
+ error(`Scribe: table value mode on a "{vt}" node`)
864
+ end
865
+ if vt == "boolean" then
866
+ return ru8(r) ~= 0
867
+ elseif vt == "int" then
868
+ local width = intWidth(node)
869
+ if width == 1 then
870
+ return ru8(r) + (node.Min :: number)
871
+ elseif width == 2 then
872
+ return ru16(r) + (node.Min :: number)
873
+ elseif width == 4 then
874
+ return ru32(r) + (node.Min :: number)
875
+ elseif node.Min ~= nil and node.Min >= 0 then
876
+ return rvarint(r)
877
+ else
878
+ return rzigzag(r)
879
+ end
880
+ elseif vt == "number" then
881
+ local plan = floatPlan(node)
882
+ if plan == FLOAT_F64 then
883
+ return rf64(r)
884
+ elseif plan == FLOAT_F32 then
885
+ return rf32(r)
886
+ elseif plan == FLOAT_Q8 then
887
+ return quantValue(node, ru8(r))
888
+ elseif plan == FLOAT_Q16 then
889
+ return quantValue(node, ru16(r))
890
+ end
891
+ -- FLOAT_Q32, as the tail rather than a branch of its own. These arms must
892
+ -- mirror the encoder's, or a field is written and read at different widths.
893
+ return quantValue(node, ru32(r))
894
+ elseif vt == "big" then
895
+ return { rf64(r), rzigzag(r) }
896
+ elseif vt == "flags" then
897
+ local members = node.Members :: { string }
898
+ local count = #members
899
+ local mask = if count <= 8 then ru8(r) elseif count <= 16 then ru16(r) else ru32(r)
900
+ charge(r, TABLE_BYTES)
901
+ local out = {}
902
+ for i, name in members do
903
+ if mask % (2 ^ i) >= 2 ^ (i - 1) then
904
+ -- The name is interned in the compiled template, so only the slot is
905
+ -- new; charged for symmetry with decodeGeneric.
906
+ charge(r, SLOT_BYTES)
907
+ table.insert(out, name)
908
+ end
909
+ end
910
+ return out
911
+ elseif vt == "enum" then
912
+ local idx = ru8(r)
913
+ local member = (node.Members :: { string })[idx + 1]
914
+ if member == nil then
915
+ error("Scribe: enum index out of range")
916
+ end
917
+ return member
918
+ elseif vt == "string" then
919
+ return rstr(r, STRING_BYTES)
920
+ elseif vt == "buffer" or vt == "datatype" then
921
+ return rbuf(r, BUFFER_BYTES)
922
+ elseif vt == "table" then
923
+ if depth > 24 then
924
+ error("Scribe: value too deep to deserialize")
925
+ end
926
+ charge(r, TABLE_BYTES)
927
+ -- Written with a string key in the static branch and a number key in the
928
+ -- array branch, so the first write alone must not pin the index type.
929
+ local out: { [string | number]: any } = {}
930
+ if mode == VH_STATIC then
931
+ local order = node.ChildOrder
932
+ local children = node.Children
933
+ if order == nil or children == nil then
934
+ -- An open any-node or a leaf element declares no children, so there is
935
+ -- no ChildOrder for a bitmask to index.
936
+ error("Scribe: static table under a node with no declared children")
937
+ end
938
+ local declared = rvarint(r)
939
+ -- The mask's width comes from the frame and is checked against the schema,
940
+ -- so a disagreeing frame fails here, at the table that is wrong, rather than
941
+ -- mis-parsing everything after it. It also bounds the read below by the
942
+ -- schema rather than by an attacker-chosen varint.
943
+ if declared ~= #order then
944
+ error("Scribe: static bitmask width disagrees with the schema")
945
+ end
946
+ local maskBytes = math.ceil(declared / 8)
947
+ local maskStart = r.pos
948
+ if maskStart + maskBytes > r.size then
949
+ error("Scribe: static bitmask overruns buffer")
950
+ end
951
+ r.pos += maskBytes
952
+ -- Charged up front from the popcount, so a wide struct is refused before the
953
+ -- first recursive decode. The mask already states the whole entry list.
954
+ local present = 0
955
+ for b = 0, maskBytes - 1 do
956
+ local byte = buffer.readu8(r.buf, maskStart + b)
957
+ if b == maskBytes - 1 then
958
+ -- Padding bits past `declared` are written zero; a frame that sets
959
+ -- one is refused rather than masked off.
960
+ local used = declared - b * 8
961
+ if used < 8 and byte >= 2 ^ used then
962
+ error("Scribe: static bitmask has bits set past its declared width")
963
+ end
964
+ end
965
+ while byte > 0 do
966
+ present += byte % 2
967
+ byte = math.floor(byte / 2)
968
+ end
969
+ end
970
+ charge(r, HASH_BYTES * present)
971
+ for i = 1, declared do
972
+ local byte = buffer.readu8(r.buf, maskStart + math.floor((i - 1) / 8))
973
+ local bit = (i - 1) % 8
974
+ if byte % (2 ^ (bit + 1)) >= 2 ^ bit then
975
+ local name = order[i]
976
+ out[name] = decodeValue(r, children[name], depth + 1)
977
+ end
978
+ end
979
+ return out
980
+ end
981
+ local count = rvarint(r)
982
+ if mode == VH_DENSE then
983
+ for i = 1, count do
984
+ -- SLOT_BYTES rather than the tagged path's HASH_BYTES because these
985
+ -- really are array slots, and two bytes against 32 is the same ratio as
986
+ -- the tagged path's four against 64. Charged before the decode.
987
+ charge(r, SLOT_BYTES)
988
+ out[i] = decodeValue(r, Template.ChildSchema(node, i), depth + 1)
989
+ end
990
+ return out
991
+ end
992
+ for _ = 1, count do
993
+ -- Charged per declared entry, from the count above, before the key or the
994
+ -- value is read. A no-op against the client's nil budget today; it is here
995
+ -- so it is not a hole to rediscover.
996
+ charge(r, HASH_BYTES)
997
+ local entryHeader = ru8(r)
998
+ if entryHeader >= VH_ENTRY_MAX then
999
+ error("Scribe: malformed value header")
1000
+ end
1001
+ local tag = (entryHeader - entryHeader % VH_KEY_SCALE) / VH_KEY_SCALE
1002
+ local key: any
1003
+ local child: SchemaNode? = nil
1004
+ if tag == TAG_KEY_STATIC then
1005
+ local ordinal = rvarint(r)
1006
+ -- ChildOrder is nil on a node that declares no static children, so a
1007
+ -- frame claiming a static key under one is malformed. Without this it
1008
+ -- surfaces as "attempt to index nil with number", reading as a bug.
1009
+ local order = node.ChildOrder
1010
+ local name = if order ~= nil then order[ordinal] else nil
1011
+ if name == nil then
1012
+ error("Scribe: bad child ordinal")
1013
+ end
1014
+ key = name
1015
+ child = (node.Children :: { [string]: SchemaNode })[name]
1016
+ elseif tag == TAG_KEY_STRING then
1017
+ key = rstr(r, STRING_BYTES)
1018
+ child = Template.ChildSchema(node, key)
1019
+ elseif tag == TAG_KEY_UINT then
1020
+ key = rvarint(r)
1021
+ child = Template.ChildSchema(node, key)
1022
+ else
1023
+ key = rf64(r)
1024
+ child = Template.ChildSchema(node, key)
1025
+ end
1026
+ local value = decodeValuePayload(r, child, depth + 1, entryHeader % VH_KEY_SCALE)
1027
+ -- Skip a NaN key (only a crafted TAG_KEY_F64 decodes to one): t[NaN] throws.
1028
+ -- Decode the value first to keep the reader in sync.
1029
+ if key == key then
1030
+ out[key] = value
1031
+ end
1032
+ end
1033
+ return out
1034
+ end
1035
+ error(`Scribe: cannot decode schema value type "{vt}"`)
1036
+ end
1037
+
1038
+ function Wire.EncodeValue(w: Writer, node: SchemaNode?, value: any)
1039
+ encodeValue(w, node, value, 0)
1040
+ end
1041
+
1042
+ function Wire.DecodeValue(r: Reader, node: SchemaNode?): any
1043
+ return decodeValue(r, node, 0)
1044
+ end
1045
+
1046
+ -- Path codec --------------------------------------------------------------------
1047
+
1048
+ -- Encodes a path as (deepest static field ID, dynamic tail). Returns the schema
1049
+ -- node the full path resolves to (dynamic segments resolve to any-nodes).
1050
+ function Wire.EncodePath(w: Writer, compiled: Compiled, path: { string | number }): SchemaNode?
1051
+ local node, dynStart = Template.Resolve(compiled, path)
1052
+ wvarint(w, node.Id :: number)
1053
+ local dynCount = #path - dynStart + 1
1054
+ -- The count travels as a u8, so a deeper path would wrap and desync the frame.
1055
+ -- Writes are already capped at MAX_PATH_DYN_SEGMENTS (Node.validateWrite).
1056
+ if dynCount > 255 then
1057
+ error(`Scribe: path has too many dynamic segments ({dynCount})`)
1058
+ end
1059
+ wu8(w, dynCount)
1060
+ local target: SchemaNode? = node
1061
+ for i = dynStart, #path do
1062
+ local seg = path[i]
1063
+ if type(seg) == "string" then
1064
+ wu8(w, TAG_KEY_STRING)
1065
+ wstr(w, seg)
1066
+ elseif seg % 1 == 0 and seg >= 0 then
1067
+ wu8(w, TAG_KEY_UINT)
1068
+ wvarint(w, seg)
1069
+ else
1070
+ wu8(w, TAG_KEY_F64)
1071
+ wf64(w, seg)
1072
+ end
1073
+ target = if target then Template.ChildSchema(target, seg) else nil
1074
+ end
1075
+ return target
1076
+ end
1077
+
1078
+ function Wire.DecodePath(r: Reader, compiled: Compiled): ({ string | number }, SchemaNode?)
1079
+ local id = rvarint(r)
1080
+ local node = compiled.ById[id]
1081
+ if node == nil then
1082
+ error(`Scribe: unknown field id {id}`)
1083
+ end
1084
+ local path: { string | number } = table.clone(node.Path) :: any
1085
+ local dynCount = ru8(r)
1086
+ local target: SchemaNode? = node
1087
+ for _ = 1, dynCount do
1088
+ local tag = ru8(r)
1089
+ local seg: string | number
1090
+ if tag == TAG_KEY_STRING then
1091
+ seg = rstr(r)
1092
+ elseif tag == TAG_KEY_UINT then
1093
+ seg = rvarint(r)
1094
+ elseif tag == TAG_KEY_F64 then
1095
+ seg = rf64(r)
1096
+ else
1097
+ error("Scribe: bad path segment tag")
1098
+ end
1099
+ table.insert(path, seg)
1100
+ target = if target then Template.ChildSchema(target, seg) else nil
1101
+ end
1102
+ return path, target
1103
+ end
1104
+
1105
+ -- Op codec ------------------------------------------------------------------------
1106
+
1107
+ export type Op = {
1108
+ Kind: string, -- "Set" | "Insert" | "Remove" | "Clear"
1109
+ Path: { string | number },
1110
+ Value: any?,
1111
+ Index: number?,
1112
+ }
1113
+
1114
+ function Wire.EncodeOp(w: Writer, compiled: Compiled, op: Op)
1115
+ local kindId = KIND_TO_ID[op.Kind]
1116
+ if kindId == nil then
1117
+ error(`Scribe: unknown op kind "{op.Kind}"`)
1118
+ end
1119
+ local head = kindId
1120
+ local hasValue = op.Value ~= nil
1121
+ if hasValue then
1122
+ head += FLAG_VALUE
1123
+ end
1124
+ if op.Index ~= nil then
1125
+ head += FLAG_INDEX
1126
+ end
1127
+ wu8(w, head)
1128
+ local target = Wire.EncodePath(w, compiled, op.Path)
1129
+ if op.Index ~= nil then
1130
+ wvarint(w, op.Index)
1131
+ end
1132
+ if hasValue then
1133
+ local valueNode = target
1134
+ if op.Kind == "Insert" and target then
1135
+ -- Array elements are children of the container node.
1136
+ valueNode = Template.ChildSchema(target, 1)
1137
+ end
1138
+ Wire.EncodeValue(w, valueNode, op.Value)
1139
+ end
1140
+ end
1141
+
1142
+ function Wire.DecodeOp(r: Reader, compiled: Compiled): Op
1143
+ local head = ru8(r)
1144
+ local kindId = head % 16
1145
+ local kind = ID_TO_KIND[kindId]
1146
+ if kind == nil then
1147
+ error(`Scribe: unknown op kind id {kindId}`)
1148
+ end
1149
+ local hasValue = head % 32 >= 16
1150
+ local hasIndex = head % 64 >= 32
1151
+ local path, target = Wire.DecodePath(r, compiled)
1152
+ local index: number? = nil
1153
+ if hasIndex then
1154
+ index = rvarint(r)
1155
+ end
1156
+ local value: any = nil
1157
+ if hasValue then
1158
+ local valueNode = target
1159
+ if kind == "Insert" and target then
1160
+ valueNode = Template.ChildSchema(target, 1)
1161
+ end
1162
+ value = Wire.DecodeValue(r, valueNode)
1163
+ end
1164
+ return { Kind = kind, Path = path, Value = value, Index = index }
1165
+ end
1166
+
1167
+ --- The initial writer capacity EncodeOpsFrame will choose for `opCount` ops and an
1168
+ --- optional `sizeHint`. Exported so a spec can pin it: seeding changes allocation
1169
+ --- counts and not one output byte, so nothing else could tell it from an
1170
+ --- implementation that quietly stopped seeding. InitWriterSeed.spec watches it.
1171
+ function Wire.OpsFrameCapacity(opCount: number, sizeHint: number?): number
1172
+ -- A hint smaller than the op count implies, from a tiny previous Init before a
1173
+ -- large one, must not shrink the writer below what the ops alone justify.
1174
+ local capacity = 64 + opCount * 16
1175
+ if sizeHint ~= nil and sizeHint > capacity then
1176
+ return sizeHint
1177
+ end
1178
+ return capacity
1179
+ end
1180
+
1181
+ --- Encodes a frame: a frame-type byte, an optional prelude written by `prelude(w)`,
1182
+ --- and a u16-counted op list. When `spans` is given it is filled with each op's
1183
+ --- encoded byte length, in order, measured from the writer's own offset rather than
1184
+ --- by re-encoding, which would cost a second pass and over-count one header per op.
1185
+ ---
1186
+ --- `sizeHint` is a floor for the writer's initial capacity, in bytes, and only the
1187
+ --- Init path passes one. `#ops` models a Diff but not an Init: ownerSnapshotOps
1188
+ --- emits one op per root, so a forty-thousand-field profile produces the same
1189
+ --- handful of ops as a tiny one and the writer doubles its way up from a couple of
1190
+ --- hundred bytes. The last Init's size estimates the next.
1191
+ function Wire.EncodeOpsFrame(
1192
+ frameType: number,
1193
+ compiled: Compiled,
1194
+ ops: { Op },
1195
+ prelude: ((Writer) -> ())?,
1196
+ spans: { number }?,
1197
+ sizeHint: number?
1198
+ ): buffer
1199
+ -- Callers pre-chunk to MAX_OPS_PER_FRAME; a frame over the u16 count limit
1200
+ -- would silently drop its tail, so fail loudly instead.
1201
+ if #ops > 65535 then
1202
+ error(`Scribe: op frame too large ({#ops} ops); chunk before encoding`)
1203
+ end
1204
+ local w = Wire.NewWriter(Wire.OpsFrameCapacity(#ops, sizeHint))
1205
+ wu8(w, frameType)
1206
+ if prelude then
1207
+ prelude(w)
1208
+ end
1209
+ wu16(w, #ops)
1210
+ if spans == nil then
1211
+ for i = 1, #ops do
1212
+ Wire.EncodeOp(w, compiled, ops[i])
1213
+ end
1214
+ else
1215
+ local prev = w.len
1216
+ for i = 1, #ops do
1217
+ Wire.EncodeOp(w, compiled, ops[i])
1218
+ spans[i] = w.len - prev
1219
+ prev = w.len
1220
+ end
1221
+ end
1222
+ return Wire.Finish(w)
1223
+ end
1224
+
1225
+ -- Frame fragmentation ------------------------------------------------------------
1226
+ --
1227
+ -- Framing, not replication: an Init snapshot is one op per root, so the encoded buffer
1228
+ -- is split rather than the ops.
1229
+ -- u8 Frames.Fragment | u16 seq | u32 total | u16 index | <payload slice>
1230
+ -- `total` repeats in every fragment so the receiver can size from the first. `index`
1231
+ -- makes a lost middle fragment detectable. `seq` stops two interleaved frames splicing
1232
+ -- into one that decodes cleanly to values from neither; Scribe never interleaves today.
1233
+ Wire.FRAGMENT_HEADER = 9
1234
+
1235
+ --- Splits `bytes` into fragments no larger than `maxBytes`, handing each to `emit`
1236
+ --- in order. Returns nil when the frame already fits and `emit` was never called;
1237
+ --- otherwise whether every fragment was emitted (`emit` may return false to stop).
1238
+ ---
1239
+ --- Streaming rather than list-returning: a materialised list is a second full copy
1240
+ --- of the frame, and the unicast Init has one recipient and needs none.
1241
+ function Wire.Fragment(bytes: buffer, maxBytes: number, seq: number, emit: (buffer) -> boolean): boolean?
1242
+ local total = buffer.len(bytes)
1243
+ if total <= maxBytes then
1244
+ return nil
1245
+ end
1246
+ local capacity = maxBytes - Wire.FRAGMENT_HEADER
1247
+ if capacity < 1 then
1248
+ error(`Scribe: fragment budget of {maxBytes} bytes cannot carry a payload`, 0)
1249
+ end
1250
+ -- buffer.writeu16 truncates silently, so a wrapped index would reset the
1251
+ -- receiver mid-frame and a wrapped count would end it early.
1252
+ local count = math.ceil(total / capacity)
1253
+ if count > 65535 then
1254
+ error(`Scribe: frame of {total} bytes needs {count} fragments (max 65535); raise MaxOutboundBytes`, 0)
1255
+ end
1256
+ local offset, index = 0, 0
1257
+ while offset < total do
1258
+ local take = math.min(capacity, total - offset)
1259
+ local frame = buffer.create(Wire.FRAGMENT_HEADER + take)
1260
+ buffer.writeu8(frame, 0, Wire.Frames.Fragment)
1261
+ buffer.writeu16(frame, 1, seq)
1262
+ buffer.writeu32(frame, 3, total)
1263
+ buffer.writeu16(frame, 7, index)
1264
+ buffer.copy(frame, Wire.FRAGMENT_HEADER, bytes, offset, take)
1265
+ if not emit(frame) then
1266
+ return false
1267
+ end
1268
+ offset += take
1269
+ index += 1
1270
+ end
1271
+ return true
1272
+ end
1273
+
1274
+ function Wire.DecodeOps(r: Reader, compiled: Compiled): { Op }
1275
+ local count = ru16(r)
1276
+ local ops = table.create(count) :: { Op }
1277
+ for _ = 1, count do
1278
+ table.insert(ops, Wire.DecodeOp(r, compiled))
1279
+ end
1280
+ return ops
1281
+ end
1282
+
1283
+ return Wire