@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,1848 @@
1
+ --!strict
2
+ -- Template compiler + runtime schema derivation. Walks the user template with
3
+ -- sorted keys (deterministic on server and client), strips declarator markers,
4
+ -- assigns a u16 field ID to every static path node, and records declared
5
+ -- type/bounds/visibility metadata for validation and wire packing.
6
+
7
+ local Util = require(script.Parent.Util)
8
+ local Marker = require(script.Parent.Marker)
9
+ local Big = require(script.Parent.Big)
10
+ local Datatypes = require(script.Parent.Datatypes)
11
+ local DerivedModule = require(script.Parent.Derived)
12
+
13
+ --- A declared bound that is NaN or infinite cannot bound anything: nothing exceeds
14
+ --- math.huge, and every comparison against NaN is false.
15
+ local function isFiniteBound(n: number): boolean
16
+ return n == n and n ~= math.huge and n ~= -math.huge
17
+ end
18
+
19
+ -- The wire width a Scribe.Number takes, opt-in via Precision. FLOAT_F64 is the default
20
+ -- and is what an undeclared Number stays; Min/Max alone select nothing. FLOAT_F32 is
21
+ -- Precision = "f32", IEEE binary32 in 4 bytes. FLOAT_Q8/16/32 is Precision = <step>, a
22
+ -- fixed-point grid over [Min, Max] whose nearest-point index travels in the narrowest
23
+ -- of 1, 2 or 4 bytes that holds the step count.
24
+ -- Lives here rather than in Wire (where its sibling intWidth does) because the compiler
25
+ -- has to agree with the encoder and the decoder: "the declared bounds cannot be
26
+ -- represented in the chosen width" is a startup refusal.
27
+ local FLOAT_F64, FLOAT_F32, FLOAT_Q8, FLOAT_Q16, FLOAT_Q32 = 0, 1, 2, 3, 4
28
+
29
+ -- The extremes of IEEE binary32: the largest finite value and the smallest normal
30
+ -- magnitude. Wire.canSchemaEncode tests values against both, because a value outside
31
+ -- them must degrade to exact f64 rather than round to infinity or flush to zero.
32
+ local F32_MAX = 3.4028234663852886e38
33
+ local F32_MIN_NORMAL = 1.1754943508222875e-38
34
+ -- Largest grid index a fixed-point field can carry, i.e. the u32 the widest form
35
+ -- writes. A range needing more steps than this is refused at compile time.
36
+ local Q_MAX_STEPS = 4294967295
37
+
38
+ --- How many grid steps `[Min, Max]` needs at a step of `Precision`. The grid
39
+ --- index runs 0..steps INCLUSIVE, so a width holding `steps` holds every index.
40
+ local function quantSteps(min: number, max: number, precision: number): number
41
+ return math.ceil((max - min) / precision)
42
+ end
43
+
44
+ export type Visibility = "Replicated" | "ServerOnly" | "Shared"
45
+
46
+ export type SchemaNode = {
47
+ Id: number?, -- nil for dynamic (any) pseudo-nodes
48
+ Name: string?,
49
+ Path: { string },
50
+ Kind: "leaf" | "table" | "any",
51
+ ValueType: "number"
52
+ | "int"
53
+ | "boolean"
54
+ | "string"
55
+ | "enum"
56
+ | "flags"
57
+ | "big"
58
+ | "buffer"
59
+ | "datatype"
60
+ | "table"
61
+ | "any",
62
+ Datatype: string?, -- typeof() name when ValueType == "datatype"
63
+ Visibility: Visibility, -- who receives diffs
64
+ Persist: boolean, -- false for a Scribe.Session subtree; orthogonal to Visibility
65
+ Timed: boolean,
66
+ Min: number?,
67
+ Max: number?,
68
+ -- Scribe.Number only, opt-in: nil is f64, "f32" is IEEE binary32, a positive
69
+ -- number is the step of a fixed-point grid over [Min, Max]. Wire.floatPlan is the
70
+ -- one place that turns this into a width.
71
+ Precision: (number | string)?,
72
+ MaxLength: number?,
73
+ Members: { string }?,
74
+ MemberIndex: { [string]: number }?, -- 0-based, for u8 packing
75
+ Default: any,
76
+ Factory: (() -> any)?, -- Scribe.Dynamic: seeds this field on a brand-new profile
77
+ -- Scribe.Derived: computed from other declared fields, never written. Resolved in
78
+ -- a post-pass (see Compile), because an input may name a root that has not been
79
+ -- built yet when this node is created.
80
+ Derived: {
81
+ Inputs: { SchemaNode },
82
+ InputPaths: { { string } },
83
+ Compute: (...any) -> any,
84
+ Transmit: boolean, -- server computes and REPLICATES (an input the audience cannot see)
85
+ OfflineComputable: boolean, -- root-level, and every input persists
86
+ Label: string,
87
+ }?,
88
+ Children: { [string]: SchemaNode }?,
89
+ ChildOrder: { string }?, -- sorted; ordinal i encodes child ChildOrder[i]
90
+ ChildOrdinal: { [string]: number }?,
91
+ Parent: SchemaNode?,
92
+ AnyChild: SchemaNode?, -- dynamic-key child: the compiled element schema on an
93
+ -- ArrayOf/DictOf node (set at compile time), otherwise a generic pseudo-node
94
+ -- synthesized lazily on first access
95
+ HasPacked: boolean?, -- true if a declared descendant stores a different shape than
96
+ -- it reads (a packed datatype buffer, a Scribe.Big pair); lets container reads
97
+ -- skip the deep-unpack walk when there is nothing to convert
98
+ -- Scribe.ArrayOf / Scribe.DictOf. `Container` is the discriminator (nil on every
99
+ -- other node, untyped dynamic containers included); `IsElement` marks the compiled
100
+ -- element root under AnyChild; `Closed` marks an element record whose field set is
101
+ -- fixed, so an undeclared key is a write error rather than a synthesized `any` child.
102
+ Container: ("Array" | "Dict")?,
103
+ IsElement: boolean?,
104
+ Closed: boolean?,
105
+ -- Scribe.Optional: the field may legitimately be absent. Its Default is nil, so
106
+ -- it is not seeded into a new profile and not filled into a partial element.
107
+ Nullable: boolean?,
108
+ -- Element default with ServerOnly subtrees removed, used when a client mirror
109
+ -- materializes a fresh entry (see Node.resolveContainer).
110
+ ClientDefault: any,
111
+ MaxItems: number?,
112
+ Evict: string?,
113
+ Unique: boolean?,
114
+ KeyType: string?,
115
+ MaxKeys: number?,
116
+ MaxKeyLength: number?,
117
+ }
118
+
119
+ export type Compiled = {
120
+ Root: SchemaNode,
121
+ ById: { [number]: SchemaNode },
122
+ NodeCount: number,
123
+ Hash: number,
124
+ RootOrder: { string },
125
+ -- Whether the template declares a Scribe.Shared root. Replication uses it to skip
126
+ -- the per-player work only Shared data justifies: an O(N) broadcast on every leave
127
+ -- and an O(N) entry scan on every join.
128
+ HasShared: boolean,
129
+ DynamicNodes: { SchemaNode }, -- fields with a Scribe.Dynamic factory, in id order
130
+ DerivedNodes: { SchemaNode }, -- Scribe.Derived fields in topological order
131
+ -- pathKey of an input (or any ancestor of one) -> the fields to recompute. A
132
+ -- write looks up its own pathKey and finds every dependent in one hop.
133
+ DerivedByWrite: { [string]: { SchemaNode } },
134
+ -- Root views. Player is the compiled itself when no store is declared; views share
135
+ -- everything but Root, RootOrder and HasShared by reference.
136
+ Views: { Player: Compiled, Store: Compiled? },
137
+ Config: CompileConfig,
138
+ }
139
+
140
+ export type CompileConfig = {
141
+ ReplicateRobuxLog: boolean?,
142
+ ReplicateInGameLog: boolean?,
143
+ -- Roots owned by the server, not a player. Same compile state as the player roots,
144
+ -- so one id space and one hash.
145
+ ServerStore: { [string]: any }?,
146
+ }
147
+
148
+ local RESERVED_ROOT = "_Scribe"
149
+ local SESSION_ROOT = "_ScribeSession"
150
+ -- Cooldown slots share the flat _Scribe.Timed dict with timed-field pathKeys and
151
+ -- are namespaced by this prefix. Owned here (not in Server/Timed) so Compile can
152
+ -- reject a root field that would alias a cooldown slot.
153
+ local COOLDOWN_PREFIX = "@cd|"
154
+ -- Online-only cooldowns share that dict but hold remaining seconds rather than a
155
+ -- deadline. The prefixes differ at byte 4 ("|" vs "o"), so no wall-clock key text can
156
+ -- ever spell an online slot.
157
+ local ONLINE_COOLDOWN_PREFIX = "@cdo|"
158
+
159
+ local Template = {}
160
+
161
+ Template.FLOAT_F64 = FLOAT_F64
162
+ Template.FLOAT_F32 = FLOAT_F32
163
+ Template.FLOAT_Q8 = FLOAT_Q8
164
+ Template.FLOAT_Q16 = FLOAT_Q16
165
+ Template.FLOAT_Q32 = FLOAT_Q32
166
+ Template.F32_MAX = F32_MAX
167
+ Template.F32_MIN_NORMAL = F32_MIN_NORMAL
168
+ Template.Q_MAX_STEPS = Q_MAX_STEPS
169
+ Template.QuantSteps = quantSteps
170
+
171
+ --- The wire width `node` takes. Total by construction: every shape the validator
172
+ --- refuses answers FLOAT_F64 here, so a node that somehow reached the encoder
173
+ --- unvalidated gets the lossless encoding rather than a corrupt one.
174
+ function Template.FloatPlan(node: SchemaNode): number
175
+ local p = node.Precision
176
+ if p == nil then
177
+ return FLOAT_F64
178
+ end
179
+ if p == "f32" then
180
+ return FLOAT_F32
181
+ end
182
+ local min, max = node.Min, node.Max
183
+ if type(p) ~= "number" or p ~= p or p <= 0 or p == math.huge or min == nil or max == nil or max < min then
184
+ return FLOAT_F64
185
+ end
186
+ local steps = quantSteps(min, max, p)
187
+ if steps < 256 then
188
+ return FLOAT_Q8
189
+ elseif steps < 65536 then
190
+ return FLOAT_Q16
191
+ elseif steps <= Q_MAX_STEPS then
192
+ return FLOAT_Q32
193
+ end
194
+ return FLOAT_F64
195
+ end
196
+ Template.RESERVED_ROOT = RESERVED_ROOT
197
+ Template.SESSION_ROOT = SESSION_ROOT
198
+ Template.COOLDOWN_PREFIX = COOLDOWN_PREFIX
199
+ Template.ONLINE_COOLDOWN_PREFIX = ONLINE_COOLDOWN_PREFIX
200
+
201
+ local function compileError(path: { string }, message: string): never
202
+ error(`Scribe: template error at "{table.concat(path, ".")}": {message}`, 0)
203
+ end
204
+
205
+ -- A Scribe declarator anywhere inside an array-like container would be silently
206
+ -- stored as its raw marker table instead of compiled into a schema field, so reject
207
+ -- the shape outright. A valid data blob contains no markers, so scanning it is safe.
208
+ local function rejectNestedMarkers(path: { string }, value: any)
209
+ local function walk(v: any, where: string)
210
+ if Marker.inspect(v) ~= nil then
211
+ compileError(
212
+ path,
213
+ `"{where}" is a Scribe declarator inside an array-like container, which stores its `
214
+ .. `entries as opaque data and so has no schema for the declarator to compile into. `
215
+ .. `Declare the element shape instead: Scribe.ArrayOf(\{ ... }) for a list, or `
216
+ .. `Scribe.DictOf(\{ ... }) for a string-keyed table. That is also the only way to `
217
+ .. `store a Roblox datatype inside a container`
218
+ )
219
+ elseif type(v) == "table" then
220
+ for k, child in v do
221
+ walk(child, if where == "" then tostring(k) else where .. "." .. tostring(k))
222
+ end
223
+ end
224
+ end
225
+ for k, v in value do
226
+ walk(v, tostring(k))
227
+ end
228
+ end
229
+
230
+ -- Declarators that cannot appear inside an ArrayOf/DictOf element shape, each with
231
+ -- the reason it is unsound there. Scanned over the RAW shape at compile time so a
232
+ -- bad template fails at startup rather than behaving subtly wrong per element.
233
+ local FORBIDDEN_IN_ELEMENT: { [string]: string } = {
234
+ Timed = "timed state is keyed by path and element paths are positional (an array index shifts on every"
235
+ .. " insert or remove), so a running timer would resolve to the wrong element; store an expiry field"
236
+ .. " on the element instead",
237
+ Dynamic = "a Scribe.Dynamic factory seeds a field once per brand-new profile, and elements do not exist"
238
+ .. " then; generate per-element values at Insert time",
239
+ Derived = "a derived field reads a fixed set of declared paths, and element paths are positional (an array"
240
+ .. " index shifts on every insert or remove), so its inputs would name a different entry after every"
241
+ .. " structural write; derive at the root from a field the element writes instead",
242
+ Shared = "Scribe.Shared is only supported on root fields",
243
+ Session = "Scribe.Session is only supported on root fields",
244
+ }
245
+
246
+ local function rejectInElementShape(path: { string }, shape: any)
247
+ local function walk(v: any)
248
+ if type(v) ~= "table" then
249
+ return
250
+ end
251
+ local kind, default, meta = Marker.inspect(v)
252
+ if kind ~= nil then
253
+ local reason = FORBIDDEN_IN_ELEMENT[kind :: string]
254
+ if reason then
255
+ compileError(path, `Scribe.{kind} is not supported inside an element shape: {reason}`)
256
+ end
257
+ if kind == "ArrayOf" or kind == "DictOf" or kind == "SetOf" or kind == "MapOf" then
258
+ -- A nested container hides its shape in Meta.Element, not in Default.
259
+ walk(if meta then meta.Element else nil)
260
+ else
261
+ walk(default)
262
+ end
263
+ return
264
+ end
265
+ for _, child in v do
266
+ walk(child)
267
+ end
268
+ end
269
+ walk(shape)
270
+ end
271
+
272
+ -- Whether reading this node (or anything below it) has to convert a stored shape back
273
+ -- to its read shape: a datatype packs to a buffer, a Scribe.Big stores a
274
+ -- { mantissa, exponent } pair. One predicate, so a third such type cannot reach some
275
+ -- read paths and miss the others.
276
+ local function isPacked(node: SchemaNode): boolean
277
+ return node.ValueType == "datatype" or node.ValueType == "big" or node.HasPacked == true
278
+ end
279
+
280
+ local function checkContainerCap(path: { string }, label: string, value: any)
281
+ if value == nil then
282
+ return
283
+ end
284
+ if type(value) ~= "number" or value % 1 ~= 0 or value < 1 then
285
+ compileError(path, `{label} must be a positive integer`)
286
+ end
287
+ end
288
+
289
+ -- Element subtrees are addressed only through AnyChild, never by field id, so they
290
+ -- carry none. See the id-less rationale at the ArrayOf/DictOf branch in buildNode.
291
+ local function clearIds(node: SchemaNode)
292
+ node.Id = nil
293
+ if node.Children then
294
+ for _, child in node.Children do
295
+ clearIds(child)
296
+ end
297
+ end
298
+ if node.AnyChild then
299
+ clearIds(node.AnyChild)
300
+ end
301
+ end
302
+
303
+ -- Deepest declared level below and including `node`, counting a nested container's
304
+ -- element as one further level (an element is reached through a key of its own).
305
+ local function declaredDepth(node: SchemaNode): number
306
+ local deepest = 0
307
+ if node.Children then
308
+ for _, child in node.Children do
309
+ local d = declaredDepth(child)
310
+ if d > deepest then
311
+ deepest = d
312
+ end
313
+ end
314
+ end
315
+ if node.AnyChild then
316
+ local d = declaredDepth(node.AnyChild)
317
+ if d > deepest then
318
+ deepest = d
319
+ end
320
+ end
321
+ return deepest + 1
322
+ end
323
+
324
+ -- Element default with ServerOnly subtrees dropped, mirroring BuildDefaults'
325
+ -- buildClient. A client mirror seeds fresh entries from this, so that writing one
326
+ -- field of a new element cannot conjure a ServerOnly sibling's declared value.
327
+ local function buildClientDefault(node: SchemaNode): any
328
+ if node.Visibility == "ServerOnly" then
329
+ return nil
330
+ end
331
+ if node.Kind ~= "table" or not node.Children then
332
+ return Util.deepClone(node.Default)
333
+ end
334
+ local out = {}
335
+ for key, child in node.Children do
336
+ local value = buildClientDefault(child)
337
+ if value ~= nil then
338
+ out[key] = value
339
+ end
340
+ end
341
+ return out
342
+ end
343
+
344
+ local function checkDefaultValue(path: { string }, value: any)
345
+ local t = typeof(value)
346
+ if t == "table" then
347
+ local hasNum, hasStr = false, false
348
+ for k, v in value do
349
+ local kt = type(k)
350
+ if kt ~= "string" and kt ~= "number" then
351
+ compileError(path, `unsupported key type "{kt}"`)
352
+ end
353
+ hasNum = hasNum or kt == "number"
354
+ hasStr = hasStr or kt == "string"
355
+ if hasNum and hasStr then
356
+ -- A mixed table cannot be JSON-encoded, so the very first save of a
357
+ -- new profile seeded with this default would fail outright.
358
+ compileError(path, "a default cannot mix array indices and string keys (it would fail the save)")
359
+ end
360
+ -- A string default key becomes a persisted JSON object key, so it must
361
+ -- be valid UTF-8 or the very first save of a new profile fails.
362
+ if kt == "string" and not Util.isUtf8(k :: string) then
363
+ compileError(path, `default key "{k}" contains invalid UTF-8 bytes`)
364
+ end
365
+ local childPath = table.clone(path)
366
+ table.insert(childPath, tostring(k))
367
+ checkDefaultValue(childPath, v)
368
+ end
369
+ elseif t ~= "boolean" and t ~= "number" and t ~= "string" and t ~= "buffer" then
370
+ compileError(path, `unsupported value type "{t}" (only booleans, numbers, strings, buffers and tables persist)`)
371
+ elseif t == "number" and (value ~= value or value == math.huge or value == -math.huge) then
372
+ compileError(path, "NaN/inf default")
373
+ elseif t == "string" and not Util.isUtf8(value :: string) then
374
+ -- A string default is seeded verbatim into every new profile and saved.
375
+ compileError(path, "string default contains invalid UTF-8 bytes")
376
+ end
377
+ end
378
+
379
+ -- Builds one schema node from a (possibly marker-wrapped) template value.
380
+ type PendingDerived = { Node: SchemaNode, InputPaths: { string }, Compute: (...any) -> any }
381
+ -- `Derived` is absent on the throwaway state an element shape compiles against; a
382
+ -- derived field is refused inside an element shape before it could be reached.
383
+ type CompileState = { NextId: number, ById: { [number]: SchemaNode }, Derived: { PendingDerived }? }
384
+
385
+ local function buildNode(
386
+ state: CompileState,
387
+ name: string?,
388
+ rawValue: any,
389
+ path: { string },
390
+ inheritedVisibility: Visibility,
391
+ inheritedPersist: boolean,
392
+ parent: SchemaNode?
393
+ ): SchemaNode
394
+ -- A field name is a persisted JSON object key, so reject invalid UTF-8 at compile
395
+ -- time rather than at the first save.
396
+ if name ~= nil and not Util.isUtf8(name) then
397
+ compileError(path, `field name contains invalid UTF-8 bytes`)
398
+ end
399
+
400
+ local visibility: Visibility = inheritedVisibility
401
+ local persist: boolean = inheritedPersist
402
+ -- Markers seen on THIS node, tracked separately from the inherited values so a
403
+ -- nested ServerOnly under a ServerOnly parent is still allowed. Replication and
404
+ -- persistence are independent axes: one of each combines, two of the same do not.
405
+ local replicationSeen: string? = nil
406
+ local sessionSeen = false
407
+ local timed = false
408
+ local derivedInputs: { string }? = nil
409
+ local derivedCompute: ((...any) -> any)? = nil
410
+ local dynamicSeen = false
411
+ local meta: Marker.Meta? = nil
412
+ local valueType: string? = nil
413
+ local containerKind: ("Array" | "Dict")? = nil
414
+ local containerDeclarator: string? = nil
415
+ local nullable = false
416
+ local value = rawValue
417
+
418
+ -- Unwrap (possibly nested) markers, e.g. Scribe.Session wrapping a table
419
+ -- whose fields use Scribe.Int.
420
+ while true do
421
+ local kind, default, markerMeta = Marker.inspect(value)
422
+ if kind == nil then
423
+ break
424
+ end
425
+ if kind == "Session" then
426
+ if sessionSeen then
427
+ compileError(path, "Scribe.Session is already applied to this field")
428
+ end
429
+ sessionSeen = true
430
+ if #path > 1 then
431
+ compileError(path, "Scribe.Session is only supported on root fields")
432
+ end
433
+ persist = false
434
+ elseif kind == "ServerOnly" or kind == "Shared" then
435
+ -- A field has ONE replication target, so these two cannot both apply:
436
+ -- letting the inner win makes Scribe.Shared(Scribe.ServerOnly(x)) broadcast
437
+ -- a field the outer wrapper says nobody should receive.
438
+ if replicationSeen ~= nil then
439
+ compileError(
440
+ path,
441
+ `Scribe.{replicationSeen} cannot wrap Scribe.{kind}: a field has one replication target, `
442
+ .. `not two. Combine either one with Scribe.Session instead, which sets whether it saves.`
443
+ )
444
+ end
445
+ replicationSeen = kind
446
+ if kind == "Shared" and #path > 1 then
447
+ compileError(path, "Scribe.Shared is only supported on root fields")
448
+ end
449
+ visibility = kind :: Visibility
450
+ elseif kind == "Timed" then
451
+ timed = true
452
+ elseif kind == "Int" then
453
+ valueType = "int"
454
+ meta = markerMeta
455
+ elseif kind == "Number" then
456
+ valueType = "number"
457
+ meta = markerMeta
458
+ elseif kind == "Big" then
459
+ valueType = "big"
460
+ meta = markerMeta
461
+ elseif kind == "String" then
462
+ valueType = "string"
463
+ meta = markerMeta
464
+ elseif kind == "Enum" then
465
+ valueType = "enum"
466
+ meta = markerMeta
467
+ elseif kind == "Flags" then
468
+ valueType = "flags"
469
+ meta = markerMeta
470
+ elseif kind == "Datatype" then
471
+ valueType = "datatype"
472
+ meta = markerMeta
473
+ elseif kind == "Optional" then
474
+ -- Wraps another declarator: keep unwrapping so the inner type and bounds
475
+ -- still compile, and drop the default to nil at the end of buildNode.
476
+ nullable = true
477
+ elseif kind == "ArrayOf" or kind == "DictOf" or kind == "SetOf" or kind == "MapOf" then
478
+ -- The element shape lives in Meta.Element and the marker's Default is nil,
479
+ -- so the `value = default` below ends the unwrap loop here. A SetOf is an
480
+ -- Array container with a uniqueness invariant on top, so it reuses the
481
+ -- whole element schema, wire and validation path.
482
+ containerKind = if kind == "DictOf" or kind == "MapOf" then "Dict" else "Array"
483
+ -- Keep the declarator the USER wrote: containerKind collapses SetOf into
484
+ -- Array and MapOf into Dict, so error text built from it names a declarator
485
+ -- the author never used.
486
+ containerDeclarator = `Scribe.{kind}`
487
+ meta = markerMeta
488
+ elseif kind == "Derived" then
489
+ -- A derived field is computed, never written, never persisted. Its Default is
490
+ -- the output declarator, so the loop keeps unwrapping into it and the
491
+ -- type/bounds machinery below is reached unchanged.
492
+ if derivedInputs ~= nil then
493
+ compileError(path, "Scribe.Derived is already applied to this field")
494
+ end
495
+ local inputs = if markerMeta then markerMeta.Inputs else nil
496
+ local compute = if markerMeta then markerMeta.Compute else nil
497
+ if type(inputs) ~= "table" then
498
+ compileError(path, "Scribe.Derived requires a table of input paths")
499
+ end
500
+ if type(compute) ~= "function" then
501
+ compileError(path, "Scribe.Derived requires a compute function")
502
+ end
503
+ -- Persistence is per ROOT (see Node.storeFor), so a derived field under a
504
+ -- persisted root would be written into profile.Data and saved. A root field
505
+ -- becomes non-persisted here, exactly as Scribe.Session would; anything
506
+ -- deeper has to already be.
507
+ if #path == 1 then
508
+ persist = false
509
+ elseif persist then
510
+ compileError(
511
+ path,
512
+ `a derived field is never persisted, so it must be a root field or live inside a `
513
+ .. `Scribe.Session root ("{path[1]}" is persisted)`
514
+ )
515
+ end
516
+ derivedInputs = inputs :: { string }
517
+ derivedCompute = compute :: (...any) -> any
518
+ elseif kind == "Dynamic" then
519
+ dynamicSeen = true
520
+ -- `default` is the sample (the factory ran once at declaration). Infer the
521
+ -- field type from it and carry the factory forward.
522
+ if default == nil then
523
+ compileError(path, "Scribe.Dynamic factory must return a non-nil value")
524
+ end
525
+ -- Dynamic seeds into the persistent store on a brand-new profile, but
526
+ -- Session data lives in a separate store rebuilt from its default every
527
+ -- session, so a Session+Dynamic seed would land in the wrong store.
528
+ if not persist then
529
+ compileError(
530
+ path,
531
+ "Scribe.Dynamic is not supported on a Session field; generate per-session values in OnPlayerInit instead"
532
+ )
533
+ end
534
+ local factory = if markerMeta then markerMeta.Factory else nil
535
+ local sampleType = typeof(default)
536
+ if Datatypes.IsSupported(sampleType) then
537
+ valueType = "datatype"
538
+ meta = { Datatype = sampleType, Factory = factory } :: Marker.Meta
539
+ elseif type(default) == "table" then
540
+ compileError(path, "Scribe.Dynamic only wraps leaf values (numbers, strings, datatypes, ...)")
541
+ else
542
+ meta = { Factory = factory } :: Marker.Meta
543
+ end
544
+ end
545
+ value = default
546
+ end
547
+
548
+ -- Wrapper combinations that contradict what a derived field IS. Checked after the
549
+ -- unwrap loop so the order the user wrote them in does not matter.
550
+ if derivedInputs ~= nil then
551
+ if sessionSeen then
552
+ compileError(path, "Scribe.Session is redundant on a derived field: a derived field never persists")
553
+ end
554
+ if timed then
555
+ compileError(path, "Scribe.Timed cannot wrap a derived field: a derived value has no expiry, only inputs")
556
+ end
557
+ if dynamicSeen then
558
+ compileError(
559
+ path,
560
+ "Scribe.Dynamic cannot wrap a derived field: a factory seeds a stored value, and a derived field "
561
+ .. "stores nothing"
562
+ )
563
+ end
564
+ if nullable then
565
+ compileError(
566
+ path,
567
+ "Scribe.Optional cannot wrap a derived field: its value is whatever the compute function returns"
568
+ )
569
+ end
570
+ if containerKind ~= nil then
571
+ compileError(
572
+ path,
573
+ `Scribe.Derived cannot wrap {containerDeclarator or "a container"}: a derived field produces one `
574
+ .. "scalar value"
575
+ )
576
+ end
577
+ end
578
+
579
+ -- Scribe.ArrayOf / Scribe.DictOf: a dynamic container carrying a compiled element
580
+ -- schema. Returns early, before the leaf and default machinery below: the container
581
+ -- declares no data of its own, and its element shape hangs off AnyChild, the node
582
+ -- every dynamic key resolves through (Template.ChildSchema).
583
+ if containerKind ~= nil then
584
+ local declarator = containerDeclarator or `Scribe.{containerKind}Of`
585
+ local elementShape = if meta then meta.Element else nil
586
+ if elementShape == nil then
587
+ compileError(path, `{declarator} requires an element shape`)
588
+ end
589
+ if timed then
590
+ compileError(path, `Scribe.Timed cannot wrap {declarator}`)
591
+ end
592
+ if nullable then
593
+ compileError(
594
+ path,
595
+ `Scribe.Optional cannot wrap {declarator}; an empty container is already the absent case`
596
+ )
597
+ end
598
+ rejectInElementShape(path, elementShape)
599
+ checkContainerCap(path, "MaxItems", meta and meta.MaxItems)
600
+ checkContainerCap(path, "MaxKeys", meta and meta.MaxKeys)
601
+ checkContainerCap(path, "MaxKeyLength", meta and meta.MaxKeyLength)
602
+ local evict = meta and meta.Evict
603
+ if evict ~= nil then
604
+ if evict ~= "Front" and evict ~= "Back" then
605
+ compileError(path, `Scribe.ArrayOf Evict must be "Front" or "Back", got {tostring(evict)}`)
606
+ end
607
+ -- Evict has nothing to drop from without a cap, so a bare Evict is a
608
+ -- config mistake rather than a no-op.
609
+ if not (meta and meta.MaxItems) then
610
+ compileError(path, "Scribe.ArrayOf Evict requires MaxItems")
611
+ end
612
+ end
613
+
614
+ local node: SchemaNode = {
615
+ Id = state.NextId,
616
+ Name = name,
617
+ Path = table.clone(path),
618
+ Kind = "table",
619
+ ValueType = "table",
620
+ Visibility = visibility,
621
+ Persist = persist,
622
+ Timed = false,
623
+ Container = containerKind :: "Array" | "Dict",
624
+ MaxItems = meta and meta.MaxItems,
625
+ Evict = meta and meta.Evict,
626
+ Unique = meta and meta.Unique,
627
+ KeyType = meta and meta.KeyType,
628
+ MaxKeys = meta and meta.MaxKeys,
629
+ MaxKeyLength = meta and meta.MaxKeyLength,
630
+ Default = {},
631
+ Parent = parent,
632
+ }
633
+ state.ById[state.NextId :: number] = node
634
+ state.NextId += 1
635
+ if state.NextId > 65535 then
636
+ error("Scribe: template exceeds 65535 static fields", 0)
637
+ end
638
+
639
+ -- Compile the element against a throwaway id counter, then strip the ids. Element
640
+ -- fields are reachable only through AnyChild, while Template.Resolve follows
641
+ -- Children and Wire.EncodePath sources ids from it, so an id here would be
642
+ -- unaddressable at best and a decoder collision at worst.
643
+ local elementPath = table.clone(path)
644
+ table.insert(elementPath, "[]")
645
+ local element = buildNode({ NextId = 0, ById = {} }, nil, elementShape, elementPath, visibility, persist, node)
646
+ clearIds(element)
647
+ element.IsElement = true
648
+ if element.Children and next(element.Children) == nil then
649
+ compileError(path, `{declarator} element shape declares no fields`)
650
+ end
651
+ -- A declared record has a fixed field set at EVERY depth: an undeclared key on
652
+ -- the element or on any nested sub-record is a write error. Nested containers
653
+ -- ran this same post-processing in their own buildNode call, so the walk stops
654
+ -- at container boundaries.
655
+ local function closeRecords(n: SchemaNode)
656
+ if n.Container == nil and n.Children then
657
+ if next(n.Children) ~= nil then
658
+ n.Closed = true
659
+ end
660
+ for _, child in n.Children do
661
+ closeRecords(child)
662
+ end
663
+ end
664
+ end
665
+ closeRecords(element)
666
+ -- A set stores its members deduplicated and sorted, so the element has to be
667
+ -- orderable. Anything else compiles clean, accepts the first Add, then throws a
668
+ -- bare "attempt to compare table < table" on the second.
669
+ if node.Unique then
670
+ local vt = element.ValueType
671
+ if not (vt == "int" or vt == "number" or vt == "string" or vt == "enum") then
672
+ -- A Flags element carries Children = {}, so "has children" alone would
673
+ -- call it a record. Name the declarator's own value type first.
674
+ local kind
675
+ if vt == "table" and element.Container ~= nil then
676
+ kind = "nested container"
677
+ elseif vt == "table" then
678
+ kind = "record"
679
+ else
680
+ kind = vt
681
+ end
682
+ compileError(
683
+ path,
684
+ `Scribe.SetOf element must be an Int, Number, String or Enum, got a {kind}: members are `
685
+ .. "compared by value and stored in a sorted canonical order. Use Scribe.ArrayOf, or "
686
+ .. "hold a scalar identity field"
687
+ )
688
+ end
689
+ end
690
+ element.ClientDefault = buildClientDefault(element)
691
+ node.AnyChild = element
692
+ node.HasPacked = isPacked(element)
693
+
694
+ local deepest = #path + declaredDepth(element)
695
+ if deepest > Util.MAX_VALUE_DEPTH then
696
+ compileError(
697
+ path,
698
+ `element shape nests {deepest} levels deep, past the {Util.MAX_VALUE_DEPTH}-level write limit`
699
+ )
700
+ end
701
+
702
+ return node
703
+ end
704
+
705
+ local datatypeName: string? = nil
706
+ local datatypePrecision: string? = nil
707
+ if valueType == "datatype" then
708
+ datatypeName = meta and meta.Datatype
709
+ if not datatypeName or not Datatypes.IsSupported(datatypeName) then
710
+ compileError(path, `unsupported datatype declarator`)
711
+ end
712
+ if typeof(value) ~= datatypeName then
713
+ compileError(path, `default must be a {datatypeName}, got {typeof(value)}`)
714
+ end
715
+ -- Refused HERE, before the default is packed, rather than in the
716
+ -- declarator-sanity block below: Datatypes.Pack validates the argument itself
717
+ -- and would throw a raw, path-less error on the very next line.
718
+ local declared = meta and meta.Precision
719
+ if declared ~= nil then
720
+ local accepted = Datatypes.PrecisionValues(datatypeName :: string)
721
+ if not accepted then
722
+ compileError(
723
+ path,
724
+ `Scribe.{datatypeName} has no Precision option`
725
+ .. ` (only Scribe.Number and Scribe.CFrame take one)`
726
+ )
727
+ elseif type(declared) ~= "string" or not table.find(accepted, declared :: string) then
728
+ local offered = table.concat(accepted, '" or "')
729
+ compileError(path, `Scribe.{datatypeName} Precision must be "{offered}", got {tostring(declared)}`)
730
+ end
731
+ datatypePrecision = declared :: string
732
+ end
733
+ -- Profile data only ever holds the packed form.
734
+ value = Datatypes.Pack(datatypeName :: string, value, datatypePrecision)
735
+ end
736
+
737
+ -- checkDefaultValue validates raw persistable leaf data. Run it for leaves and for
738
+ -- array-like default blobs, whose elements are stored as data rather than recursed
739
+ -- as schema. A named container's children are validated when buildNode recurses into
740
+ -- them; here `value` still holds their un-stripped markers, so walking the whole
741
+ -- container would wrongly reject valid nested declarators.
742
+ if type(value) ~= "table" or Util.hasNumericKeys(value) then
743
+ -- Marker scan FIRST: a declarator holding a non-persistable default would
744
+ -- otherwise trip checkDefaultValue's generic "unsupported value type" on the
745
+ -- marker's raw .Default and bury the real problem, which is the declarator
746
+ -- being inside an array at all.
747
+ if type(value) == "table" then
748
+ rejectNestedMarkers(path, value)
749
+ end
750
+ checkDefaultValue(path, value)
751
+ end
752
+
753
+ local node: SchemaNode = {
754
+ Id = state.NextId,
755
+ Name = name,
756
+ Path = table.clone(path),
757
+ Kind = if type(value) == "table" then "table" else "leaf",
758
+ ValueType = (valueType or (if type(value) == "table" then "table" else type(value))) :: any,
759
+ Visibility = visibility,
760
+ Persist = persist,
761
+ Timed = timed,
762
+ Datatype = datatypeName,
763
+ Default = nil,
764
+ Parent = parent,
765
+ }
766
+ state.ById[state.NextId :: number] = node
767
+ state.NextId += 1
768
+ if state.NextId > 65535 then
769
+ error("Scribe: template exceeds 65535 static fields", 0)
770
+ end
771
+
772
+ if meta then
773
+ node.Min = meta.Min
774
+ node.Max = meta.Max
775
+ node.Precision = meta.Precision
776
+ node.MaxLength = meta.MaxLength
777
+ if meta.Members then
778
+ local members = table.clone(meta.Members)
779
+ local index: { [string]: number } = {}
780
+ for i, member in members do
781
+ if type(member) ~= "string" then
782
+ compileError(path, "enum members must be strings")
783
+ end
784
+ index[member] = i - 1
785
+ end
786
+ if #members > 255 then
787
+ compileError(path, "enums support at most 255 members")
788
+ end
789
+ node.Members = members
790
+ node.MemberIndex = index
791
+ end
792
+ end
793
+
794
+ -- Scribe.Dynamic: record the factory. Datatype results are packed (profile.Data
795
+ -- holds the packed form); other leaves pass through unchanged.
796
+ if meta and meta.Factory then
797
+ local rawFactory = meta.Factory
798
+ if datatypeName then
799
+ local dtName = datatypeName :: string
800
+ -- Always nil today: a Scribe.Dynamic datatype field is inferred from the
801
+ -- factory's sample, so there is no way to declare a Precision on one. Threaded
802
+ -- anyway, so a seeded value always lands in the form a Set would have written.
803
+ local dtPrecision = datatypePrecision
804
+ node.Factory = function()
805
+ return Datatypes.Pack(dtName, rawFactory(), dtPrecision)
806
+ end
807
+ else
808
+ node.Factory = rawFactory
809
+ end
810
+ end
811
+
812
+ -- Precision names what a field is stored and sent at, not a direction: on
813
+ -- Scribe.Number it narrows from f64, on Scribe.CFrame it widens from a lossy
814
+ -- quaternion. Anywhere else it would sit in the meta table doing nothing, so refuse
815
+ -- it. Datatype fields are exempt, having been validated above against the set their
816
+ -- codec publishes.
817
+ if node.Precision ~= nil and node.ValueType ~= "number" and node.ValueType ~= "datatype" then
818
+ compileError(
819
+ path,
820
+ `Precision is a Scribe.Number option and has no meaning on a {node.ValueType} field`
821
+ .. ` (Scribe.Int already packs from its Min/Max alone)`
822
+ )
823
+ end
824
+ if node.ValueType == "int" then
825
+ if type(value) ~= "number" or value % 1 ~= 0 then
826
+ compileError(path, "Scribe.Int default must be an integer")
827
+ end
828
+ -- Fractional bounds skew fixed-width int packing (value - Min is
829
+ -- truncated), so require integer Min/Max on Int fields.
830
+ if (node.Min ~= nil and node.Min % 1 ~= 0) or (node.Max ~= nil and node.Max % 1 ~= 0) then
831
+ compileError(path, "Scribe.Int Min/Max must be integers")
832
+ end
833
+ elseif node.ValueType == "number" then
834
+ if type(value) ~= "number" then
835
+ compileError(path, "Scribe.Number default must be a number")
836
+ end
837
+ -- A bound that cannot bound anything. A numeric literal above ~1.8e308 IS
838
+ -- math.huge, so `Max = 1e400` declares a ceiling no value can reach; NaN is worse,
839
+ -- since `value < nan` and `value > nan` are both false, disabling the very check
840
+ -- it was written to add.
841
+ if (node.Min ~= nil and not isFiniteBound(node.Min)) or (node.Max ~= nil and not isFiniteBound(node.Max)) then
842
+ compileError(path, "Scribe.Number Min/Max must be finite")
843
+ end
844
+ -- Narrowing is refused at configure time, not at runtime: the runtime answer
845
+ -- would be the encoder quietly taking the generic path, with correct bytes,
846
+ -- none of the saving, and no way to tell the narrowing never took effect.
847
+ local precision = node.Precision
848
+ if precision == "f32" then
849
+ -- Not a packing constraint (the bounds do not enter the f32 encoding) but a
850
+ -- contradiction: a bound past the binary32 range describes values the encoder
851
+ -- must refuse one by one, so the field would silently spend nine bytes at the
852
+ -- end of the range it was widened to reach.
853
+ if
854
+ (node.Min ~= nil and math.abs(node.Min) > F32_MAX)
855
+ or (node.Max ~= nil and math.abs(node.Max) > F32_MAX)
856
+ then
857
+ compileError(
858
+ path,
859
+ `Scribe.Number Precision = "f32" cannot represent a bound past {F32_MAX}`
860
+ .. ` (Min = {node.Min or "nil"}, Max = {node.Max or "nil"}); drop Precision to keep f64`
861
+ )
862
+ end
863
+ elseif precision ~= nil then
864
+ if type(precision) ~= "number" then
865
+ compileError(
866
+ path,
867
+ `Scribe.Number Precision must be "f32" or a positive number, got a {type(precision)}`
868
+ )
869
+ end
870
+ local p = precision :: number
871
+ if not isFiniteBound(p) or p <= 0 then
872
+ compileError(path, `Scribe.Number Precision must be finite and greater than zero, got {p}`)
873
+ end
874
+ -- A fixed-point grid is measured FROM Min and bounded BY Max: without both
875
+ -- there is no origin to index from and no step count to pick a width from.
876
+ if node.Min == nil or node.Max == nil then
877
+ compileError(path, `Scribe.Number Precision = {p} requires both Min and Max`)
878
+ end
879
+ local min, max = node.Min :: number, node.Max :: number
880
+ -- Min > Max is reported by the shared check below, in its own words; do
881
+ -- not pre-empt it with arithmetic on a negative range.
882
+ if max >= min then
883
+ local steps = quantSteps(min, max, p)
884
+ if steps > Q_MAX_STEPS then
885
+ compileError(
886
+ path,
887
+ `Scribe.Number range {min}..{max} needs {steps} steps of {p}, past the {Q_MAX_STEPS}`
888
+ .. ` a fixed-point field can index; widen Precision, or use Precision = "f32"`
889
+ )
890
+ end
891
+ -- The grid must be coarser than the double under it: at a large
892
+ -- magnitude a double's own spacing can exceed Precision, breaking the
893
+ -- promised error bound before the codec does anything. The step count
894
+ -- above stays small in that case, so test the bounds directly.
895
+ local extreme = math.max(math.abs(min), math.abs(max))
896
+ if extreme + p == extreme or extreme - p == extreme then
897
+ compileError(
898
+ path,
899
+ `Scribe.Number Precision = {p} is finer than a double's own spacing at {extreme},`
900
+ .. ` so the bound cannot step by it; widen Precision or narrow the range`
901
+ )
902
+ end
903
+ end
904
+ end
905
+ elseif node.ValueType == "enum" then
906
+ if not node.MemberIndex or node.MemberIndex[value] == nil then
907
+ compileError(path, "enum default must be one of its members")
908
+ end
909
+ elseif node.ValueType == "big" then
910
+ local parsed = Big.from(value)
911
+ if parsed == nil then
912
+ compileError(path, `Scribe.Big default must be a number or a numeric string, got {tostring(value)}`)
913
+ end
914
+ if node.Min ~= nil and Big.from(node.Min) == nil then
915
+ compileError(path, "Scribe.Big Min must be a number or a numeric string")
916
+ end
917
+ if node.Max ~= nil and Big.from(node.Max) == nil then
918
+ compileError(path, "Scribe.Big Max must be a number or a numeric string")
919
+ end
920
+ elseif node.ValueType == "flags" then
921
+ -- bit32 is 32 bits wide, so a 33rd member would silently fall off the wire
922
+ -- packing rather than round-tripping.
923
+ if #(node.Members :: { string }) > 32 then
924
+ compileError(path, `Scribe.Flags takes at most 32 members, got {#(node.Members :: { string })}`)
925
+ end
926
+ -- A member name is persisted verbatim and is the one persisted string with no
927
+ -- write-path guard, since it comes from the template rather than from a Set:
928
+ -- invalid UTF-8 fails the whole profile save the first time that flag is enabled.
929
+ -- A duplicate is refused because MemberIndex keeps only the last, leaving the
930
+ -- earlier bit unreachable.
931
+ local seenMember: { [string]: boolean } = {}
932
+ for _, member in node.Members :: { string } do
933
+ if type(member) ~= "string" then
934
+ compileError(path, `Scribe.Flags member names must be strings, got a {typeof(member)}`)
935
+ end
936
+ if not Util.isUtf8(member) then
937
+ compileError(
938
+ path,
939
+ `Scribe.Flags member "{member}" contains invalid UTF-8, which would fail the profile save`
940
+ )
941
+ end
942
+ if seenMember[member] then
943
+ compileError(path, `Scribe.Flags declares "{member}" twice; member names must be unique`)
944
+ end
945
+ seenMember[member] = true
946
+ end
947
+ if type(value) ~= "table" then
948
+ compileError(path, "Scribe.Flags default must be a table of member names")
949
+ end
950
+ for _, member in value :: { any } do
951
+ if not node.MemberIndex or node.MemberIndex[member] == nil then
952
+ compileError(path, `Scribe.Flags default contains "{tostring(member)}", which is not a member`)
953
+ end
954
+ end
955
+ elseif node.ValueType == "string" then
956
+ if type(value) ~= "string" then
957
+ compileError(path, "Scribe.String default must be a string")
958
+ end
959
+ -- MaxLength is a byte budget, not a comparison bound: inf or NaN leaves the field
960
+ -- silently unbounded, and a negative value is worse than a no-op, since
961
+ -- truncateUtf8 ends in string.sub(s, 1, cut) and a negative index counts from the
962
+ -- end, quietly deleting the tail of every value.
963
+ if node.MaxLength ~= nil then
964
+ local n = node.MaxLength
965
+ if not isFiniteBound(n) or n % 1 ~= 0 or n < 0 then
966
+ compileError(path, "Scribe.String MaxLength must be a non-negative integer")
967
+ end
968
+ end
969
+ end
970
+ if node.ValueType == "big" then
971
+ -- A big bound past 1.8e308 can only be written as a numeric string, so the pair
972
+ -- has to be ordered by Big.compare: a raw `>` either throws on a mixed pair or
973
+ -- orders two strings lexically, which rejects "2" < "1e50" and accepts the
974
+ -- inverted "1e50" > "2" this guard exists to catch.
975
+ if node.Min ~= nil and node.Max ~= nil then
976
+ local minBig = Big.from(node.Min) :: any
977
+ local maxBig = Big.from(node.Max) :: any
978
+ if Big.compare(minBig, maxBig) > 0 then
979
+ compileError(path, "Min > Max")
980
+ end
981
+ end
982
+ elseif node.Min and node.Max and node.Min > node.Max then
983
+ compileError(path, "Min > Max")
984
+ end
985
+ if timed and type(value) == "table" then
986
+ compileError(path, "Scribe.Timed only wraps leaf values")
987
+ end
988
+
989
+ if node.Kind == "table" then
990
+ if Util.hasNumericKeys(value) then
991
+ -- Array-like default: entries are DATA (deep-cloned, generically encoded),
992
+ -- not schema. rejectNestedMarkers already ran above and refused any
993
+ -- declarator nested in here.
994
+ node.Default = Util.deepClone(value)
995
+ else
996
+ for k in value do
997
+ -- sortedKeys would silently drop a non-string key, compiling a schema
998
+ -- missing the field with no diagnostic at all.
999
+ if type(k) ~= "string" then
1000
+ compileError(path, `record fields must have string names, got a {typeof(k)} key`)
1001
+ end
1002
+ end
1003
+ local children: { [string]: SchemaNode } = {}
1004
+ local order = Util.sortedKeys(value)
1005
+ local ordinal: { [string]: number } = {}
1006
+ local default = {}
1007
+ local hasPacked = false
1008
+ for i, key in order do
1009
+ local childPath = table.clone(path)
1010
+ table.insert(childPath, key)
1011
+ local child = buildNode(state, key, value[key], childPath, visibility, persist, node)
1012
+ children[key] = child
1013
+ ordinal[key] = i
1014
+ default[key] = child.Default
1015
+ -- Bubble the packed marker up (post-order: child is fully built).
1016
+ if isPacked(child) then
1017
+ hasPacked = true
1018
+ end
1019
+ end
1020
+ node.Children = children
1021
+ node.ChildOrder = order
1022
+ node.ChildOrdinal = ordinal
1023
+ node.Default = default
1024
+ node.HasPacked = hasPacked
1025
+ end
1026
+ elseif node.ValueType == "big" then
1027
+ -- The canonical { mantissa, exponent } form, so the schema default matches
1028
+ -- what every write produces rather than the raw declarator argument.
1029
+ node.Default = Big.toStored(Big.from(value) :: any)
1030
+ else
1031
+ node.Default = value
1032
+ end
1033
+
1034
+ -- Collected, not resolved: an input may name a root this walk has not reached
1035
+ -- yet, so Compile finishes the job once every node exists.
1036
+ if derivedInputs ~= nil then
1037
+ local collected = state.Derived
1038
+ if collected == nil then
1039
+ compileError(path, "Scribe.Derived is not supported here")
1040
+ end
1041
+ table.insert(collected :: any, {
1042
+ Node = node,
1043
+ InputPaths = derivedInputs :: { string },
1044
+ Compute = derivedCompute :: (...any) -> any,
1045
+ })
1046
+ end
1047
+
1048
+ -- Scribe.Optional: the inner declarator supplied the type and bounds; the default is
1049
+ -- dropped so the field is neither seeded into a new profile nor filled into a
1050
+ -- partial element write.
1051
+ if nullable then
1052
+ if timed then
1053
+ compileError(path, "Scribe.Optional cannot wrap Scribe.Timed: a lapsed timer restores the default")
1054
+ end
1055
+ if node.Factory then
1056
+ compileError(path, "Scribe.Optional cannot wrap Scribe.Dynamic: a factory exists to seed a value")
1057
+ end
1058
+ if node.Kind == "table" then
1059
+ compileError(path, "Scribe.Optional only wraps leaf values")
1060
+ end
1061
+ node.Nullable = true
1062
+ node.Default = nil
1063
+ end
1064
+
1065
+ return node
1066
+ end
1067
+
1068
+ -- Reserved internal roots: built server-only by default, then per-subkey
1069
+ -- visibility applied explicitly so the rules are exact.
1070
+ local function buildInternalRoots(state: any, root: SchemaNode, config: CompileConfig)
1071
+ local scribeTemplate = {
1072
+ -- GiftAims is not a second PendingGifts: a pending gift is a live intent counted
1073
+ -- against GiftMaxPending, an aim is the recipient identity that survives a stale
1074
+ -- prompt so a late receipt can still be routed. They expire on separate clocks;
1075
+ -- see the GIFT AIM block in Server/Monetization.
1076
+ GiftAims = {},
1077
+ GiftCredits = {},
1078
+ PendingGifts = {},
1079
+ Perks = {},
1080
+ ProcessedPurchaseIds = {},
1081
+ ReceiptReservations = {},
1082
+ PurchaseLogs = {
1083
+ InGame = {},
1084
+ Robux = {},
1085
+ },
1086
+ -- Exchange holds the in-flight record per exchange id; ExchangeInbox holds value
1087
+ -- settled to this player but not yet delivered onto a game path. Untyped, like
1088
+ -- PendingGifts, because a settle must not be refusable by a declared shape.
1089
+ Exchange = {},
1090
+ ExchangeInbox = {},
1091
+ Timed = {},
1092
+ -- Per periodic board: the gain baseline and the first period written, for the erase sweep.
1093
+ Boards = {},
1094
+ Version = Marker.make("Int", 1, { Min = 0 }),
1095
+ }
1096
+
1097
+ local scribeNode = buildNode(state, RESERVED_ROOT, scribeTemplate, { RESERVED_ROOT }, "ServerOnly", true, root)
1098
+ local children = scribeNode.Children :: { [string]: SchemaNode }
1099
+ local function setVisibility(node: SchemaNode, visibility: Visibility)
1100
+ node.Visibility = visibility
1101
+ if node.Children then
1102
+ for _, child in node.Children do
1103
+ setVisibility(child, visibility)
1104
+ end
1105
+ end
1106
+ end
1107
+ setVisibility(children.Perks, "Replicated")
1108
+ setVisibility(children.GiftCredits, "Replicated")
1109
+ -- Purchase logs are opt-in per kind (PurchaseLog.ReplicateRobux/InGame);
1110
+ -- the container itself only replicates when at least one kind does, so the
1111
+ -- default sends nothing at all.
1112
+ local logs = children.PurchaseLogs
1113
+ local replicateRobux = config.ReplicateRobuxLog == true
1114
+ local replicateInGame = config.ReplicateInGameLog == true
1115
+ logs.Visibility = if replicateRobux or replicateInGame then "Replicated" else "ServerOnly"
1116
+ local logChildren = logs.Children :: { [string]: SchemaNode }
1117
+ setVisibility(logChildren.Robux, (if replicateRobux then "Replicated" else "ServerOnly") :: Visibility)
1118
+ setVisibility(logChildren.InGame, (if replicateInGame then "Replicated" else "ServerOnly") :: Visibility)
1119
+
1120
+ -- _ScribeSession: never persisted, replicated to the owner. Holds the pass/Plus
1121
+ -- ownership cache, the player's own save info, and a sync flag the server flips
1122
+ -- true once the async gamepass refresh completes, so the client can await it
1123
+ -- before trusting OwnsCache (see Client/Server OwnsAsync).
1124
+ local sessionTemplate = {
1125
+ OwnsCache = {},
1126
+ SaveInfo = {},
1127
+ OwnsSynced = false,
1128
+ Timed = {},
1129
+ }
1130
+ local sessionNode = buildNode(state, SESSION_ROOT, sessionTemplate, { SESSION_ROOT }, "Replicated", false, root)
1131
+
1132
+ return scribeNode, sessionNode
1133
+ end
1134
+
1135
+ -- A DataStore serializes every object key to a JSON string, so a Scribe.MapOf with
1136
+ -- integer keys comes back holding "123" where it stored 123. The declared key type is
1137
+ -- what makes converting them back unambiguous. Runs on raw stored data before
1138
+ -- Reconcile, so every later read sees the keys the template promised.
1139
+ function Template.CoerceMapKeys(compiled: Compiled, data: any)
1140
+ local function walk(node: SchemaNode, value: any, depth: number)
1141
+ if type(value) ~= "table" or depth > 32 then
1142
+ return
1143
+ end
1144
+ if node.Container == "Dict" and node.KeyType == "integer" then
1145
+ local rename: { [string]: number }? = nil
1146
+ local blocked = false
1147
+ for key in value do
1148
+ if type(key) == "string" then
1149
+ local asNumber = tonumber(key)
1150
+ -- Only a canonical integer spelling converts. A key like "07" or
1151
+ -- "1.5" was never written by this map, so leaving it alone keeps
1152
+ -- foreign data intact rather than silently relocating it.
1153
+ if asNumber ~= nil and asNumber % 1 == 0 and tostring(asNumber) == key then
1154
+ rename = rename or {}
1155
+ (rename :: { [string]: number })[key] = asNumber
1156
+ else
1157
+ blocked = true
1158
+ end
1159
+ end
1160
+ end
1161
+ -- ALL of them or none. Converting only the canonical ones leaves the
1162
+ -- container holding a number key and a string key at once, a mixed table
1163
+ -- no DataStore will store, so every save for that profile would fail.
1164
+ if rename and not blocked then
1165
+ for from, to in rename do
1166
+ value[to] = value[from]
1167
+ value[from] = nil
1168
+ end
1169
+ end
1170
+ end
1171
+ local children = node.Children
1172
+ if children then
1173
+ for name, child in children do
1174
+ walk(child, value[name], depth + 1)
1175
+ end
1176
+ elseif node.Container ~= nil then
1177
+ for key in value do
1178
+ local element = Template.ChildSchema(node, key)
1179
+ if element then
1180
+ walk(element, value[key], depth + 1)
1181
+ end
1182
+ end
1183
+ end
1184
+ end
1185
+ walk(compiled.Root, data, 0)
1186
+ end
1187
+
1188
+ function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1189
+ local cfg: CompileConfig = config or {}
1190
+ if type(userTemplate) ~= "table" then
1191
+ error("Scribe: Template must be a table", 0)
1192
+ end
1193
+ for key in userTemplate do
1194
+ if type(key) ~= "string" then
1195
+ error("Scribe: template root keys must be strings", 0)
1196
+ end
1197
+ -- A top-level field's pathKey is just its name, so a root named "@cd|Daily"
1198
+ -- would collide with the cooldown slot of the same name. Nested fields are
1199
+ -- safe: their pathKeys always contain the \31 separator, which a cooldown key
1200
+ -- never has.
1201
+ if string.sub(key, 1, 3) == "@cd" then
1202
+ error(
1203
+ `Scribe: template may not declare a "{key}" key: the "{COOLDOWN_PREFIX}" prefix is reserved for cooldown slots`,
1204
+ 0
1205
+ )
1206
+ end
1207
+ if string.sub(key, 1, #RESERVED_ROOT) == RESERVED_ROOT then
1208
+ error(`Scribe: template may not declare a "{key}" key: the {RESERVED_ROOT} root is library-owned`, 0)
1209
+ end
1210
+ end
1211
+
1212
+ -- Held separately as well as on `state`, so the post-pass below reads it without
1213
+ -- the optionality buildNode's signature needs for the element-shape case.
1214
+ local pendingDerived: { PendingDerived } = {}
1215
+ local state: CompileState = { NextId = 1, ById = {} :: { [number]: SchemaNode }, Derived = pendingDerived }
1216
+ local root: SchemaNode = {
1217
+ Id = 0,
1218
+ Name = nil,
1219
+ Path = {},
1220
+ Kind = "table",
1221
+ ValueType = "table",
1222
+ Visibility = "Replicated",
1223
+ Persist = true,
1224
+ Timed = false,
1225
+ Default = nil,
1226
+ Parent = nil,
1227
+ }
1228
+ state.ById[0] = root
1229
+
1230
+ local children: { [string]: SchemaNode } = {}
1231
+ local userOrder = Util.sortedKeys(userTemplate)
1232
+ for _, key in userOrder do
1233
+ children[key] = buildNode(state, key, userTemplate[key], { key }, "Replicated", true, root)
1234
+ end
1235
+
1236
+ -- persist = false is what keeps these out of every save.
1237
+ local storeTemplate = cfg.ServerStore
1238
+ local storeOrder: { string } = {}
1239
+ if storeTemplate ~= nil then
1240
+ if type(storeTemplate) ~= "table" then
1241
+ error("Scribe: ServerStore must be a table", 0)
1242
+ end
1243
+ storeOrder = Util.sortedKeys(storeTemplate)
1244
+ for _, key in storeOrder do
1245
+ if type(key) ~= "string" then
1246
+ error("Scribe: ServerStore root keys must be strings", 0)
1247
+ end
1248
+ if string.sub(key, 1, 3) == "@cd" or string.sub(key, 1, #RESERVED_ROOT) == RESERVED_ROOT then
1249
+ error(`Scribe: ServerStore may not declare a "{key}" key: that prefix is library-owned`, 0)
1250
+ end
1251
+ if children[key] ~= nil then
1252
+ error(
1253
+ `Scribe: ServerStore declares "{key}", which the Template already declares. The two share `
1254
+ .. "one field-id space and one schema, so one would silently shadow the other. Rename one.",
1255
+ 0
1256
+ )
1257
+ end
1258
+ -- Caught on the declarator: it cannot be told apart after building.
1259
+ local markerKind = Marker.inspect(storeTemplate[key])
1260
+ if markerKind == "Session" then
1261
+ error(
1262
+ `Scribe: ServerStore root "{key}" is Scribe.Session. A server store is never saved, so the `
1263
+ .. "marker sets nothing that is not already true. Drop the wrapper.",
1264
+ 0
1265
+ )
1266
+ end
1267
+ local node = buildNode(state, key, storeTemplate[key], { key }, "Replicated", false, root)
1268
+ children[key] = node
1269
+
1270
+ -- Load-bearing, not tidiness: hasShared scans every child of the root, so one
1271
+ -- Shared store root switches on the whole per-player fanout.
1272
+ if node.Visibility == "Shared" then
1273
+ error(
1274
+ `Scribe: ServerStore root "{key}" is Scribe.Shared. Every store root already reaches every `
1275
+ .. "client, and a store has no owning player for Shared to name. Drop the wrapper, or use "
1276
+ .. "Scribe.ServerOnly to keep it off the wire.",
1277
+ 0
1278
+ )
1279
+ end
1280
+
1281
+ -- A deadline is swept per profile entry and a Dynamic factory is sampled per profile
1282
+ -- load. A store has neither, and both would fail silently.
1283
+ local function refuseSubtree(n: SchemaNode)
1284
+ local where = if n.Name then `"{Util.pathString(n.Path :: any)}"` else `root "{key}"`
1285
+ if n.Timed then
1286
+ error(
1287
+ `Scribe: ServerStore field {where} is Scribe.Timed. A deadline lives in a player's `
1288
+ .. "_Scribe.Timed dict and is swept per profile, so a server store has nowhere to "
1289
+ .. "hold one and nothing to expire it.",
1290
+ 0
1291
+ )
1292
+ end
1293
+ if n.Factory ~= nil then
1294
+ error(
1295
+ `Scribe: ServerStore field {where} is Scribe.Dynamic. The factory is sampled once when `
1296
+ .. "a brand-new profile is created, and a store has no profile. Set the value from "
1297
+ .. "your own code after the bundle is built.",
1298
+ 0
1299
+ )
1300
+ end
1301
+ if n.Children then
1302
+ for _, child in n.Children do
1303
+ refuseSubtree(child)
1304
+ end
1305
+ end
1306
+ if n.AnyChild then
1307
+ refuseSubtree(n.AnyChild)
1308
+ end
1309
+ end
1310
+ refuseSubtree(node)
1311
+ end
1312
+ end
1313
+
1314
+ local scribeNode, sessionNode = buildInternalRoots(state, root, cfg)
1315
+ children[RESERVED_ROOT] = scribeNode
1316
+ children[SESSION_ROOT] = sessionNode
1317
+
1318
+ local order = table.clone(userOrder)
1319
+ for _, key in storeOrder do
1320
+ table.insert(order, key)
1321
+ end
1322
+ table.insert(order, RESERVED_ROOT)
1323
+ table.insert(order, SESSION_ROOT)
1324
+ table.sort(order)
1325
+
1326
+ local ordinal: { [string]: number } = {}
1327
+ for i, key in order do
1328
+ ordinal[key] = i
1329
+ end
1330
+ root.Children = children
1331
+ root.ChildOrder = order
1332
+ root.ChildOrdinal = ordinal
1333
+ -- The root node is hand-built here rather than by buildNode, so bubble its
1334
+ -- HasPacked flag the same way (else a whole-data Get()/Clone() on the root
1335
+ -- accessor would leak packed buffers for a ROOT-level datatype field).
1336
+ local rootHasPacked = false
1337
+ for _, child in children do
1338
+ if isPacked(child) then
1339
+ rootHasPacked = true
1340
+ break
1341
+ end
1342
+ end
1343
+ root.HasPacked = rootHasPacked
1344
+
1345
+ -- Scribe.Shared cannot appear below a root field, so this scan is exhaustive.
1346
+ local hasShared = false
1347
+ for _, child in children do
1348
+ if child.Visibility == "Shared" then
1349
+ hasShared = true
1350
+ break
1351
+ end
1352
+ end
1353
+
1354
+ -- Derived fields, once every node they could name exists: resolve the input
1355
+ -- paths, order the graph, decide who computes each field, and seed the defaults.
1356
+ -- Before the hash fold, which folds the result.
1357
+ local derivedNodes: { SchemaNode } = {}
1358
+ local derivedByWrite: { [string]: { SchemaNode } } = {}
1359
+ if #pendingDerived > 0 then
1360
+ local reservedRoots = { [RESERVED_ROOT] = true, [SESSION_ROOT] = true }
1361
+ derivedNodes, derivedByWrite =
1362
+ DerivedModule.Resolve(root, pendingDerived :: any, reservedRoots, compileError :: any)
1363
+ DerivedModule.SeedDefaults(derivedNodes :: any, compileError :: any)
1364
+
1365
+ -- A derived field recomputes on whichever tree took the write, so an input on the
1366
+ -- far side would settle into the wrong one.
1367
+ if storeTemplate ~= nil then
1368
+ local function isStoreRoot(path: { any }): boolean
1369
+ return #path > 0 and storeTemplate[path[1]] ~= nil
1370
+ end
1371
+ for _, node in derivedNodes do
1372
+ local spec = (node :: any).Derived
1373
+ if spec ~= nil and spec.Inputs ~= nil then
1374
+ local outputInStore = isStoreRoot(node.Path)
1375
+ for _, input in spec.Inputs do
1376
+ if isStoreRoot(input.Path) ~= outputInStore then
1377
+ error(
1378
+ `Scribe: derived field "{Util.pathString(node.Path)}" reads `
1379
+ .. `"{Util.pathString(input.Path)}", which is on the other side of the `
1380
+ .. "ServerStore boundary. A derived field recomputes on whichever tree took "
1381
+ .. "the write, and the two trees hold different data.",
1382
+ 0
1383
+ )
1384
+ end
1385
+ end
1386
+ end
1387
+ end
1388
+ end
1389
+ -- A record's Default table was composed from its children while they were
1390
+ -- built, so a nested derived field's freshly seeded default has to be written
1391
+ -- back up: anything reading a record's Default directly would otherwise see
1392
+ -- the output declarator's default rather than the computed one.
1393
+ for _, node in derivedNodes do
1394
+ local child = node
1395
+ local parent = node.Parent
1396
+ while parent ~= nil and type(parent.Default) == "table" and child.Name ~= nil do
1397
+ (parent.Default :: { [string]: any })[child.Name :: string] = child.Default
1398
+ child = parent
1399
+ parent = parent.Parent
1400
+ end
1401
+ end
1402
+ end
1403
+
1404
+ -- Folded into the schema hash below: Transmit decides whether the field crosses
1405
+ -- the wire at all, and the input set decides what a locally computing client
1406
+ -- reads, so a drift in either has to fail the handshake rather than diverge.
1407
+ local function derivedSig(node: SchemaNode): string
1408
+ local spec = node.Derived
1409
+ if spec == nil then
1410
+ return "nil"
1411
+ end
1412
+ local ids = table.create(#spec.Inputs)
1413
+ for i, input in spec.Inputs do
1414
+ ids[i] = tostring(input.Id)
1415
+ end
1416
+ return `d{if spec.Transmit then "1" else "0"}:{table.concat(ids, ",")}`
1417
+ end
1418
+
1419
+ --- Precision drives a float's wire width, so it belongs in the hash for the same
1420
+ --- reason Min/Max do. %.17g rather than tostring: 17 significant digits round-trip
1421
+ --- every double, so the fold does not depend on tostring's shortest-round-trip
1422
+ --- behaviour, which nothing here pins.
1423
+ local function precisionSig(n: SchemaNode): string
1424
+ local p = n.Precision
1425
+ if p == nil then
1426
+ return "nil"
1427
+ elseif type(p) == "number" then
1428
+ return string.format("%.17g", p)
1429
+ end
1430
+ return tostring(p)
1431
+ end
1432
+
1433
+ -- The hash must fold every field that affects the wire byte layout, or a
1434
+ -- server/client schema drift decodes silently wrong. Min/Max drive int
1435
+ -- width; Precision drives float width; Members drive enum indexing;
1436
+ -- Datatype/MaxLength are semantic.
1437
+ local hash = 2166136261
1438
+ for id = 0, state.NextId - 1 do
1439
+ local node = state.ById[id]
1440
+ if node then
1441
+ local members = ""
1442
+ if node.Members then
1443
+ local parts = table.create(#node.Members)
1444
+ for i, m in node.Members do
1445
+ parts[i] = `{#m}:{m}`
1446
+ end
1447
+ members = table.concat(parts, ",")
1448
+ end
1449
+ hash = Util.fnv32(
1450
+ -- Persist is folded too: without it a stale copy that moved a field
1451
+ -- on or off Session would hash identically to the current one.
1452
+ `{id}:{node.Name or ""}:{node.ValueType}:{node.Visibility}:{node.Persist}`
1453
+ .. `:{node.Min or "nil"}:{node.Max or "nil"}:{precisionSig(node)}:{node.MaxLength or "nil"}`
1454
+ .. `:{node.Datatype or "nil"}:{members}:{node.Container or "nil"}`
1455
+ .. `:{node.MaxItems or "nil"}:{node.Evict or "nil"}:{if node.Unique then "u" else "nil"}:{node.KeyType or "nil"}:{node.MaxKeys or "nil"}:{node.MaxKeyLength or "nil"}`
1456
+ .. `:{node.Nullable == true}:{if node.ChildOrder then #node.ChildOrder else -1}`
1457
+ .. `:{derivedSig(node)}`,
1458
+ hash
1459
+ )
1460
+ end
1461
+ end
1462
+
1463
+ -- Element subtrees carry no ids, so the ById fold above cannot see them, but their
1464
+ -- Min/Max/Precision drive scalar width and their Members drive enum indexing: an
1465
+ -- element-only drift would pass the Hello schema guard and then decode every
1466
+ -- following op in the frame as garbage. ChildOrder is sorted at compile time, so the
1467
+ -- walk order is identical on both realms.
1468
+ local elementOrdinal = 0
1469
+ local function foldElementNode(n: SchemaNode)
1470
+ local members = ""
1471
+ if n.Members then
1472
+ local parts = table.create(#n.Members)
1473
+ for i, m in n.Members do
1474
+ parts[i] = `{#m}:{m}`
1475
+ end
1476
+ members = table.concat(parts, ",")
1477
+ end
1478
+ -- Leaf defaults matter here, unlike static nodes whose defaults only seed new
1479
+ -- profiles server-side: mirrors materialize fresh element entries from these,
1480
+ -- so a drift would seed different content on each realm.
1481
+ local dflt = ""
1482
+ local d = n.Default
1483
+ local dt = type(d)
1484
+ if dt == "boolean" or dt == "string" then
1485
+ dflt = tostring(d)
1486
+ elseif dt == "number" then
1487
+ dflt = string.format("%.17g", d)
1488
+ elseif dt == "buffer" then
1489
+ dflt = buffer.tostring(d)
1490
+ elseif n.ValueType == "big" and dt == "table" then
1491
+ -- A big's default is the stored { mantissa, exponent } pair, not a scalar,
1492
+ -- so the branches above skip it and a drift in one would otherwise hash
1493
+ -- identically on both realms.
1494
+ dflt = string.format("%.17g:%.17g", (d :: any)[1], (d :: any)[2])
1495
+ end
1496
+ hash = Util.fnv32(
1497
+ `@{elementOrdinal}:{n.Name or ""}:{n.ValueType}:{n.Visibility}`
1498
+ .. `:{n.Min or "nil"}:{n.Max or "nil"}:{precisionSig(n)}:{n.MaxLength or "nil"}`
1499
+ .. `:{n.Datatype or "nil"}:{members}:{n.Container or "nil"}`
1500
+ .. `:{n.MaxItems or "nil"}:{n.Evict or "nil"}:{if n.Unique then "u" else "nil"}:{n.KeyType or "nil"}:{n.MaxKeys or "nil"}:{n.MaxKeyLength or "nil"}`
1501
+ .. `:{n.Nullable == true}:{if n.ChildOrder then #n.ChildOrder else -1}`
1502
+ .. `:{#dflt}:{dflt}`,
1503
+ hash
1504
+ )
1505
+ elementOrdinal += 1
1506
+ local nodeChildren = n.Children
1507
+ if n.ChildOrder and nodeChildren then
1508
+ for _, key in n.ChildOrder do
1509
+ foldElementNode(nodeChildren[key])
1510
+ end
1511
+ end
1512
+ if n.AnyChild then
1513
+ foldElementNode(n.AnyChild)
1514
+ end
1515
+ -- Subtree terminator: without it a field moved from a sub-record up to the
1516
+ -- element root folds to the same preorder byte stream as before the move.
1517
+ hash = Util.fnv32("/", hash)
1518
+ end
1519
+ local function foldElements(n: SchemaNode)
1520
+ local anyChild = n.AnyChild
1521
+ if anyChild and anyChild.IsElement then
1522
+ foldElementNode(anyChild)
1523
+ end
1524
+ local nodeChildren = n.Children
1525
+ if n.ChildOrder and nodeChildren then
1526
+ for _, key in n.ChildOrder do
1527
+ foldElements(nodeChildren[key])
1528
+ end
1529
+ end
1530
+ end
1531
+ foldElements(root)
1532
+
1533
+ -- Flatten the fields carrying a Scribe.Dynamic factory (in id order), so the
1534
+ -- load path can seed them on a new profile without walking the whole tree.
1535
+ local dynamicNodes: { SchemaNode } = {}
1536
+ for id = 0, state.NextId - 1 do
1537
+ local node = state.ById[id]
1538
+ if node and node.Factory then
1539
+ table.insert(dynamicNodes, node)
1540
+ end
1541
+ end
1542
+
1543
+ local compiled: Compiled = {
1544
+ Root = root,
1545
+ ById = state.ById,
1546
+ NodeCount = state.NextId,
1547
+ Hash = hash,
1548
+ RootOrder = order,
1549
+ HasShared = hasShared,
1550
+ DynamicNodes = dynamicNodes,
1551
+ DerivedNodes = derivedNodes,
1552
+ DerivedByWrite = derivedByWrite,
1553
+ Views = nil :: any,
1554
+ Config = cfg,
1555
+ }
1556
+
1557
+ -- A view is the compiled with its root scoped to a subset of the children. Node reads
1558
+ -- only Root, DerivedByWrite, DerivedNodes and Template.Resolve, so this costs nothing
1559
+ -- in Node itself.
1560
+ local function makeView(keys: { string }): Compiled
1561
+ local viewChildren: { [string]: SchemaNode } = {}
1562
+ local viewOrdinal: { [string]: number } = {}
1563
+ local viewShared = false
1564
+ for index, key in keys do
1565
+ local child = children[key]
1566
+ viewChildren[key] = child
1567
+ viewOrdinal[key] = index
1568
+ if child.Visibility == "Shared" then
1569
+ viewShared = true
1570
+ end
1571
+ end
1572
+ local viewRoot: SchemaNode = table.clone(root)
1573
+ -- No Id: a view must never reach an encoder. EncodePath would write id 0 and decode
1574
+ -- to a valid but schemaless path instead of raising.
1575
+ viewRoot.Id = nil
1576
+ viewRoot.Children = viewChildren
1577
+ viewRoot.ChildOrder = keys
1578
+ viewRoot.ChildOrdinal = viewOrdinal
1579
+ local view: Compiled = table.clone(compiled)
1580
+ view.Root = viewRoot
1581
+ view.RootOrder = keys
1582
+ view.HasShared = viewShared
1583
+ return view
1584
+ end
1585
+
1586
+ if #storeOrder == 0 then
1587
+ -- No store, so the player view IS the compiled and nothing else changes shape.
1588
+ compiled.Views = { Player = compiled, Store = nil }
1589
+ else
1590
+ local declared = storeTemplate :: { [string]: any }
1591
+ local playerKeys: { string } = {}
1592
+ for _, key in order do
1593
+ if declared[key] == nil then
1594
+ table.insert(playerKeys, key)
1595
+ end
1596
+ end
1597
+ compiled.Views = { Player = makeView(playerKeys), Store = makeView(table.clone(storeOrder)) }
1598
+ end
1599
+ return compiled
1600
+ end
1601
+
1602
+ -- Shared with Node, whose read paths all have to agree on which nodes need an unpack.
1603
+ function Template.IsPacked(node: SchemaNode?): boolean
1604
+ return node ~= nil and isPacked(node)
1605
+ end
1606
+
1607
+ -- Schema node for a child key: the static child when one exists, otherwise a cached
1608
+ -- dynamic pseudo-node inheriting the parent's visibility. Returns nil for children of
1609
+ -- leaves.
1610
+ function Template.ChildSchema(node: SchemaNode, key: string | number): SchemaNode?
1611
+ if node.Kind == "leaf" then
1612
+ return nil
1613
+ end
1614
+ if type(key) == "string" and node.Children then
1615
+ local child = node.Children[key]
1616
+ if child then
1617
+ return child
1618
+ end
1619
+ end
1620
+ -- A compiled element record has a fixed field set, so an undeclared key resolves
1621
+ -- to nothing and the caller rejects the write. Without this, ChildSchema would
1622
+ -- synthesize a generic `any` node and CACHE it on the shared element schema,
1623
+ -- which both accepts the typo forever and mutates the compiled tree at runtime.
1624
+ if node.Closed then
1625
+ return nil
1626
+ end
1627
+ local anyChild = node.AnyChild
1628
+ if not anyChild then
1629
+ local created: SchemaNode = {
1630
+ Id = nil,
1631
+ Name = nil,
1632
+ Path = node.Path,
1633
+ Kind = "any",
1634
+ ValueType = "any",
1635
+ Persist = node.Persist,
1636
+ Visibility = node.Visibility,
1637
+ Timed = false,
1638
+ Default = nil,
1639
+ Parent = node,
1640
+ }
1641
+ node.AnyChild = created
1642
+ anyChild = created
1643
+ end
1644
+ return anyChild
1645
+ end
1646
+
1647
+ -- Resolve a path to (deepest static schema node, index of the first dynamic
1648
+ -- segment). If the whole path is static, the index is #path + 1.
1649
+ function Template.Resolve(compiled: Compiled, path: { string | number }): (SchemaNode, number)
1650
+ local node = compiled.Root
1651
+ for i, seg in path do
1652
+ if type(seg) == "string" and node.Children and node.Children[seg] then
1653
+ node = node.Children[seg]
1654
+ else
1655
+ return node, i
1656
+ end
1657
+ end
1658
+ return node, #path + 1
1659
+ end
1660
+
1661
+ -- Effective visibility of a path (deepest static node's visibility; dynamic
1662
+ -- segments inherit).
1663
+ function Template.VisibilityOf(compiled: Compiled, path: { string | number }): Visibility
1664
+ local node = Template.Resolve(compiled, path)
1665
+ return node.Visibility
1666
+ end
1667
+
1668
+ -- The persistence axis, for callers that only have a path. Separate from
1669
+ -- VisibilityOf because a field can be Session (never saves) AND ServerOnly or
1670
+ -- Shared (who receives it) at the same time.
1671
+ function Template.PersistOf(compiled: Compiled, path: { string | number }): boolean
1672
+ local node = Template.Resolve(compiled, path)
1673
+ return node.Persist
1674
+ end
1675
+
1676
+ -- Deep-cloned default data. `which`:
1677
+ -- "Persistent": everything saved (Persist); the ProfileStore template
1678
+ -- "Session": non-persisted roots only
1679
+ -- "Client": everything except ServerOnly subtrees (the owner's mirror)
1680
+ function Template.BuildDefaults(compiled: Compiled, which: "Persistent" | "Session" | "Client"): { [string]: any }
1681
+ local function include(node: SchemaNode): boolean
1682
+ if which == "Persistent" then
1683
+ return node.Persist
1684
+ elseif which == "Session" then
1685
+ return not node.Persist
1686
+ else
1687
+ return node.Visibility ~= "ServerOnly"
1688
+ end
1689
+ end
1690
+
1691
+ -- Client defaults strip ServerOnly subtrees but keep mixed-visibility
1692
+ -- containers whose children are visible (the _Scribe reserved root).
1693
+ local function buildClient(node: SchemaNode): any
1694
+ if node.Kind ~= "table" or not node.Children then
1695
+ return if node.Visibility == "ServerOnly" then nil else Util.deepClone(node.Default)
1696
+ end
1697
+ local out = {}
1698
+ local anyVisible = false
1699
+ for key, child in node.Children do
1700
+ local value = buildClient(child)
1701
+ if value ~= nil then
1702
+ out[key] = value
1703
+ anyVisible = true
1704
+ end
1705
+ end
1706
+ if node.Visibility == "ServerOnly" and not anyVisible then
1707
+ return nil
1708
+ end
1709
+ return out
1710
+ end
1711
+
1712
+ local function build(node: SchemaNode): any
1713
+ if node.Kind ~= "table" or not node.Children then
1714
+ return Util.deepClone(node.Default)
1715
+ end
1716
+ local out = {}
1717
+ for key, child in node.Children do
1718
+ out[key] = build(child)
1719
+ end
1720
+ return out
1721
+ end
1722
+
1723
+ local out = {}
1724
+ for key, child in compiled.Root.Children :: { [string]: SchemaNode } do
1725
+ if which == "Client" then
1726
+ out[key] = buildClient(child)
1727
+ elseif include(child) then
1728
+ out[key] = build(child)
1729
+ end
1730
+ end
1731
+ return out
1732
+ end
1733
+
1734
+ -- Clone `value` at `node`, stripping ServerOnly subtrees (Init snapshots, offline
1735
+ -- perk reads). Mixed-visibility containers such as the _Scribe root keep their
1736
+ -- visible children; returns nil only when nothing is visible AND the node itself is
1737
+ -- ServerOnly.
1738
+ function Template.CloneVisible(node: SchemaNode, value: any): any
1739
+ -- A locally computed derived field is never sent: every realm that receives it can
1740
+ -- also see all of its inputs, so the client recomputes it from its own mirror.
1741
+ local derived = node.Derived
1742
+ if derived ~= nil and not derived.Transmit then
1743
+ return nil
1744
+ end
1745
+ if type(value) ~= "table" then
1746
+ if node.Visibility == "ServerOnly" then
1747
+ return nil
1748
+ end
1749
+ -- Packed datatypes are buffers, which are mutable and whose only reference here
1750
+ -- is live profile state. Callers mutate the returned tree in place, so hand
1751
+ -- back a copy.
1752
+ if type(value) == "buffer" then
1753
+ return Util.cloneBuffer(value)
1754
+ end
1755
+ return value
1756
+ end
1757
+ local out = {}
1758
+ local anyVisible = false
1759
+ for k, v in value do
1760
+ local childNode = if type(k) == "string" and node.Children then node.Children[k] else nil
1761
+ -- An ArrayOf/DictOf element schema describes EVERY entry, numeric keys
1762
+ -- included, so a ServerOnly field inside an element shape is stripped like a
1763
+ -- static one. Gated on IsElement so untyped dynamic containers keep the
1764
+ -- wholesale deepClone below, which otherwise starts aliasing live buffers.
1765
+ if childNode == nil and node.AnyChild ~= nil and node.AnyChild.IsElement then
1766
+ childNode = node.AnyChild
1767
+ end
1768
+ if childNode then
1769
+ local cloned = Template.CloneVisible(childNode, v)
1770
+ if cloned ~= nil then
1771
+ out[k] = cloned
1772
+ anyVisible = true
1773
+ end
1774
+ elseif node.Visibility ~= "ServerOnly" then
1775
+ -- Dynamic entries inherit this node's visibility.
1776
+ out[k] = Util.deepClone(v)
1777
+ anyVisible = true
1778
+ end
1779
+ end
1780
+ if node.Visibility == "ServerOnly" and not anyVisible then
1781
+ return nil
1782
+ end
1783
+ return out
1784
+ end
1785
+
1786
+ -- Backfills element fields added to an ArrayOf/DictOf shape after profiles exist.
1787
+ -- ProfileStore's Reconcile walks the static template only, and an element shape is
1788
+ -- reachable solely through AnyChild, so without this a field added in v2 stays missing
1789
+ -- on every stored entry forever. Fills a missing key, never touches an existing one;
1790
+ -- a Nullable field has a nil default and is skipped. Returns true when anything changed.
1791
+ function Template.ReconcileElements(compiled: Compiled, data: { [string]: any }): boolean
1792
+ -- `inElement` flips true under a container's AnyChild and stays true beneath it, so
1793
+ -- fills happen at every depth of an element subtree. Static template fields are
1794
+ -- never filled here; profile:Reconcile owns those.
1795
+ local function walk(node: SchemaNode, value: any, inElement: boolean): boolean
1796
+ if type(value) ~= "table" then
1797
+ return false
1798
+ end
1799
+ local changed = false
1800
+ if node.Container ~= nil then
1801
+ local element = node.AnyChild
1802
+ if element then
1803
+ for _, entry in value do
1804
+ if walk(element, entry, true) then
1805
+ changed = true
1806
+ end
1807
+ end
1808
+ end
1809
+ return changed
1810
+ end
1811
+ if node.Children then
1812
+ for name, child in node.Children do
1813
+ if inElement and value[name] == nil and child.Default ~= nil then
1814
+ value[name] = Util.deepClone(child.Default)
1815
+ changed = true
1816
+ end
1817
+ if walk(child, value[name], inElement) then
1818
+ changed = true
1819
+ end
1820
+ end
1821
+ end
1822
+ return changed
1823
+ end
1824
+
1825
+ local changed = false
1826
+ for key, child in compiled.Root.Children :: { [string]: SchemaNode } do
1827
+ if walk(child, data[key], false) then
1828
+ changed = true
1829
+ end
1830
+ end
1831
+ return changed
1832
+ end
1833
+
1834
+ -- Top-level keys present in `data` but absent from the schema (dev-mode warning;
1835
+ -- `nil :: T?` template fields are invisible at runtime).
1836
+ function Template.UnknownRootKeys(compiled: Compiled, data: { [string]: any }): { string }
1837
+ local unknown = {}
1838
+ local children = compiled.Root.Children :: { [string]: SchemaNode }
1839
+ for key in data do
1840
+ if type(key) ~= "string" or not children[key] then
1841
+ table.insert(unknown, tostring(key))
1842
+ end
1843
+ end
1844
+ table.sort(unknown)
1845
+ return unknown
1846
+ end
1847
+
1848
+ return Template