@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,3954 @@
1
+ --!strict
2
+ -- The Value tree runtime: a metatable-backed accessor tree that lazily materializes
3
+ -- child nodes, records paths for replication, validates every write, and holds
4
+ -- per-node callback lists. Used for the server tree and the client mirror alike.
5
+
6
+ local Util = require(script.Parent.Util)
7
+ local Big = require(script.Parent.Big)
8
+ local Template = require(script.Parent.Template)
9
+ local Datatypes = require(script.Parent.Datatypes)
10
+ local DerivedModule = require(script.Parent.Derived)
11
+ local Metrics = require(script.Parent.Metrics)
12
+
13
+ type SchemaNode = Template.SchemaNode
14
+ type Compiled = Template.Compiled
15
+
16
+ export type Op = {
17
+ Kind: string,
18
+ Path: { string | number },
19
+ Value: any?,
20
+ Index: number?,
21
+ }
22
+
23
+ export type TimedHooks = {
24
+ SetTimed: (accessor: any, value: any, seconds: number, replicate: boolean?) -> (),
25
+ ExtendTimed: (accessor: any, seconds: number, replicate: boolean?) -> (),
26
+ Active: (accessor: any) -> (boolean, number?),
27
+ }
28
+
29
+ export type TreeParams = {
30
+ Compiled: Compiled,
31
+ Stores: { Persist: { [string]: any }, Session: { [string]: any } },
32
+ IsServer: boolean,
33
+ Label: string,
34
+ OnOp: ((op: Op, schema: SchemaNode?) -> ())?,
35
+ OnAnomaly: ((path: { string | number }, value: any, reason: string) -> ())?,
36
+ BoundsPolicy: ("Clamp" | "Reject")?,
37
+ DevMode: boolean?,
38
+ TimedHooks: TimedHooks?,
39
+ OnEconomy: ((path: { string | number }, delta: number, newValue: number, tags: { [string]: any }) -> ())?,
40
+ LogError: (message: string) -> (),
41
+ LogWarn: ((message: string) -> ())?,
42
+ OnBatchEnd: (() -> ())?,
43
+ -- Scribe.Derived diagnostics, so each realm logs with its own context and this
44
+ -- module stays free of the logger.
45
+ OnDerivedIssue: ((code: string, field: string, detail: string) -> ())?,
46
+ -- The server store: no player, no key. Read only by the cross-tree refusal.
47
+ IsServerStore: boolean?,
48
+ }
49
+
50
+ -- Cast once: Big.from is optional because parsing can fail, which a literal cannot,
51
+ -- and the economy path below would otherwise compare through `any`.
52
+ local BIG_ZERO = Big.from(0) :: Big.Big
53
+
54
+ local Node = {}
55
+
56
+ -- The message RunTransaction returns when `fn` yielded. Exported so a caller can tell
57
+ -- a yield apart from a throw without string-matching a literal.
58
+ local YIELD_ERROR =
59
+ "Scribe: a transaction function must not yield (no task.wait, DataStore, or MarketplaceService calls inside Data.Transaction; do async work before or after it)"
60
+ Node.YIELD_ERROR = YIELD_ERROR
61
+
62
+ local ACCESSOR_MT: any -- forward declaration
63
+
64
+ -- Tree ------------------------------------------------------------------------
65
+
66
+ local Tree = {}
67
+ Tree.__index = Tree
68
+
69
+ export type Tree = typeof(setmetatable(
70
+ {} :: {
71
+ Params: TreeParams,
72
+ Compiled: Compiled,
73
+ Accessor: any,
74
+ -- The library's handle on the reserved `_Scribe` root: the only accessor
75
+ -- permitted to write there, and never returned by any public API.
76
+ Reserved: any,
77
+ Dead: boolean,
78
+ _listeners: { [string]: { [string]: { [any]: (...any) -> () } } },
79
+ -- Path array per listened pathKey; the pathKey string is lossy and cannot be
80
+ -- reversed to read a node's value.
81
+ _paths: { [string]: { string | number } },
82
+ -- Ancestor pathKey -> listened pathKeys strictly below it, so a container write
83
+ -- finds its descendant listeners by lookup instead of sweeping every path.
84
+ _descendants: { [string]: { [string]: boolean } },
85
+ -- True only while replaying the initial snapshot: suppresses per-op fires so
86
+ -- descendants can be fired once, together, afterwards.
87
+ _replaying: boolean,
88
+ _batchDepth: number,
89
+ -- Ancestor Changed fires deferred to the end of a batch, keyed by pathKey so N
90
+ -- writes under one container collapse to one fire. Insertion-ordered via
91
+ -- _pendingAncestorOrder, which reproduces the unbatched order.
92
+ _pendingAncestors: { [string]: { string | number } }?,
93
+ _pendingAncestorOrder: { string }?,
94
+ -- Set only while a failed transaction rolls back: dispatch is queued here and
95
+ -- drained once the tree is whole again. See `fire` and `rollbackTransaction`.
96
+ _fireQueue: { { any } }?,
97
+ _txn: {
98
+ Snapshots: { [string]: { Path: { string | number }, Value: any } },
99
+ Below: { [string]: { [string]: boolean } },
100
+ Ops: { { Op: Op, Schema: SchemaNode? } },
101
+ Created: { { string | number } },
102
+ Seeded: { { string | number } },
103
+ Economy: { { Path: { string | number }, Delta: number, New: number, Tags: { [string]: any } } },
104
+ RawRestores: { [string]: { Store: { [string]: any }, Value: any } },
105
+ }?,
106
+ -- Scribe.Derived: fields whose inputs changed and have not been recomputed
107
+ -- yet, and the reentrancy guard for the settle pass that drains them.
108
+ _derivedDirty: { [SchemaNode]: true }?,
109
+ _derivedAudit: { { Path: { string | number }, Label: string, Server: any } }?,
110
+ _derivedSettling: boolean,
111
+ -- Fields whose compute function has already reported a throw this session.
112
+ _derivedLogged: { [SchemaNode]: true }?,
113
+ },
114
+ Tree
115
+ ))
116
+
117
+ -- Per-accessor state, stored under keys a caller cannot type. Table identities, not
118
+ -- strings: a rawset string key like "_tree" is found before __index runs, so
119
+ -- `Data.Get(p)._tree` would hand game code the live Tree and its raw stores.
120
+ local F_TREE = {} :: any
121
+ local F_PATH = {} :: any
122
+ local F_KEY = {} :: any
123
+ local F_SCHEMA = {} :: any
124
+ local F_CHILDREN = {} :: any
125
+
126
+ -- The accessors permitted to write under Template.RESERVED_ROOT. A module upvalue
127
+ -- rather than a field, so no object a caller can reach can rawset the capability onto
128
+ -- a public accessor. Weak-keyed: a collected child accessor is rebuilt from its
129
+ -- parent, which re-grants it.
130
+ local PRIVILEGED: { [any]: true } = setmetatable({}, { __mode = "k" }) :: any
131
+
132
+ -- The ONE tree whose transaction is open right now, or nil. `Tree._txn` is per-tree,
133
+ -- right for the journal but wrong as the admission test: a transaction can only undo
134
+ -- writes to its own tree, and another player is another tree behind another DataStore
135
+ -- key. A module upvalue is sound because a transaction is synchronous by construction:
136
+ -- `fn` runs on its own coroutine and a yield is refused. Cleared BEFORE the rollback
137
+ -- restores and before the queued fires drain, so a listener writing after a rollback is
138
+ -- an ordinary write.
139
+ local OPEN_TXN_TREE: Tree? = nil
140
+
141
+ -- The shared half of both cross-tree refusals: why, and the durable outbox to use
142
+ -- instead. One player handing value to another is a real need, so the refusal has to
143
+ -- name the route that works.
144
+ local CROSS_TREE_TXN_WHY = "a transaction can only roll back its OWN player, because another player is "
145
+ .. "another tree behind another DataStore key -- the same reason a yield inside a transaction is "
146
+ .. "refused. For one-sided value (a gift, mail, a reward, a bounty payout) use the durable outbox that "
147
+ .. "gift delivery already uses: record the debit on the giver's own key INSIDE this transaction, "
148
+ .. "Data.Flush it, then deliver with Data.SendMessage and apply it idempotently at the far end. See the "
149
+ .. "Transactions guide."
150
+
151
+ -- The cross-tree refusal, in one place: accessorIndex is not the only writer, since
152
+ -- Server/Timed writes the flat `_Scribe.Timed` store raw. `subject` names what was
153
+ -- written, `level` is the caller's own blame depth. Callers gate on OPEN_TXN_TREE
154
+ -- before building `subject`, which is not worth allocating on every write.
155
+ local function assertSameTreeWrite(tree: Tree?, subject: string, level: number)
156
+ if OPEN_TXN_TREE == nil or tree == OPEN_TXN_TREE then
157
+ return
158
+ end
159
+ -- Not another player, so the outbox route is wrong advice: it has no key at all.
160
+ if tree ~= nil and tree.Params.IsServerStore then
161
+ error(
162
+ `Scribe: "{subject}" is on the ServerStore, not on the player whose transaction is `
163
+ .. `open, so it cannot be written from inside that transaction: a rollback restores one `
164
+ .. `player's own tree, and the store is not saved to any key, so a store write would `
165
+ .. `outlive an aborted transaction. Write the store before Data.Transaction, or after it `
166
+ .. `returns true.`,
167
+ level
168
+ )
169
+ end
170
+ error(
171
+ `Scribe: "{subject}" belongs to a different player than the one `
172
+ .. `whose transaction is open, so it cannot be written from inside that transaction: `
173
+ .. CROSS_TREE_TXN_WHY,
174
+ level
175
+ )
176
+ end
177
+
178
+ local function newAccessor(tree: Tree, path: { string | number }, schema: SchemaNode?, privileged: boolean?): any
179
+ local accessor: any = setmetatable({}, ACCESSOR_MT)
180
+ rawset(accessor, F_TREE, tree)
181
+ rawset(accessor, F_PATH, path)
182
+ rawset(accessor, F_KEY, Util.pathKey(path))
183
+ rawset(accessor, F_SCHEMA, schema)
184
+ -- Weak VALUES: child accessors carry no state (listeners live on the tree, keyed by
185
+ -- pathKey), so a collected one is simply rebuilt on the next index. Without this,
186
+ -- indexing a dictionary by transient keys (GUIDs, trade ids) leaks for the session.
187
+ rawset(accessor, F_CHILDREN, setmetatable({}, { __mode = "v" }))
188
+ if privileged then
189
+ PRIVILEGED[accessor] = true
190
+ end
191
+ return accessor
192
+ end
193
+
194
+ function Node.NewTree(params: TreeParams): Tree
195
+ local self = setmetatable({
196
+ Params = params,
197
+ Compiled = params.Compiled,
198
+ Accessor = nil :: any,
199
+ Reserved = nil :: any,
200
+ Dead = false,
201
+ _listeners = {},
202
+ _paths = {},
203
+ _descendants = {},
204
+ _replaying = false,
205
+ _batchDepth = 0,
206
+ _pendingAncestors = nil,
207
+ _pendingAncestorOrder = nil,
208
+ _fireQueue = nil,
209
+ _txn = nil,
210
+ _derivedDirty = nil,
211
+ _derivedSettling = false,
212
+ _derivedLogged = nil,
213
+ }, Tree) :: Tree
214
+ self.Accessor = newAccessor(self, {}, params.Compiled.Root)
215
+ -- The schema is read straight off Root.Children, not through ChildSchema: a template
216
+ -- lacking the reserved root must not get an AnyChild node synthesized and cached onto
217
+ -- the compiled root as a side effect of building a tree.
218
+ local rootChildren = params.Compiled.Root.Children
219
+ self.Reserved = newAccessor(
220
+ self,
221
+ { Template.RESERVED_ROOT },
222
+ if rootChildren then rootChildren[Template.RESERVED_ROOT] else nil,
223
+ true
224
+ )
225
+ return self
226
+ end
227
+
228
+ local function assertAlive(tree: Tree)
229
+ if tree.Dead then
230
+ error(`Scribe: data for {tree.Params.Label} has been unloaded`, 3)
231
+ end
232
+ end
233
+
234
+ local function storeFor(tree: Tree, rootKey: string | number): { [string]: any }
235
+ local children = tree.Compiled.Root.Children
236
+ if type(rootKey) == "string" and children then
237
+ local rootSchema = children[rootKey]
238
+ if rootSchema and not rootSchema.Persist then
239
+ return tree.Params.Stores.Session
240
+ end
241
+ end
242
+ return tree.Params.Stores.Persist
243
+ end
244
+
245
+ -- The other-typed form of a key that produces the SAME Util.pathKey (7 <-> "7"), or
246
+ -- nil when there is none. Used to reject a numeric key coexisting with its string
247
+ -- form, whose colliding pathKeys would alias listeners, coalescing and rollback.
248
+ local function aliasForm(seg: any): any
249
+ if type(seg) == "number" then
250
+ return tostring(seg)
251
+ elseif type(seg) == "string" then
252
+ local n = tonumber(seg)
253
+ if n ~= nil and n % 1 == 0 and tostring(n) == seg then
254
+ return n
255
+ end
256
+ end
257
+ return nil
258
+ end
259
+
260
+ -- Container memos -------------------------------------------------------------
261
+ --
262
+ -- Key count and "holds a string key", memoised by container identity so building a
263
+ -- capped or integer-keyed dictionary key by key is not O(n^2). Weak-keyed, and safe
264
+ -- because a whole-table Set installs a different table with no entry yet. Maintained
265
+ -- where a container is ASSIGNED INTO, not where a write is validated: NoValidate and
266
+ -- FromRemote writes skip validation entirely.
267
+ local containerCounts: { [any]: number } = setmetatable({}, { __mode = "k" }) :: any
268
+ -- The offending string key of an integer-keyed container, or `false` for
269
+ -- "walked it, there is none".
270
+ local stringKeyed: { [any]: any } = setmetatable({}, { __mode = "k" }) :: any
271
+
272
+ local function countKeysExact(container: any): number
273
+ local n = 0
274
+ for _ in container do
275
+ n += 1
276
+ end
277
+ containerCounts[container] = n
278
+ return n
279
+ end
280
+
281
+ local function countKeys(container: any): number
282
+ local cached = containerCounts[container]
283
+ if cached ~= nil then
284
+ return cached
285
+ end
286
+ return countKeysExact(container)
287
+ end
288
+
289
+ -- One key of `container` went from absent to present or back. A container with no
290
+ -- memo yet is left alone: the next countKeys walks it once and starts from truth.
291
+ local function noteKeyDelta(container: any, key: any, had: boolean, has: boolean)
292
+ if had == has then
293
+ return
294
+ end
295
+ -- A cached "holds no string key" stops being true the moment one is added. Upgraded
296
+ -- here rather than in the guard because NoValidate and FromRemote writes assign
297
+ -- without reaching validation, and this hook still sees them. A string key going AWAY
298
+ -- is deliberately not tracked: that only leaves a stale "yes", which
299
+ -- blockingStringKey re-derives before acting on.
300
+ if has and type(key) == "string" and stringKeyed[container] == false then
301
+ stringKeyed[container] = key
302
+ end
303
+ local cached = containerCounts[container]
304
+ if cached ~= nil then
305
+ containerCounts[container] = if has then cached + 1 else cached - 1
306
+ end
307
+ end
308
+
309
+ -- Drop both memos for a container mutated in a way this module cannot account for
310
+ -- key by key. Cheaper and safer than trying to reconstruct the delta.
311
+ local function forgetContainer(container: any)
312
+ containerCounts[container] = nil
313
+ stringKeyed[container] = nil
314
+ end
315
+
316
+ -- A container emptied in place (table.clear keeps the identity) has no keys at all, so
317
+ -- neither memo needs re-deriving. Not load-bearing; it just keeps them truthful.
318
+ local function noteContainerCleared(container: any)
319
+ containerCounts[container] = 0
320
+ stringKeyed[container] = false
321
+ end
322
+
323
+ local function scanStringKey(container: any): string?
324
+ for existing in container do
325
+ if type(existing) == "string" then
326
+ stringKeyed[container] = existing
327
+ return existing
328
+ end
329
+ end
330
+ stringKeyed[container] = false
331
+ return nil
332
+ end
333
+
334
+ -- Does this container still hold a string key? Only a Scribe.MapOf("integer") asks, and
335
+ -- only when adding a key, so "no" is the case worth memoising. A cached "yes" is NOT
336
+ -- trusted: such a key goes away by a raw fix-up of the stored table (a migration, an
337
+ -- operator edit) this module never sees, so re-deriving lets the repair take effect
338
+ -- instead of locking the container forever.
339
+ local function blockingStringKey(container: any): string?
340
+ local cached = stringKeyed[container]
341
+ if cached == false then
342
+ return nil
343
+ end
344
+ return scanStringKey(container)
345
+ end
346
+
347
+ -- Would creating `key` in this UNDECLARED container leave it holding an array part and
348
+ -- string keys at once? The DataStore drops half of such a table on encode. Returns a
349
+ -- description of the blocker, or nil.
350
+ --
351
+ -- Deliberately asymmetric: a numeric key is refused whenever a string key is present,
352
+ -- but a string key only when index 1 is occupied, since `{ [7] = ... }` is a legitimate
353
+ -- sparse bag that encodes cleanly.
354
+ local function mixedKeyBlocker(container: any, key: any): string?
355
+ if type(key) == "number" then
356
+ if container[1] ~= nil then
357
+ -- Already array-shaped, so a further index adds nothing the string side did
358
+ -- not already have to permit. Short-circuiting here is also what keeps
359
+ -- building an array key-by-key linear rather than quadratic.
360
+ return nil
361
+ end
362
+ local blocking = blockingStringKey(container)
363
+ if blocking ~= nil then
364
+ return `the string key "{blocking}"`
365
+ end
366
+ return nil
367
+ end
368
+ if container[1] ~= nil then
369
+ return "an array starting at index 1"
370
+ end
371
+ return nil
372
+ end
373
+
374
+ local function checkContainerKey(
375
+ containerSchema: SchemaNode?,
376
+ container: any,
377
+ key: any,
378
+ path: { any },
379
+ upto: number,
380
+ removing: boolean?
381
+ )
382
+ -- Rendered only when refusing; this runs on every container write.
383
+ local function where(): string
384
+ return Util.pathString(table.move(path, 1, upto, 1, {}))
385
+ end
386
+ local kind = if containerSchema then containerSchema.Container else nil
387
+ if kind == nil then
388
+ -- No declared key type, but an undeclared container still may not become a mixed
389
+ -- array/hash table. Only key CREATION is judged: a removal, or a write to a key
390
+ -- already there, must stay possible or a profile that loaded already mixed has no
391
+ -- way to repair itself.
392
+ if not removing and container[key] == nil then
393
+ local blocker = mixedKeyBlocker(container, key)
394
+ if blocker ~= nil then
395
+ -- A write on the profile root has an empty path prefix, and `"" already
396
+ -- holds ...` reads like a bug in the message. Name the root instead.
397
+ local label = if where() == "" then "the profile root" else `"{where()}"`
398
+ error(
399
+ `Scribe: {label} already holds {blocker}, so adding the key {tostring(key)} would make it `
400
+ .. "a mixed array/hash table -- the DataStore drops half of one on save, and Set on the "
401
+ .. "parent refuses the same shape. Use one key type for this container",
402
+ 0
403
+ )
404
+ end
405
+ end
406
+ return
407
+ end
408
+ local schema = containerSchema :: SchemaNode
409
+ if kind == "Array" then
410
+ if type(key) ~= "number" then
411
+ error(
412
+ `Scribe: "{where()}" is a Scribe.ArrayOf and takes array indices, but the key "{tostring(key)}" `
413
+ .. `is a {type(key)}`,
414
+ 0
415
+ )
416
+ end
417
+ local len = #container
418
+ if removing then
419
+ -- Only the tail can go away by a nil write without leaving a hole. Removing
420
+ -- a key that is not there stays a no-op.
421
+ if container[key] ~= nil and key ~= len then
422
+ error(
423
+ `Scribe: "{where()}" is a Scribe.ArrayOf and must stay contiguous; use Remove({key}) `
424
+ .. `instead of setting index {key} to nil`,
425
+ 0
426
+ )
427
+ end
428
+ return
429
+ end
430
+ if key % 1 ~= 0 or key < 1 or key > len + 1 then
431
+ error(
432
+ `Scribe: index {key} is out of range for "{where()}" (length {len}); `
433
+ .. "array elements are created with Insert",
434
+ 0
435
+ )
436
+ end
437
+ -- Growth only: an entry past the cap that already exists stays writable,
438
+ -- because a newer-template server may have stored it before this server's
439
+ -- lower cap deployed, and stranding it turns a rolling deploy into lost writes.
440
+ if schema.MaxItems and key > schema.MaxItems and container[key] == nil then
441
+ error(`Scribe: "{where()}" is capped at MaxItems {schema.MaxItems}`, 0)
442
+ end
443
+ else
444
+ -- Scribe.MapOf declares its key type; a plain Scribe.DictOf is string-keyed.
445
+ local keyType = schema.KeyType or "string"
446
+ if keyType == "integer" then
447
+ if type(key) ~= "number" then
448
+ error(
449
+ `Scribe: "{where()}" is a Scribe.MapOf("integer") and takes integer keys, but the key `
450
+ .. `{tostring(key)} is a {type(key)}`,
451
+ 0
452
+ )
453
+ end
454
+ -- A DataStore serializes object keys to JSON strings, and only a finite
455
+ -- integer survives that round trip unambiguously.
456
+ if key ~= key or key == math.huge or key == -math.huge or key % 1 ~= 0 then
457
+ error(`Scribe: "{where()}" takes finite integer keys, got {tostring(key)}`, 0)
458
+ end
459
+ elseif type(key) ~= "string" then
460
+ local declarator = if schema.KeyType then `Scribe.MapOf("string")` else "Scribe.DictOf"
461
+ error(
462
+ `Scribe: "{where()}" is a {declarator} and takes string keys, but the key {tostring(key)} `
463
+ .. `is a {type(key)}`,
464
+ 0
465
+ )
466
+ end
467
+ if removing then
468
+ return
469
+ end
470
+ -- A new integer key in a container that still holds a string one gives a
471
+ -- table with both key types, which fails the WHOLE profile save, not just
472
+ -- this field. Reachable when load-time coercion was blocked by a
473
+ -- non-canonical spelling ("07", "1.5"). Refuse and name the blocker.
474
+ if keyType == "integer" and container[key] == nil then
475
+ local blocking = blockingStringKey(container)
476
+ if blocking ~= nil then
477
+ error(
478
+ `Scribe: "{where()}" is a Scribe.MapOf("integer") but still holds the string key `
479
+ .. `"{blocking}", which load-time coercion could not convert. Writing an integer `
480
+ .. "key now would leave both key types in one table, which fails the whole "
481
+ .. "profile save. Remove or migrate that key first",
482
+ 0
483
+ )
484
+ end
485
+ end
486
+ local maxKeyLength = if keyType == "string" then schema.MaxKeyLength else nil
487
+ if maxKeyLength and #(key :: string) > maxKeyLength then
488
+ -- Reject rather than truncate: a truncated key writes to the wrong slot.
489
+ error(`Scribe: key "{key}" at "{where()}" is {#(key :: string)} bytes, over MaxKeyLength {maxKeyLength}`, 0)
490
+ end
491
+ local maxKeys = schema.MaxKeys
492
+ if maxKeys and container[key] == nil then
493
+ local count = countKeys(container)
494
+ if count >= maxKeys then
495
+ -- At the cap according to the memo. Re-derive before refusing, so a
496
+ -- memo drifted by a caller mutating the live table from a container
497
+ -- Get() costs a walk rather than rejecting a legitimate write.
498
+ count = countKeysExact(container)
499
+ end
500
+ if count >= maxKeys then
501
+ error(`Scribe: "{where()}" already holds {count} keys, at its MaxKeys {maxKeys}`, 0)
502
+ end
503
+ end
504
+ end
505
+ end
506
+
507
+ -- Resolves the container holding path's last segment, materializing missing
508
+ -- intermediates when `create`. `schema` is the LAST segment's schema; the
509
+ -- per-segment ones come from walking its Parent chain, which mirrors the path.
510
+ local function resolveContainer(
511
+ tree: Tree,
512
+ path: { string | number },
513
+ create: boolean,
514
+ schema: SchemaNode?,
515
+ validating: boolean?
516
+ ): (any, any)
517
+ local n = #path
518
+ if n == 0 then
519
+ return nil, nil
520
+ end
521
+ local chain: { SchemaNode }? = nil
522
+ if create and schema ~= nil and n > 1 then
523
+ local c = table.create(n) :: { SchemaNode }
524
+ local cursor: SchemaNode? = schema
525
+ for i = n, 1, -1 do
526
+ if cursor == nil then
527
+ break
528
+ end
529
+ c[i] = cursor
530
+ cursor = cursor.Parent
531
+ end
532
+ chain = c
533
+ end
534
+ local container: any = storeFor(tree, path[1])
535
+ for i = 1, n - 1 do
536
+ local seg = path[i]
537
+ local nextContainer = container[seg]
538
+ if nextContainer == nil then
539
+ if not create then
540
+ return nil, nil
541
+ end
542
+ -- The container written into is path[1..i-1], so its schema is the chain
543
+ -- entry one level up; i == 1 is the store root, never a declared
544
+ -- container. Validated writes only: a remote apply must never throw here,
545
+ -- because one throw drops the rest of the frame and desyncs the mirror.
546
+ if validating and chain and i > 1 then
547
+ checkContainerKey(chain[i - 1], container, seg, path, i - 1)
548
+ end
549
+ -- Same alias hazard applySet guards for the leaf key: a nested write like
550
+ -- Dict[7].Sub must not create a numeric 7 next to an existing string "7".
551
+ local alias = aliasForm(seg)
552
+ if alias ~= nil and container[alias] ~= nil then
553
+ error(
554
+ `Scribe: key "{tostring(seg)}" at "{Util.pathString(path)}" collides with the existing `
555
+ .. `"{tostring(alias)}" key form (a numeric key and its string form cannot coexist)`,
556
+ 0
557
+ )
558
+ end
559
+ -- A declared element materializes from its compiled defaults, so writing
560
+ -- one field of a fresh key does not leave the rest nil against a type
561
+ -- that says they are always present.
562
+ local createdSchema = if chain then chain[i] else nil
563
+ local seed: any = nil
564
+ if createdSchema and createdSchema.IsElement then
565
+ -- The mirror gets the ServerOnly-stripped copy; the full default would
566
+ -- surface a value on the client that no replicated op ever sent.
567
+ seed = if tree.Params.IsServer then createdSchema.Default else createdSchema.ClientDefault
568
+ end
569
+ nextContainer = if type(seed) == "table" then Util.deepClone(seed) else {}
570
+ local segHad = container[seg] ~= nil
571
+ container[seg] = nextContainer
572
+ noteKeyDelta(container, seg, segHad, true)
573
+ -- Recorded so a rollback can prune containers that never existed pre-txn.
574
+ local txn = tree._txn
575
+ if txn then
576
+ txn.Created[#txn.Created + 1] = table.move(path, 1, i, 1, table.create(i) :: { string | number })
577
+ end
578
+ elseif type(nextContainer) ~= "table" then
579
+ if not create then
580
+ -- A READ through a segment that now holds a scalar answers nil, as a
581
+ -- read through an absent segment does. readValue is on the apply path
582
+ -- twice (snapshotDescendants and fireDescendants), so raising here would
583
+ -- kill the frame and desync the mirror for good. Only a WRITE raises.
584
+ return nil, nil
585
+ end
586
+ error(`Scribe: cannot index "{Util.pathString(path)}": "{tostring(seg)}" is not a table`, 0)
587
+ end
588
+ container = nextContainer
589
+ end
590
+ return container, path[n]
591
+ end
592
+
593
+ local function readValue(tree: Tree, path: { string | number }): any
594
+ if #path == 0 then
595
+ return tree.Params.Stores.Persist
596
+ end
597
+ local container, key = resolveContainer(tree, path, false)
598
+ if container == nil then
599
+ return nil
600
+ end
601
+ return container[key]
602
+ end
603
+
604
+ -- Listeners ---------------------------------------------------------------------
605
+
606
+ local function listenersFor(tree: Tree, pathKey: string, event: string, create: boolean): { [any]: (...any) -> () }?
607
+ local byEvent = tree._listeners[pathKey]
608
+ if byEvent == nil then
609
+ if not create then
610
+ return nil
611
+ end
612
+ byEvent = {}
613
+ tree._listeners[pathKey] = byEvent
614
+ end
615
+ local list = byEvent[event]
616
+ if list == nil then
617
+ if not create then
618
+ return nil
619
+ end
620
+ list = {}
621
+ byEvent[event] = list
622
+ end
623
+ return list
624
+ end
625
+
626
+ -- Calls `fn` with every strict ancestor pathKey of `pathKey`, outermost first. A
627
+ -- segment can never contain the \31 separator (control characters are refused at
628
+ -- write time), so a prefix ending at one is exactly an ancestor.
629
+ local function forEachAncestorKey(pathKey: string, fn: (string) -> ())
630
+ local at = string.find(pathKey, "\31", 1, true)
631
+ while at do
632
+ fn(string.sub(pathKey, 1, at - 1))
633
+ at = string.find(pathKey, "\31", at + 1, true)
634
+ end
635
+ end
636
+
637
+ -- Register/unregister `pathKey` under each of its ancestors, so a write at an
638
+ -- ancestor can find everything listening below it without sweeping every path.
639
+ local function indexDescendant(tree: Tree, pathKey: string)
640
+ forEachAncestorKey(pathKey, function(ancestor)
641
+ local set = tree._descendants[ancestor]
642
+ if set == nil then
643
+ set = {}
644
+ tree._descendants[ancestor] = set
645
+ end
646
+ set[pathKey] = true
647
+ end)
648
+ end
649
+
650
+ local function unindexDescendant(tree: Tree, pathKey: string)
651
+ forEachAncestorKey(pathKey, function(ancestor)
652
+ local set = tree._descendants[ancestor]
653
+ if set ~= nil then
654
+ set[pathKey] = nil
655
+ if next(set) == nil then
656
+ tree._descendants[ancestor] = nil
657
+ end
658
+ end
659
+ end)
660
+ end
661
+
662
+ local function connect(tree: Tree, path: { string | number }, event: string, fn: (...any) -> ()): () -> ()
663
+ assertAlive(tree)
664
+ local pathKey = Util.pathKey(path)
665
+ local list = listenersFor(tree, pathKey, event, true) :: { [any]: (...any) -> () }
666
+ if tree._paths[pathKey] == nil then
667
+ indexDescendant(tree, pathKey)
668
+ end
669
+ tree._paths[pathKey] = path
670
+ local token = {}
671
+ list[token] = fn
672
+ return function()
673
+ local byEvent = tree._listeners[pathKey]
674
+ local current = byEvent and byEvent[event]
675
+ if current then
676
+ current[token] = nil
677
+ -- Reclaim now-empty listener tables so they don't accumulate and
678
+ -- permanently defeat the fireAncestors no-listener fast path.
679
+ if next(current) == nil then
680
+ byEvent[event] = nil
681
+ if next(byEvent) == nil then
682
+ tree._listeners[pathKey] = nil
683
+ tree._paths[pathKey] = nil
684
+ unindexDescendant(tree, pathKey)
685
+ end
686
+ end
687
+ end
688
+ end
689
+ end
690
+
691
+ local function fire(tree: Tree, pathKey: string, event: string, ...: any)
692
+ if tree._replaying then
693
+ return -- suppressed during the Init replay; fired together afterwards
694
+ end
695
+ local list = listenersFor(tree, pathKey, event, false)
696
+ if list == nil then
697
+ return
698
+ end
699
+ -- A rollback restores many paths one at a time; dispatching as each lands would
700
+ -- let a listener read and write from a half-restored tree that never existed.
701
+ -- Queue instead, and RunTransaction drains once every restore has landed. Unlike
702
+ -- the `_replaying` suppression above, nothing is dropped: only the dispatch moves.
703
+ local queue = tree._fireQueue
704
+ if queue ~= nil then
705
+ queue[#queue + 1] = { pathKey, event, table.pack(...) }
706
+ return
707
+ end
708
+ local args = table.pack(...)
709
+ -- Snapshot the listeners before dispatch: a callback may connect or disconnect
710
+ -- into this same live table, and mutating during generalized iteration is
711
+ -- undefined in Luau. Semantics match GoodSignal: a listener connected during the
712
+ -- fire does not receive it, and one disconnected mid-fire is not called.
713
+ local tokens = {}
714
+ local fns = {}
715
+ for token, fn in list do
716
+ tokens[#tokens + 1] = token
717
+ fns[#fns + 1] = fn
718
+ end
719
+ for i = 1, #fns do
720
+ if list[tokens[i]] == nil then
721
+ continue -- disconnected by an earlier listener during this fire
722
+ end
723
+ local fn = fns[i]
724
+ local ok, err = xpcall(function()
725
+ fn(table.unpack(args, 1, args.n))
726
+ end, function(e)
727
+ return debug.traceback(tostring(e), 2)
728
+ end)
729
+ if not ok then
730
+ tree.Params.LogError(`listener error at "{pathKey}" ({event}): {err}`)
731
+ end
732
+ end
733
+ end
734
+
735
+ -- Walks up from `path` firing two kinds of event on each ancestor. OnChildChanged is a
736
+ -- TRANSITION, so it fires immediately and is never coalesced, which would destroy what
737
+ -- it reports. Changed is STATE, and its `old` is the same reference as `new`, so a batch
738
+ -- can collapse it losing nothing.
739
+ --
740
+ -- `childOld` is the deepest ancestor's immediate child's prior value, passed only by
741
+ -- applySet. It needs its own `known` flag because nil is a legitimate prior value.
742
+ local function fireAncestors(tree: Tree, path: { string | number }, childOld: any, childOldKnown: boolean?)
743
+ if next(tree._listeners) == nil then
744
+ return
745
+ end
746
+ local deferring = tree._batchDepth > 0
747
+ -- The child of the ancestor at `depth` is the prefix of length depth + 1, i.e.
748
+ -- the previous iteration's already-allocated prefix. Starts as `path` itself.
749
+ local childPrefix: { string | number } = path
750
+ for depth = #path - 1, 0, -1 do
751
+ local prefix = table.move(path, 1, depth, 1, table.create(depth) :: { string | number })
752
+ local pathKey = Util.pathKey(prefix)
753
+ local byEvent = tree._listeners[pathKey]
754
+ if byEvent ~= nil then
755
+ local childList = byEvent.OnChildChanged
756
+ if childList and next(childList) ~= nil then
757
+ -- Read the child on its OWN path, not by indexing the parent's table:
758
+ -- at the root, readValue short-circuits to Stores.Persist, so
759
+ -- `parentValue[key]` would read nil for a Session root's child.
760
+ local childNew = readValue(tree, childPrefix)
761
+ local previous = if depth == #path - 1 and childOldKnown then childOld else childNew
762
+ fire(tree, pathKey, "OnChildChanged", path[depth + 1], childNew, previous)
763
+ end
764
+ local list = byEvent.Changed
765
+ if list and next(list) ~= nil then
766
+ if not deferring then
767
+ local value = readValue(tree, prefix)
768
+ fire(tree, pathKey, "Changed", value, value)
769
+ else
770
+ local pending = tree._pendingAncestors
771
+ if pending == nil then
772
+ pending = {}
773
+ tree._pendingAncestors = pending
774
+ tree._pendingAncestorOrder = {}
775
+ end
776
+ if (pending :: any)[pathKey] == nil then
777
+ (pending :: any)[pathKey] = prefix
778
+ local order = tree._pendingAncestorOrder :: { string }
779
+ order[#order + 1] = pathKey
780
+ end
781
+ end
782
+ end
783
+ end
784
+ childPrefix = prefix
785
+ end
786
+ end
787
+
788
+ -- A container's own STATE fire, routed through the defer queue fireAncestors uses.
789
+ -- Insert/Remove/Clear mutate at the container's own path, so they never reach
790
+ -- fireAncestors for that node and would otherwise fire N times in a batch where every
791
+ -- other container fires once. Safe to collapse: the fire is (value, value), and OnInsert
792
+ -- and OnRemove carry the per-entry transitions separately.
793
+ local function deferSelfState(tree: Tree, pathKey: string, path: { string | number }): boolean
794
+ if tree._replaying then
795
+ -- Same suppression `fire` applies: ReplayFire fires every observed path
796
+ -- itself once the apply is done, so queuing here would double it.
797
+ return true
798
+ end
799
+ if tree._batchDepth == 0 then
800
+ return false
801
+ end
802
+ local list = listenersFor(tree, pathKey, "Changed", false)
803
+ if list == nil or next(list) == nil then
804
+ return true -- nothing listening: skip the fire either way
805
+ end
806
+ local pending = tree._pendingAncestors
807
+ if pending == nil then
808
+ pending = {}
809
+ tree._pendingAncestors = pending
810
+ tree._pendingAncestorOrder = {}
811
+ end
812
+ if (pending :: any)[pathKey] == nil then
813
+ (pending :: any)[pathKey] = table.clone(path)
814
+ local order = tree._pendingAncestorOrder :: { string }
815
+ order[#order + 1] = pathKey
816
+ end
817
+ return true
818
+ end
819
+
820
+ -- Fire the ancestor Changed events a batch deferred, one per container. Values are
821
+ -- read NOW, so every listener sees the batch's end state.
822
+ --
823
+ -- Order is first-touch, which reproduces the unbatched order minus the duplicates. It
824
+ -- is NOT globally deepest-first, and sorting it that way would move fires.
825
+ local function flushPendingAncestors(tree: Tree)
826
+ local pending = tree._pendingAncestors
827
+ if pending == nil then
828
+ return
829
+ end
830
+ local order = tree._pendingAncestorOrder :: { string }
831
+ tree._pendingAncestors = nil
832
+ tree._pendingAncestorOrder = nil
833
+ for _, pathKey in order do
834
+ local list = listenersFor(tree, pathKey, "Changed", false)
835
+ if list and next(list) ~= nil then
836
+ local value = readValue(tree, pending[pathKey])
837
+ fire(tree, pathKey, "Changed", value, value)
838
+ end
839
+ end
840
+ end
841
+
842
+ -- Drop a rolled-back transaction's deferred fires; the restores below fire their own
843
+ -- Changed with the pre-transaction values. Scoped by a mark taken when the transaction
844
+ -- opened, because the queue is tree-wide: a transaction nested in a Data.Batch shares it
845
+ -- with the batch's surviving writes, and clearing it wholesale would swallow those too.
846
+ local function discardPendingAncestors(tree: Tree, mark: number)
847
+ local order = tree._pendingAncestorOrder
848
+ if order == nil then
849
+ return
850
+ end
851
+ local pending = tree._pendingAncestors :: any
852
+ for i = #order, mark + 1, -1 do
853
+ pending[order[i]] = nil
854
+ order[i] = nil
855
+ end
856
+ if mark == 0 then
857
+ tree._pendingAncestors = nil
858
+ tree._pendingAncestorOrder = nil
859
+ end
860
+ end
861
+
862
+ -- Stands in for "this path held nothing" in a descendant snapshot: `olds[key] = nil`
863
+ -- stores no entry, so an absent-to-present descendant would be invisible to the diff.
864
+ -- That is the ordinary case, not an edge one (every appended array element).
865
+ local ABSENT = table.freeze({})
866
+
867
+ -- A whole-table write changes every leaf beneath it, but `fire` touches only that
868
+ -- pathKey and `fireAncestors` walks upward, so a descendant listener would never hear
869
+ -- about it. These two snapshot the observed descendants before the write and fire
870
+ -- whichever changed after it. Scoped to STRICT descendants: the written path is fired
871
+ -- by the caller, and including it would double-fire the container's own observer.
872
+ local function snapshotDescendants(tree: Tree, pathKey: string): { [string]: any }?
873
+ if next(tree._listeners) == nil then
874
+ return nil
875
+ end
876
+ -- Indexed, not swept: _descendants answers this in one lookup, so a write does
877
+ -- not cost a prefix match against every path the game is listening to.
878
+ local below = tree._descendants[pathKey]
879
+ if below == nil then
880
+ return nil
881
+ end
882
+ local olds: { [string]: any }? = nil
883
+ for key in below do
884
+ local byEvent = tree._listeners[key]
885
+ if byEvent and byEvent.Changed then
886
+ local path = tree._paths[key]
887
+ if path then
888
+ olds = olds or {}
889
+ local was = readValue(tree, path)
890
+ local slot = olds :: { [string]: any }
891
+ slot[key] = if was == nil then ABSENT else was
892
+ end
893
+ end
894
+ end
895
+ return olds
896
+ end
897
+
898
+ local function fireDescendants(tree: Tree, olds: { [string]: any }?)
899
+ if not olds then
900
+ return
901
+ end
902
+ -- Collect before firing: a fired listener may add or remove listeners.
903
+ local pending: { { Key: string, New: any, Old: any } } = {}
904
+ for key, parked in olds do
905
+ local path = tree._paths[key]
906
+ if path then
907
+ local old = if parked == ABSENT then nil else parked
908
+ local current = readValue(tree, path)
909
+ -- Identity, not leafEquals, which reports tables as never equal. Both sides
910
+ -- are the same path read before and after one mutation, so a container still
911
+ -- holding its original table held its contents too. Insert at the tail
912
+ -- depends on this, or it wakes every bound row in the array.
913
+ if current ~= old then
914
+ table.insert(pending, { Key = key, New = current, Old = old })
915
+ end
916
+ end
917
+ end
918
+ for _, item in pending do
919
+ fire(tree, item.Key, "Changed", item.New, item.Old)
920
+ end
921
+ end
922
+
923
+ -- Key transitions for the containers a whole-table write REWRITES. applySet reports only
924
+ -- the one key it wrote, so a Set at an ancestor would add or drop keys further down with
925
+ -- nothing saying so. Scoped to STRICT descendants, like `snapshotDescendants`: the
926
+ -- written path's own contents are a bulk state change. The snapshot is a shallow
927
+ -- key -> value map per container bound to OnKeyAdded/OnKeyRemoved.
928
+ type KeyedSnapshot = {
929
+ Key: string,
930
+ Path: { string | number },
931
+ Schema: SchemaNode?,
932
+ Old: { [any]: any },
933
+ }
934
+
935
+ -- Resolve the schema at `path` starting from the node that sits at depth `from - 1`.
936
+ local function schemaBelow(base: SchemaNode?, path: { string | number }, from: number): SchemaNode?
937
+ local node = base
938
+ for i = from, #path do
939
+ if node == nil then
940
+ return nil
941
+ end
942
+ node = Template.ChildSchema(node, path[i])
943
+ end
944
+ return node
945
+ end
946
+
947
+ -- The same dynamic-key test applySet applies to a direct parent: a DECLARED child is
948
+ -- part of a record's fixed shape, so it never appears or disappears as a key.
949
+ local function isDynamicKey(node: SchemaNode?, key: any): boolean
950
+ local declared = if node then node.Children else nil
951
+ return declared == nil or type(key) ~= "string" or declared[key :: string] == nil
952
+ end
953
+
954
+ local function snapshotKeyed(tree: Tree, pathKey: string, depth: number, schema: SchemaNode?): { KeyedSnapshot }?
955
+ local below = tree._descendants[pathKey]
956
+ if below == nil then
957
+ return nil
958
+ end
959
+ local out: { KeyedSnapshot }? = nil
960
+ for key in below do
961
+ local byEvent = tree._listeners[key]
962
+ if byEvent ~= nil and (byEvent.OnKeyAdded ~= nil or byEvent.OnKeyRemoved ~= nil) then
963
+ local p = tree._paths[key]
964
+ if p ~= nil then
965
+ local node = schemaBelow(schema, p, depth + 1)
966
+ -- A Scribe.Big and a Scribe.Flags are leaves that merely store as
967
+ -- tables: their keys are an encoding, not container entries.
968
+ if node == nil or (node.ValueType ~= "big" and node.ValueType ~= "flags") then
969
+ local current = readValue(tree, p)
970
+ local olds: { [any]: any } = {}
971
+ if type(current) == "table" then
972
+ for k, v in current :: { [any]: any } do
973
+ olds[k] = v
974
+ end
975
+ end
976
+ local list = out or {}
977
+ out = list
978
+ list[#list + 1] = { Key = key, Path = p, Schema = node, Old = olds }
979
+ end
980
+ end
981
+ end
982
+ end
983
+ return out
984
+ end
985
+
986
+ local function fireKeyDeltas(tree: Tree, snapshots: { KeyedSnapshot }?)
987
+ if snapshots == nil then
988
+ return
989
+ end
990
+ for _, entry in snapshots do
991
+ local current = readValue(tree, entry.Path)
992
+ local new: { [any]: any } = if type(current) == "table" then current :: any else {}
993
+ local old = entry.Old
994
+ for k, v in new do
995
+ if old[k] == nil and isDynamicKey(entry.Schema, k) then
996
+ fire(tree, entry.Key, "OnKeyAdded", k, v)
997
+ end
998
+ end
999
+ for k, v in old do
1000
+ if new[k] == nil and isDynamicKey(entry.Schema, k) then
1001
+ fire(tree, entry.Key, "OnKeyRemoved", k, v)
1002
+ end
1003
+ end
1004
+ end
1005
+ end
1006
+
1007
+ -- Tier-1 validation ----------------------------------------------------------
1008
+
1009
+ local function anomaly(tree: Tree, path: { string | number }, value: any, reason: string)
1010
+ if tree.Params.OnAnomaly then
1011
+ tree.Params.OnAnomaly(path, value, reason)
1012
+ end
1013
+ end
1014
+
1015
+ local function validationError(path: { string | number }, message: string): never
1016
+ error(`Scribe: invalid write to "{Util.pathString(path)}": {message}`, 0)
1017
+ end
1018
+
1019
+ -- Matches the wire codec's recursion cap (Wire.luau); a value that passes
1020
+ -- validation must always be encodable, so over-deep tables are rejected here.
1021
+ local MAX_VALUE_DEPTH = Util.MAX_VALUE_DEPTH
1022
+
1023
+ -- Truncate `s` to at most `maxBytes` without splitting a multi-byte UTF-8 character; a
1024
+ -- half-encoded trailing character fails the DataStore save. Callers pass an
1025
+ -- already-validated string, so the loop runs at most 3 times.
1026
+ local function truncateUtf8(s: string, maxBytes: number): string
1027
+ if #s <= maxBytes then
1028
+ return s
1029
+ end
1030
+ local cut = maxBytes
1031
+ while cut > 0 do
1032
+ local nextByte = string.byte(s, cut + 1)
1033
+ if nextByte == nil or nextByte < 0x80 or nextByte >= 0xC0 then
1034
+ break -- byte after the cut starts a fresh character (or end of string)
1035
+ end
1036
+ cut -= 1
1037
+ end
1038
+ return string.sub(s, 1, cut)
1039
+ end
1040
+
1041
+ -- Returns the (possibly clamped) value to write. Throws on type violations.
1042
+ local function validateWrite(
1043
+ tree: Tree,
1044
+ schema: SchemaNode?,
1045
+ path: { string | number },
1046
+ value: any,
1047
+ depth: number?
1048
+ ): any
1049
+ if value == nil then
1050
+ return nil
1051
+ end
1052
+ -- Depth is budgeted from the ROOT, because Init snapshots re-encode the whole
1053
+ -- root from depth 0: a value that is not encodable from there silently drops
1054
+ -- the entire root from every snapshot.
1055
+ local d = depth or math.max(0, #path - 1)
1056
+ if d > MAX_VALUE_DEPTH then
1057
+ validationError(path, `nested deeper than {MAX_VALUE_DEPTH} levels from the root`)
1058
+ end
1059
+
1060
+ -- Declared datatype fields accept their Roblox datatype (packed here) or an
1061
+ -- already-packed buffer. Checked before the generic type gate, which would
1062
+ -- otherwise reject the userdata.
1063
+ if schema and schema.ValueType == "datatype" then
1064
+ local name = schema.Datatype :: string
1065
+ if typeof(value) == name then
1066
+ -- Precision is nil for a field that did not declare one. The template
1067
+ -- compiler has already refused any value a codec would reject, so this
1068
+ -- cannot fail on the Precision itself.
1069
+ local ok, packed = pcall(Datatypes.Pack, name, value, schema.Precision)
1070
+ if not ok then
1071
+ if type(packed) == "string" and string.find(packed, Datatypes.NONFINITE, 1, true) then
1072
+ anomaly(tree, path, value, "NonFiniteComponent")
1073
+ validationError(path, `{name} has a NaN/inf component`)
1074
+ end
1075
+ validationError(path, `could not pack {name}: {tostring(packed)}`)
1076
+ end
1077
+ return packed
1078
+ end
1079
+ if type(value) == "buffer" then
1080
+ return Util.cloneBuffer(value)
1081
+ end
1082
+ validationError(path, `expected {name}, got {typeof(value)}`)
1083
+ end
1084
+
1085
+ local t = type(value)
1086
+ if t == "function" or t == "thread" or t == "userdata" or typeof(value) ~= t then
1087
+ validationError(path, `unsupported type "{typeof(value)}"`)
1088
+ end
1089
+ if t == "number" and (value ~= value or value == math.huge or value == -math.huge) then
1090
+ validationError(path, "NaN/inf")
1091
+ end
1092
+ -- Invalid UTF-8 cannot be JSON-encoded, so the ENTIRE profile save fails (error
1093
+ -- 104) silently, long after this write. Rejecting every string leaf here names the
1094
+ -- offending path at the write site instead.
1095
+ if t == "string" and not Util.isUtf8(value :: string) then
1096
+ anomaly(tree, path, value, "InvalidUtf8")
1097
+ validationError(path, "string contains invalid UTF-8 bytes")
1098
+ end
1099
+
1100
+ local vt = if schema then schema.ValueType else "any"
1101
+ local policy = tree.Params.BoundsPolicy or "Clamp"
1102
+
1103
+ if vt == "boolean" then
1104
+ if t ~= "boolean" then
1105
+ validationError(path, `expected boolean, got {t}`)
1106
+ end
1107
+ elseif vt == "number" or vt == "int" then
1108
+ if t ~= "number" then
1109
+ validationError(path, `expected number, got {t}`)
1110
+ end
1111
+ local v = value :: number
1112
+ if vt == "int" and v % 1 ~= 0 then
1113
+ if policy == "Reject" then
1114
+ validationError(path, "expected integer")
1115
+ end
1116
+ v = math.floor(v + 0.5)
1117
+ end
1118
+ local min = schema and schema.Min
1119
+ local max = schema and schema.Max
1120
+ if (min and v < min) or (max and v > max) then
1121
+ anomaly(tree, path, value, "OutOfBounds")
1122
+ if policy == "Reject" then
1123
+ validationError(path, `out of bounds [{min or "-inf"}, {max or "inf"}]`)
1124
+ end
1125
+ v = math.clamp(v, min or -math.huge, max or math.huge)
1126
+ end
1127
+ return v
1128
+ elseif vt == "big" then
1129
+ local parsed = Big.from(value)
1130
+ if parsed == nil then
1131
+ validationError(path, `expected a number or a numeric string, got {t}`)
1132
+ end
1133
+ local big = parsed :: any
1134
+ local min = schema and schema.Min
1135
+ local max = schema and schema.Max
1136
+ if min ~= nil then
1137
+ local floor = Big.from(min) :: any
1138
+ if Big.compare(big, floor) < 0 then
1139
+ anomaly(tree, path, Big.toString(big), "OutOfBounds")
1140
+ if policy == "Reject" then
1141
+ validationError(path, `below Min {Big.toString(floor)}`)
1142
+ end
1143
+ big = floor
1144
+ end
1145
+ end
1146
+ if max ~= nil then
1147
+ local ceiling = Big.from(max) :: any
1148
+ if Big.compare(big, ceiling) > 0 then
1149
+ anomaly(tree, path, Big.toString(big), "OutOfBounds")
1150
+ if policy == "Reject" then
1151
+ validationError(path, `above Max {Big.toString(ceiling)}`)
1152
+ end
1153
+ big = ceiling
1154
+ end
1155
+ end
1156
+ return Big.toStored(big)
1157
+ elseif vt == "flags" then
1158
+ if t ~= "table" then
1159
+ validationError(path, `expected a table of member names, got {t}`)
1160
+ end
1161
+ -- Normalize to declaration order with duplicates dropped, so one set of flags
1162
+ -- has one stored form and no diff downstream has to care about write order.
1163
+ local index = (schema and schema.MemberIndex) :: { [string]: number }?
1164
+ local enabled: { [string]: boolean } = {}
1165
+ for _, name in value :: { any } do
1166
+ if type(name) ~= "string" then
1167
+ validationError(path, `flag names must be strings, got {type(name)}`)
1168
+ end
1169
+ if index == nil or index[name] == nil then
1170
+ anomaly(tree, path, name, "NotAMember")
1171
+ validationError(path, `"{tostring(name)}" is not a member of the flags`)
1172
+ end
1173
+ enabled[name] = true
1174
+ end
1175
+ local out = {}
1176
+ for _, name in (schema and schema.Members) :: { string } do
1177
+ if enabled[name] then
1178
+ table.insert(out, name)
1179
+ end
1180
+ end
1181
+ return out
1182
+ elseif vt == "string" or vt == "enum" then
1183
+ if t ~= "string" then
1184
+ validationError(path, `expected string, got {t}`)
1185
+ end
1186
+ if vt == "enum" then
1187
+ local index = schema and schema.MemberIndex
1188
+ if index and index[value] == nil then
1189
+ anomaly(tree, path, value, "NotAMember")
1190
+ validationError(path, `"{value}" is not a member of the enum`)
1191
+ end
1192
+ end
1193
+ local maxLength = schema and schema.MaxLength
1194
+ if maxLength and #(value :: string) > maxLength then
1195
+ anomaly(tree, path, value, "OverMaxLength")
1196
+ if policy == "Reject" then
1197
+ validationError(path, `exceeds MaxLength {maxLength}`)
1198
+ end
1199
+ -- Truncate on a character boundary: MaxLength is a byte budget, and a raw
1200
+ -- string.sub could split a multi-byte character and fail the save.
1201
+ return truncateUtf8(value :: string, maxLength)
1202
+ end
1203
+ elseif vt == "buffer" then
1204
+ if t ~= "buffer" then
1205
+ validationError(path, `expected buffer, got {t}`)
1206
+ end
1207
+ elseif vt == "table" then
1208
+ if t ~= "table" then
1209
+ validationError(path, `expected table, got {t}`)
1210
+ end
1211
+ end
1212
+
1213
+ if t == "buffer" then
1214
+ -- Buffers are mutable: store a private copy so a caller-held reference
1215
+ -- can't bypass replication later.
1216
+ return Util.cloneBuffer(value)
1217
+ end
1218
+
1219
+ if t == "table" then
1220
+ -- Recursive Tier-1 over the written table. A numeric key N and the string key
1221
+ -- tostring(N) produce the SAME pathKey, so they would alias distinct slots in
1222
+ -- listeners, coalescing and rollback. Only scanned when numeric keys exist.
1223
+ if Util.hasNumericKeys(value :: any) then
1224
+ for k in value :: any do
1225
+ -- A mixed table cannot be JSON-encoded, so the whole profile save fails
1226
+ -- later, far from this write. This also subsumes the alias pair above.
1227
+ if type(k) == "string" then
1228
+ validationError(
1229
+ path,
1230
+ "a table cannot mix array indices and string keys (it would fail the DataStore save)"
1231
+ )
1232
+ end
1233
+ end
1234
+ end
1235
+ -- A whole-container write must match the declared key shape, or a pure-dictionary
1236
+ -- payload passes the plain table gate above and lands under a `{ Record }` field.
1237
+ local container = if schema then schema.Container else nil
1238
+ if container ~= nil then
1239
+ local declared = schema :: SchemaNode
1240
+ local count = 0
1241
+ local maxIndex = 0
1242
+ for k in value do
1243
+ count += 1
1244
+ if container == "Array" then
1245
+ if type(k) ~= "number" then
1246
+ validationError(path, `Scribe.ArrayOf takes array entries, but "{tostring(k)}" is a string key`)
1247
+ end
1248
+ if (k :: number) > maxIndex then
1249
+ maxIndex = k :: number
1250
+ end
1251
+ elseif declared.KeyType == "integer" then
1252
+ -- A Scribe.MapOf("integer") declares its key type, so judge against that
1253
+ -- and not DictOf's string assumption, which would refuse the map's own
1254
+ -- keys and accept the ones it cannot store.
1255
+ if type(k) ~= "number" then
1256
+ validationError(
1257
+ path,
1258
+ `Scribe.MapOf("integer") takes integer keys, but "{tostring(k)}" is a string key`
1259
+ )
1260
+ end
1261
+ local n = k :: number
1262
+ if n ~= n or n == math.huge or n == -math.huge or n % 1 ~= 0 then
1263
+ validationError(path, `key {tostring(k)} is not a finite integer`)
1264
+ end
1265
+ else
1266
+ if type(k) ~= "string" then
1267
+ validationError(path, `Scribe.DictOf takes string keys, but {tostring(k)} is a number key`)
1268
+ end
1269
+ local maxKeyLength = declared.MaxKeyLength
1270
+ if maxKeyLength and #(k :: string) > maxKeyLength then
1271
+ validationError(path, `key "{k}" is {#(k :: string)} bytes, over MaxKeyLength {maxKeyLength}`)
1272
+ end
1273
+ end
1274
+ end
1275
+ -- A container already over cap in storage (a newer-template server wrote it
1276
+ -- before this server's lower cap deployed) stays writable; only growth is refused.
1277
+ local function storedCount(): number
1278
+ local stored = readValue(tree, path)
1279
+ return if type(stored) == "table" then Util.count(stored) else 0
1280
+ end
1281
+ if container == "Array" then
1282
+ -- `#value` stops at the first hole, so compare against the HIGHEST key
1283
+ -- instead: a ragged payload always has maxIndex > count.
1284
+ if count ~= maxIndex then
1285
+ validationError(path, "array entries must run contiguously from 1 (no holes)")
1286
+ end
1287
+ local maxItems = declared.MaxItems
1288
+ if maxItems then
1289
+ -- A set is stored deduplicated, so its cap is on MEMBERSHIP: counting the
1290
+ -- caller's raw array would refuse Set({1,1,1}) against MaxItems 2.
1291
+ local effective = count
1292
+ if declared.Unique then
1293
+ local seen: { [any]: boolean } = {}
1294
+ effective = 0
1295
+ for _, item in value do
1296
+ if not seen[item] then
1297
+ seen[item] = true
1298
+ effective += 1
1299
+ end
1300
+ end
1301
+ end
1302
+ if effective > maxItems and effective > storedCount() then
1303
+ validationError(path, `holds {effective} entries, over MaxItems {maxItems}`)
1304
+ end
1305
+ end
1306
+ else
1307
+ local maxKeys = declared.MaxKeys
1308
+ if maxKeys and count > maxKeys and count > storedCount() then
1309
+ validationError(path, `holds {count} keys, over MaxKeys {maxKeys}`)
1310
+ end
1311
+ end
1312
+ end
1313
+
1314
+ local out = {}
1315
+ for k, v in value do
1316
+ local kt = type(k)
1317
+ if kt ~= "string" and kt ~= "number" then
1318
+ validationError(path, `unsupported key type "{kt}"`)
1319
+ end
1320
+ if kt == "number" then
1321
+ -- Non-integer or non-finite numeric keys do not survive the DataStore
1322
+ -- JSON round trip.
1323
+ if k ~= k or k == math.huge or k == -math.huge or k % 1 ~= 0 then
1324
+ validationError(path, "invalid numeric key (must be a finite integer)")
1325
+ end
1326
+ else
1327
+ local ks = k :: string
1328
+ if string.find(ks, "\31", 1, true) then
1329
+ -- char 31 is the pathKey separator; a key containing it would
1330
+ -- alias a distinct path in coalescing/listeners/rollback.
1331
+ validationError(path, "string key may not contain control character \\31")
1332
+ end
1333
+ -- A JSON object key must be valid UTF-8 too; an invalid-byte key
1334
+ -- fails the whole profile save exactly like an invalid string value.
1335
+ if not Util.isUtf8(ks) then
1336
+ validationError(path, "string key contains invalid UTF-8 bytes")
1337
+ end
1338
+ end
1339
+ local childSchema = if schema then Template.ChildSchema(schema, k) else nil
1340
+ -- A declared element record has a fixed field set, so an undeclared key is a
1341
+ -- typo. The exception: a key this profile already stores was written by a newer
1342
+ -- template during a rolling deploy, and rejecting it would turn every
1343
+ -- read-modify-write on an old server into a lost write.
1344
+ if childSchema == nil and schema and schema.Closed then
1345
+ local stored = readValue(tree, path)
1346
+ if not (type(stored) == "table" and stored[k] ~= nil) then
1347
+ validationError(path, `"{tostring(k)}" is not a declared field of this element shape`)
1348
+ end
1349
+ end
1350
+ local childPath = table.clone(path)
1351
+ table.insert(childPath, k)
1352
+ out[k] = validateWrite(tree, childSchema, childPath, v, d + 1)
1353
+ end
1354
+ -- Fill declared element fields the caller omitted: the element type says they are
1355
+ -- always present, so a partial element nil-crashes every consumer typed against
1356
+ -- it. Scribe.Optional fields have no default and stay absent.
1357
+ if schema and schema.Closed and schema.Children then
1358
+ for name, child in schema.Children do
1359
+ if out[name] == nil and child.Default ~= nil then
1360
+ -- A mirror never fills a ServerOnly field: no replicated op would have
1361
+ -- sent it, so an optimistic local write would visibly diverge.
1362
+ if tree.Params.IsServer or child.Visibility ~= "ServerOnly" then
1363
+ out[name] = Util.deepClone(child.Default)
1364
+ end
1365
+ end
1366
+ end
1367
+ end
1368
+ if schema and schema.Unique then
1369
+ -- Deduplicate and sort so a set has one stored form whatever the write
1370
+ -- order. Safe because Template refuses any set element that is not an
1371
+ -- orderable scalar.
1372
+ local seen: { [any]: boolean } = {}
1373
+ local unique = {}
1374
+ for _, item in out do
1375
+ if not seen[item] then
1376
+ seen[item] = true
1377
+ table.insert(unique, item)
1378
+ end
1379
+ end
1380
+ table.sort(unique)
1381
+ return unique
1382
+ end
1383
+ return out
1384
+ end
1385
+
1386
+ return value
1387
+ end
1388
+
1389
+ -- Mutation core ----------------------------------------------------------------
1390
+
1391
+ type WriteOpts = {
1392
+ Replicate: boolean?,
1393
+ FromRemote: boolean?,
1394
+ NoOp: boolean?, -- rollback writes: fire listeners but never emit ops
1395
+ NoValidate: boolean?,
1396
+ }
1397
+
1398
+ local function emitOp(tree: Tree, op: Op, schema: SchemaNode?, opts: WriteOpts)
1399
+ if opts.NoOp or opts.FromRemote or opts.Replicate == false then
1400
+ return
1401
+ end
1402
+ local onOp = tree.Params.OnOp
1403
+ if onOp == nil then
1404
+ return
1405
+ end
1406
+ if tree._txn then
1407
+ table.insert(tree._txn.Ops, { Op = op, Schema = schema })
1408
+ else
1409
+ onOp(op, schema)
1410
+ end
1411
+ end
1412
+
1413
+ -- Derived fields ---------------------------------------------------------------
1414
+ -- A recompute is an ordinary write through applySet, so bounds, coalescing,
1415
+ -- listeners, transactions and replication all keep working. This layer only decides
1416
+ -- WHEN to recompute.
1417
+
1418
+ -- A listener fired by a recompute may write an input, re-dirtying the field that
1419
+ -- fired it. Bounded so a feedback loop is reported rather than hanging the writer.
1420
+ local MAX_SETTLE_PASSES = 4
1421
+
1422
+ -- Assigned below applyClear: settling writes through applySet.
1423
+ local settleDerived: (tree: Tree) -> ()
1424
+
1425
+ local function markDerivedDirty(tree: Tree, pathKey: string)
1426
+ local dependents = tree.Compiled.DerivedByWrite[pathKey]
1427
+ if dependents == nil then
1428
+ return
1429
+ end
1430
+ local dirty = tree._derivedDirty
1431
+ if dirty == nil then
1432
+ dirty = {}
1433
+ tree._derivedDirty = dirty
1434
+ end
1435
+ for _, node in dependents do
1436
+ (dirty :: any)[node] = true
1437
+ end
1438
+ end
1439
+
1440
+ -- A write settles immediately unless something else is already going to settle for
1441
+ -- it: inside a batch the flush does, inside a transaction the commit does, during a
1442
+ -- replay ReplayFire does (once, after the whole snapshot has landed), and inside a
1443
+ -- settle pass the pass itself does.
1444
+ local function settleAfterWrite(tree: Tree)
1445
+ if
1446
+ tree._derivedDirty == nil
1447
+ or tree._derivedSettling
1448
+ or tree._batchDepth > 0
1449
+ or tree._txn ~= nil
1450
+ or tree._replaying
1451
+ then
1452
+ return
1453
+ end
1454
+ settleDerived(tree)
1455
+ end
1456
+
1457
+ -- Per-transaction mirror of the tree's _descendants index: ancestor pathKey -> the
1458
+ -- snapshot keys strictly below it, so a snapshot can absorb the ones underneath it
1459
+ -- without scanning every snapshot in the transaction.
1460
+ local function indexSnapshot(txn: any, pathKey: string)
1461
+ forEachAncestorKey(pathKey, function(ancestor)
1462
+ local set = txn.Below[ancestor]
1463
+ if set == nil then
1464
+ set = {}
1465
+ txn.Below[ancestor] = set
1466
+ end
1467
+ set[pathKey] = true
1468
+ end)
1469
+ end
1470
+
1471
+ local function unindexSnapshot(txn: any, pathKey: string)
1472
+ forEachAncestorKey(pathKey, function(ancestor)
1473
+ local set = txn.Below[ancestor]
1474
+ if set ~= nil then
1475
+ set[pathKey] = nil
1476
+ if next(set) == nil then
1477
+ txn.Below[ancestor] = nil
1478
+ end
1479
+ end
1480
+ end)
1481
+ end
1482
+
1483
+ -- Whether `a` is a strict ancestor path of `b` (a shorter, matching prefix).
1484
+ local function pathIsStrictAncestor(a: { string | number }, b: { string | number }): boolean
1485
+ if #a >= #b then
1486
+ return false
1487
+ end
1488
+ for i = 1, #a do
1489
+ if a[i] ~= b[i] then
1490
+ return false
1491
+ end
1492
+ end
1493
+ return true
1494
+ end
1495
+
1496
+ -- Restore `value` at a relative path inside `root`, creating tables as needed.
1497
+ local function setNested(root: { [any]: any }, relPath: { string | number }, value: any)
1498
+ local container = root
1499
+ for i = 1, #relPath - 1 do
1500
+ local seg = relPath[i]
1501
+ local nextContainer = container[seg]
1502
+ if type(nextContainer) ~= "table" then
1503
+ nextContainer = {}
1504
+ forgetContainer(container)
1505
+ container[seg] = nextContainer
1506
+ end
1507
+ container = nextContainer
1508
+ end
1509
+ forgetContainer(container)
1510
+ container[relPath[#relPath]] = value
1511
+ end
1512
+
1513
+ -- Remove `relPath` from `root` WITHOUT creating any intermediate tables (unlike
1514
+ -- setNested). Used to strip txn-materialized descendant containers out of a rollback
1515
+ -- reconstruction so no phantom empty sub-table survives.
1516
+ local function removeNested(root: { [any]: any }, relPath: { string | number })
1517
+ local container = root
1518
+ for i = 1, #relPath - 1 do
1519
+ local nextContainer = container[relPath[i]]
1520
+ if type(nextContainer) ~= "table" then
1521
+ return
1522
+ end
1523
+ container = nextContainer
1524
+ end
1525
+ container[relPath[#relPath]] = nil
1526
+ end
1527
+
1528
+ -- Records the pre-transaction value of `path`, keeping snapshots DISJOINT so rollback
1529
+ -- order is irrelevant. An ancestor snapshot already covers this subtree; earlier
1530
+ -- descendant snapshots are overlaid onto the current value and then dropped.
1531
+ local function snapshotForTxn(tree: Tree, path: { string | number }, pathKey: string, oldValue: any)
1532
+ local txn = tree._txn
1533
+ if not txn or txn.Snapshots[pathKey] ~= nil then
1534
+ return
1535
+ end
1536
+ -- Already covered by an ancestor snapshot? Walk THIS path's ancestor keys rather than
1537
+ -- every snapshot taken so far, which made a transaction quadratic in the number of
1538
+ -- distinct paths it touched. The real path comparison still runs on a hit: it is
1539
+ -- O(depth) and it decides whether a rollback restores the correct subtree.
1540
+ local at = string.find(pathKey, "\31", 1, true)
1541
+ while at do
1542
+ local ancestorSnap = txn.Snapshots[string.sub(pathKey, 1, at - 1)]
1543
+ if ancestorSnap ~= nil and pathIsStrictAncestor(ancestorSnap.Path, path) then
1544
+ return
1545
+ end
1546
+ at = string.find(pathKey, "\31", at + 1, true)
1547
+ end
1548
+ local value = Util.deepClone(oldValue)
1549
+ -- Track which descendant snapshots get overlaid: each is the authoritative
1550
+ -- pre-txn state at its path, which the Created-strip below must not undo.
1551
+ local overlaid: { { string | number } }? = nil
1552
+ -- Snapshots strictly BELOW this path, by lookup. Collected first because
1553
+ -- absorbing one removes it from the same index being iterated.
1554
+ local belowSet = txn.Below[pathKey]
1555
+ if belowSet ~= nil then
1556
+ local descKeys: { string } = {}
1557
+ for descKey in belowSet do
1558
+ descKeys[#descKeys + 1] = descKey
1559
+ end
1560
+ for _, descKey in descKeys do
1561
+ local snap = txn.Snapshots[descKey]
1562
+ if snap ~= nil and pathIsStrictAncestor(path, snap.Path) then
1563
+ if type(value) ~= "table" then
1564
+ value = {}
1565
+ end
1566
+ local relPath = table.move(
1567
+ snap.Path,
1568
+ #path + 1,
1569
+ #snap.Path,
1570
+ 1,
1571
+ table.create(#snap.Path - #path) :: { string | number }
1572
+ )
1573
+ setNested(value, relPath, snap.Value)
1574
+ overlaid = overlaid or {}
1575
+ table.insert(overlaid :: { { string | number } }, snap.Path)
1576
+ txn.Snapshots[descKey] = nil
1577
+ unindexSnapshot(txn, descKey)
1578
+ end
1579
+ end
1580
+ end
1581
+ -- Reconcile against containers materialized during this txn, so a rollback cannot
1582
+ -- resurrect them as phantom empty tables: either the snapshotted container itself was
1583
+ -- created (pre-txn value is nil), or a strict descendant was (strip it out). Only
1584
+ -- strip a created path when NO overlaid snapshot sits at or above it: Created also
1585
+ -- records a pre-existing container deleted and recreated inside this txn, whose
1586
+ -- overlay re-established genuine pre-txn state that stripping would destroy.
1587
+ local function establishedByOverlay(createdPath: { string | number }): boolean
1588
+ if not overlaid then
1589
+ return false
1590
+ end
1591
+ for _, snapPath in overlaid :: { { string | number } } do
1592
+ if #snapPath <= #createdPath then
1593
+ local isPrefix = true
1594
+ for i = 1, #snapPath do
1595
+ if snapPath[i] ~= createdPath[i] then
1596
+ isPrefix = false
1597
+ break
1598
+ end
1599
+ end
1600
+ if isPrefix then
1601
+ return true
1602
+ end
1603
+ end
1604
+ end
1605
+ return false
1606
+ end
1607
+ if value ~= nil then
1608
+ local pathCreated = false
1609
+ for _, createdPath in txn.Created do
1610
+ if #createdPath == #path then
1611
+ local same = true
1612
+ for i = 1, #path do
1613
+ if createdPath[i] ~= path[i] then
1614
+ same = false
1615
+ break
1616
+ end
1617
+ end
1618
+ if same then
1619
+ pathCreated = true
1620
+ break
1621
+ end
1622
+ end
1623
+ end
1624
+ if pathCreated then
1625
+ value = nil
1626
+ elseif type(value) == "table" then
1627
+ for _, createdPath in txn.Created do
1628
+ if pathIsStrictAncestor(path, createdPath) and not establishedByOverlay(createdPath) then
1629
+ local relPath: { string | number } = {}
1630
+ for i = #path + 1, #createdPath do
1631
+ relPath[#relPath + 1] = createdPath[i]
1632
+ end
1633
+ removeNested(value, relPath)
1634
+ end
1635
+ end
1636
+ end
1637
+ end
1638
+ txn.Snapshots[pathKey] = { Path = table.clone(path), Value = value }
1639
+ indexSnapshot(txn, pathKey)
1640
+ end
1641
+
1642
+ local applySet: (Tree, { string | number }, SchemaNode?, any, WriteOpts) -> any
1643
+
1644
+ -- Materializes every missing DECLARED-ELEMENT intermediate along `path` as a real
1645
+ -- applySet write of the element's defaults, before the caller's own write resolves the
1646
+ -- chain. That makes materialization visible everywhere a write is: the element Set
1647
+ -- replicates (so a schema-less Shared mirror rebuilds the full element, not a bare {}),
1648
+ -- OnKeyAdded fires, a transaction can roll the creation back, and a later leaf write
1649
+ -- equal to the default no-ops safely. Untyped intermediates keep their silent plain-{}
1650
+ -- materialization in resolveContainer.
1651
+ local function seedMissingElements(tree: Tree, path: { string | number }, schema: SchemaNode?, opts: WriteOpts)
1652
+ local n = #path
1653
+ if n < 2 or schema == nil then
1654
+ return
1655
+ end
1656
+ local chain = table.create(n) :: { SchemaNode }
1657
+ local cursor: SchemaNode? = schema
1658
+ for i = n, 1, -1 do
1659
+ if cursor == nil then
1660
+ break
1661
+ end
1662
+ chain[i] = cursor
1663
+ cursor = cursor.Parent
1664
+ end
1665
+ local validating = not opts.NoValidate and not opts.FromRemote
1666
+ local container: any = storeFor(tree, path[1])
1667
+ for i = 1, n - 1 do
1668
+ if type(container) ~= "table" then
1669
+ return -- the caller's own resolve reports the real error
1670
+ end
1671
+ local seg = path[i]
1672
+ local nextContainer = container[seg]
1673
+ if nextContainer == nil then
1674
+ local createdSchema = chain[i]
1675
+ if createdSchema and createdSchema.IsElement then
1676
+ local seed = if tree.Params.IsServer then createdSchema.Default else createdSchema.ClientDefault
1677
+ if type(seed) == "table" then
1678
+ -- The element's own key must satisfy its container's rules before the
1679
+ -- seed write lands, which runs NoValidate on an already-stored form.
1680
+ if validating and i > 1 then
1681
+ checkContainerKey(chain[i - 1], container, seg, path, i - 1)
1682
+ -- The same alias guard resolveContainer applies. Seeding reaches the
1683
+ -- container first, so resolveContainer's own check would see a key
1684
+ -- that already exists and never run. Unreachable today only because
1685
+ -- checkContainerKey above rejects the mismatched form, which is a
1686
+ -- guard in another function, so this stays.
1687
+ local alias = aliasForm(seg)
1688
+ if alias ~= nil and container[alias] ~= nil then
1689
+ error(
1690
+ `Scribe: key "{tostring(seg)}" at "{Util.pathString(path)}" collides with the `
1691
+ .. `existing "{tostring(alias)}" key form (a numeric key and its string form `
1692
+ .. "cannot coexist)",
1693
+ 0
1694
+ )
1695
+ end
1696
+ end
1697
+ local prefix = table.move(path, 1, i, 1, table.create(i) :: { string | number })
1698
+ -- This element exists because a write descended THROUGH its key, not
1699
+ -- because anything asked for it. Recorded inside transactions only, for
1700
+ -- the receipt path. Deliberately NOT txn.Created, which rollback
1701
+ -- consumes: this list is observational.
1702
+ local seedTxn = tree._txn
1703
+ if seedTxn then
1704
+ seedTxn.Seeded[#seedTxn.Seeded + 1] = prefix
1705
+ end
1706
+ applySet(tree, prefix, createdSchema, Util.deepClone(seed), {
1707
+ NoValidate = true,
1708
+ FromRemote = opts.FromRemote,
1709
+ Replicate = opts.Replicate,
1710
+ })
1711
+ nextContainer = container[seg]
1712
+ end
1713
+ end
1714
+ if nextContainer == nil then
1715
+ return -- untyped intermediate: created silently by resolveContainer
1716
+ end
1717
+ end
1718
+ container = nextContainer
1719
+ end
1720
+ end
1721
+
1722
+ -- Value equality for the three leaves whose canonical stored form is a table or a
1723
+ -- buffer, which `Util.leafEquals` always reports as changed; without it a no-op Set on
1724
+ -- one fires Changed and replicates. Safe because validateWrite has just rebuilt the
1725
+ -- value into Scribe's own normal form, of bounded size and never handed out by
1726
+ -- reference. Deliberately NOT extended to user tables, Scribe.SetOf or containers: a
1727
+ -- deep compare there is unbounded, and a whole-table Set is how a caller replaces a
1728
+ -- table.
1729
+ local function canonicalStoredEquals(schema: SchemaNode?, old: any, new: any): boolean
1730
+ if schema == nil then
1731
+ return false
1732
+ end
1733
+ local vt = schema.ValueType
1734
+ if vt == "big" then
1735
+ -- Big.toStored is exactly two numbers, and normalize() snaps the mantissa
1736
+ -- through "%.15g" precisely so that one value has ONE stored pair.
1737
+ return type(old) == "table"
1738
+ and type(new) == "table"
1739
+ and #(old :: { any }) == 2
1740
+ and #(new :: { any }) == 2
1741
+ and (old :: { any })[1] == (new :: { any })[1]
1742
+ and (old :: { any })[2] == (new :: { any })[2]
1743
+ elseif vt == "datatype" then
1744
+ -- Byte-for-byte on the PACKED form. Packing is deterministic, so an equal
1745
+ -- value re-packs to equal bytes; a lossy round trip just fails this test and
1746
+ -- writes, which is the safe direction to be wrong in.
1747
+ return type(old) == "buffer" and type(new) == "buffer" and Util.bufferEquals(old :: buffer, new :: buffer)
1748
+ elseif vt == "flags" then
1749
+ if type(old) ~= "table" or type(new) ~= "table" then
1750
+ return false
1751
+ end
1752
+ local a, b = old :: { any }, new :: { any }
1753
+ if #a ~= #b then
1754
+ return false
1755
+ end
1756
+ for i = 1, #a do
1757
+ if a[i] ~= b[i] then
1758
+ return false
1759
+ end
1760
+ end
1761
+ -- Both sides are member names in declaration order, so element-by-element
1762
+ -- equality IS set equality. An out-of-order stored value fails and writes,
1763
+ -- which canonicalizes it.
1764
+ return true
1765
+ end
1766
+ return false
1767
+ end
1768
+
1769
+ function applySet(tree: Tree, path: { string | number }, schema: SchemaNode?, value: any, opts: WriteOpts): any
1770
+ -- validateWrite rebuilds tables entry-by-entry (no aliasing); unvalidated
1771
+ -- table writes are cloned explicitly instead.
1772
+ local newValue = if opts.NoValidate then value else validateWrite(tree, schema, path, value)
1773
+ if type(newValue) == "table" and opts.NoValidate then
1774
+ newValue = Util.deepClone(newValue)
1775
+ end
1776
+
1777
+ -- A REMOTE nil-Set materializes missing parents: the server only emits a removal
1778
+ -- when the parent chain existed, so a mirror missing them lost the creating op to
1779
+ -- coalescing and the server still holds them. Creating them here keeps existence
1780
+ -- and Count() parity; local writes keep the no-op semantics. Seeding runs AFTER
1781
+ -- validateWrite so a rejected value leaves no phantom element behind.
1782
+ if newValue ~= nil or opts.FromRemote == true then
1783
+ seedMissingElements(tree, path, schema, opts)
1784
+ end
1785
+ local container, key = resolveContainer(
1786
+ tree,
1787
+ path,
1788
+ newValue ~= nil or opts.FromRemote == true,
1789
+ schema,
1790
+ not opts.NoValidate and not opts.FromRemote
1791
+ )
1792
+ if container == nil then
1793
+ if newValue == nil then
1794
+ return nil -- removing under a missing parent is a no-op
1795
+ end
1796
+ error(`Scribe: cannot write to "{Util.pathString(path)}"`, 0)
1797
+ end
1798
+
1799
+ -- Reject a keyed write whose other-typed form already occupies the container
1800
+ -- (number 7 vs string "7"), because their pathKeys alias. Local validated writes
1801
+ -- only; remote and restore writes are trusted.
1802
+ if not opts.NoValidate and not opts.FromRemote then
1803
+ -- The last segment is a key of its parent, so the container's key rules apply
1804
+ -- to it too; resolveContainer only saw the intermediate ones. Removals are
1805
+ -- checked because a nil write to a middle array index punches a hole.
1806
+ if schema and schema.Parent then
1807
+ checkContainerKey(schema.Parent, container, key, path, #path - 1, newValue == nil)
1808
+ end
1809
+ -- Deleting a declared, non-Optional field of a closed element record stores the
1810
+ -- partial element that shape exists to prevent. Removing the WHOLE element stays
1811
+ -- legal: its parent is the container, not a record.
1812
+ if
1813
+ newValue == nil
1814
+ and schema
1815
+ and schema.Nullable ~= true
1816
+ and schema.Default ~= nil
1817
+ and schema.Parent
1818
+ and schema.Parent.Closed
1819
+ and container[key] ~= nil
1820
+ then
1821
+ error(
1822
+ `Scribe: "{Util.pathString(path)}" is a declared element field; Set a value instead of removing it `
1823
+ .. "(wrap the field in Scribe.Optional if absence is legitimate)",
1824
+ 0
1825
+ )
1826
+ end
1827
+ if newValue ~= nil then
1828
+ local aliasKey = aliasForm(key)
1829
+ if aliasKey ~= nil and container[aliasKey] ~= nil then
1830
+ error(
1831
+ `Scribe: key at "{Util.pathString(path)}" collides with the existing "{tostring(aliasKey)}" key `
1832
+ .. "form (a numeric key and its string form cannot coexist)",
1833
+ 0
1834
+ )
1835
+ end
1836
+ end
1837
+ end
1838
+
1839
+ local old = container[key]
1840
+ -- `not opts.NoValidate` is what makes the second test sound: only then did
1841
+ -- validateWrite build `newValue`, and only then is it in canonical stored form.
1842
+ if Util.leafEquals(old, newValue) or (not opts.NoValidate and canonicalStoredEquals(schema, old, newValue)) then
1843
+ return old
1844
+ end
1845
+
1846
+ local pathKey = Util.pathKey(path)
1847
+ -- After the no-op early-out, so an unchanged write never triggers a recompute,
1848
+ -- and before the fires, so a listener reading a derived field sees it settled.
1849
+ markDerivedDirty(tree, pathKey)
1850
+ snapshotForTxn(tree, path, pathKey, old)
1851
+ -- Snapshot observed descendants BEFORE the write; a whole-table Set changes
1852
+ -- every leaf beneath this path and only this pass can report it.
1853
+ local descendantOlds = if type(newValue) == "table" or type(old) == "table"
1854
+ then snapshotDescendants(tree, pathKey)
1855
+ else nil
1856
+ -- Only a table on one side or the other can add or drop keys BELOW this path.
1857
+ local keyedOlds = if type(newValue) == "table" or type(old) == "table"
1858
+ then snapshotKeyed(tree, pathKey, #path, schema)
1859
+ else nil
1860
+ local keyHad = old ~= nil
1861
+ container[key] = newValue
1862
+ noteKeyDelta(container, key, keyHad, newValue ~= nil)
1863
+
1864
+ emitOp(tree, { Kind = "Set", Path = table.clone(path), Value = newValue }, schema, opts)
1865
+
1866
+ fire(tree, pathKey, "Changed", newValue, old)
1867
+ -- Key transitions on a descendant container come BEFORE that container's own
1868
+ -- Changed, matching a single-key write and keeping the guarantee that a
1869
+ -- container's transitions arrive before the state fire summarizing them.
1870
+ fireKeyDeltas(tree, keyedOlds)
1871
+ fireDescendants(tree, descendantOlds)
1872
+ -- Dictionary key events on the parent (dynamic keys only).
1873
+ if #path >= 1 then
1874
+ local parentPath = table.move(path, 1, #path - 1, 1, table.create(#path - 1) :: { string | number })
1875
+ local parentSchema = if schema then schema.Parent else nil
1876
+ local isDynamic = parentSchema == nil
1877
+ or parentSchema.Children == nil
1878
+ or type(key) ~= "string"
1879
+ or parentSchema.Children[key :: string] == nil
1880
+ if isDynamic then
1881
+ local parentKey = Util.pathKey(parentPath)
1882
+ if old == nil and newValue ~= nil then
1883
+ fire(tree, parentKey, "OnKeyAdded", key, newValue)
1884
+ elseif old ~= nil and newValue == nil then
1885
+ fire(tree, parentKey, "OnKeyRemoved", key, old)
1886
+ end
1887
+ end
1888
+ end
1889
+ fireAncestors(tree, path, old, true)
1890
+ settleAfterWrite(tree)
1891
+ return newValue
1892
+ end
1893
+
1894
+ local function ensureContainerValue(tree: Tree, path: { string | number }, schema: SchemaNode?): { [any]: any }
1895
+ local container, key = resolveContainer(tree, path, true, schema)
1896
+ if container == nil then
1897
+ error(`Scribe: cannot access "{Util.pathString(path)}"`, 0)
1898
+ end
1899
+ local value = container[key]
1900
+ if value == nil then
1901
+ value = {}
1902
+ container[key] = value
1903
+ noteKeyDelta(container, key, false, true)
1904
+ elseif type(value) ~= "table" then
1905
+ error(`Scribe: "{Util.pathString(path)}" is not a container`, 0)
1906
+ end
1907
+ return value
1908
+ end
1909
+
1910
+ -- Forward declaration: applyInsert evicts through the real remove path so the client
1911
+ -- mirror receives a Remove op rather than the table quietly shrinking.
1912
+ local applyArrayRemove: (Tree, { string | number }, SchemaNode?, number?, WriteOpts) -> any
1913
+
1914
+ -- Scribe.Big and Scribe.Flags are leaves whose stored form happens to be a table, and
1915
+ -- every container mutation gates on the stored value being one: without this, Insert on
1916
+ -- a big rewrites its mantissa pair and Clear leaves a non-Optional field nil. A
1917
+ -- Scribe.SetOf is a real container, but Insert and positional writes bypass the dedupe
1918
+ -- and ordering its stored form depends on, so it is refused too.
1919
+ local function refuseStructuralWrite(schema: SchemaNode?, path: { string | number }, method: string)
1920
+ if schema == nil then
1921
+ return
1922
+ end
1923
+ local vt = schema.ValueType
1924
+ if vt == "big" then
1925
+ error(
1926
+ `Scribe: "{Util.pathString(path)}" is a Scribe.Big, not a container; {method} would rewrite its `
1927
+ .. "stored mantissa/exponent pair. Use Set, Increment, Decrement, Multiply or Divide",
1928
+ 0
1929
+ )
1930
+ elseif vt == "flags" then
1931
+ error(
1932
+ `Scribe: "{Util.pathString(path)}" is a Scribe.Flags, not a container; {method} would corrupt its `
1933
+ .. "member list. Use Enable, Disable, Toggle or Clear",
1934
+ 0
1935
+ )
1936
+ elseif schema.Unique then
1937
+ error(
1938
+ `Scribe: "{Util.pathString(path)}" is a Scribe.SetOf; {method} bypasses the dedupe and ordering `
1939
+ .. "its stored form depends on. Use Add or Remove",
1940
+ 0
1941
+ )
1942
+ end
1943
+ end
1944
+
1945
+ local function applyInsert(
1946
+ tree: Tree,
1947
+ path: { string | number },
1948
+ schema: SchemaNode?,
1949
+ item: any,
1950
+ pos: number?,
1951
+ opts: WriteOpts
1952
+ )
1953
+ -- Validation only: Tree.ApplyOp replays replicated Inserts with FromRemote and
1954
+ -- NoValidate, and a mirror momentarily ahead of the server must not throw
1955
+ -- mid-frame, which drops the frame and desyncs permanently.
1956
+ local validating = not opts.NoValidate and not opts.FromRemote
1957
+ if validating then
1958
+ refuseStructuralWrite(schema, path, "Insert")
1959
+ if schema and schema.Container == "Dict" then
1960
+ error(`Scribe: "{Util.pathString(path)}" is a Scribe.DictOf; write a key instead of calling Insert`, 0)
1961
+ end
1962
+ -- Ahead of the other refusals because the `math.clamp` below raises its own error
1963
+ -- on a non-number position, and a NaN or fractional position would silently write
1964
+ -- a hash-part index. The cost: `Insert(nil, "x")` names the position, not the nil.
1965
+ if pos ~= nil and (type(pos) ~= "number" or pos ~= pos or pos % 1 ~= 0) then
1966
+ error(`Scribe: Insert position must be an integer, got {tostring(pos)}`, 0)
1967
+ end
1968
+ end
1969
+
1970
+ local pathKey = Util.pathKey(path)
1971
+ -- Read the existing array first (create = false, so nothing is materialized). The
1972
+ -- prospective index is needed up front so validation errors name the real element
1973
+ -- path, and the pre-creation value is what a rollback must restore, rather than an
1974
+ -- empty table. The MaxItems cap is applied further down, because with Evict it writes.
1975
+ local existingContainer, existingKey = resolveContainer(tree, path, false)
1976
+ local preValue = if existingContainer then existingContainer[existingKey] else nil
1977
+ local existingLength = if type(preValue) == "table" then #(preValue :: any) else 0
1978
+ local index = math.clamp(pos or existingLength + 1, 1, existingLength + 1)
1979
+
1980
+ -- One decision read in two places, computed once so the two cannot drift. They sit
1981
+ -- on opposite sides of the other checks: the refusal (no Evict declared) belongs
1982
+ -- with the other refusals, the eviction belongs past all of them because it WRITES.
1983
+ local capped: SchemaNode? = if validating
1984
+ and schema ~= nil
1985
+ and schema.MaxItems ~= nil
1986
+ and existingLength >= schema.MaxItems
1987
+ then schema
1988
+ else nil
1989
+
1990
+ if validating then
1991
+ if capped ~= nil and capped.Evict ~= "Front" and capped.Evict ~= "Back" then
1992
+ error(
1993
+ `Scribe: "{Util.pathString(path)}" already holds {existingLength} entries, `
1994
+ .. `at its MaxItems {capped.MaxItems}`,
1995
+ 0
1996
+ )
1997
+ end
1998
+ if item == nil then
1999
+ error(`Scribe: cannot Insert nil into "{Util.pathString(path)}"`, 0)
2000
+ end
2001
+ -- Insert creates an array index, so it can mix an undeclared container just as a
2002
+ -- keyed write can, and it is the one path checkContainerKey never sees. Checked
2003
+ -- before validateWrite, seedMissingElements and ensureContainerValue, so a refusal
2004
+ -- leaves nothing materialized.
2005
+ if (schema == nil or schema.Container == nil) and type(preValue) == "table" then
2006
+ local blocker = mixedKeyBlocker(preValue, index)
2007
+ if blocker ~= nil then
2008
+ error(
2009
+ `Scribe: "{Util.pathString(path)}" already holds {blocker}, so Insert would make it a mixed `
2010
+ .. "array/hash table -- the DataStore drops half of one on save, and Set on the parent "
2011
+ .. "refuses the same shape. Use one key type for this container",
2012
+ 0
2013
+ )
2014
+ end
2015
+ end
2016
+ end
2017
+
2018
+ -- Validate the item BEFORE creating any container, so a rejected item can
2019
+ -- never leave a phantom container behind.
2020
+ local elementSchema = if schema then Template.ChildSchema(schema, index) else nil
2021
+ local elementPath = table.clone(path)
2022
+ table.insert(elementPath, index)
2023
+ -- Pass depth = #path: an inserted element sits one level below the array's own
2024
+ -- path, and the default under-budgets it by one, admitting an element the Init
2025
+ -- snapshot cannot re-encode and so dropping that client's whole root.
2026
+ local value = if opts.NoValidate
2027
+ then Util.deepClone(item)
2028
+ else validateWrite(tree, elementSchema, elementPath, item, #path)
2029
+
2030
+ -- Only now, with the insert guaranteed to land, make room at the named end. Run any
2031
+ -- earlier and a REFUSED Insert on a full array would still drop the oldest entry,
2032
+ -- fire OnRemove and replicate a Remove, with no rollback outside a transaction.
2033
+ -- Nothing above here has written, so a refusal still materializes nothing.
2034
+ if capped ~= nil then
2035
+ -- Through the real remove path on purpose: a bare table.remove would shrink
2036
+ -- the server's array without emitting a Remove op, leaving every mirror one
2037
+ -- entry longer forever. The loop handles an array already over cap (a lowered
2038
+ -- MaxItems, or data predating it) rather than trimming one entry per Insert.
2039
+ local dropFront = capped.Evict == "Front"
2040
+ for _ = 1, existingLength - (capped.MaxItems :: number) + 1 do
2041
+ -- Recompute the tail index each pass: the array shrinks under us.
2042
+ local current = if type(preValue) == "table" then #(preValue :: any) else 0
2043
+ applyArrayRemove(tree, path, schema, if dropFront then 1 else current, opts)
2044
+ end
2045
+ -- Everything shifted down, so re-read rather than trusting the stale index.
2046
+ -- Rollback stays correct: applyArrayRemove snapshotted the pre-eviction array
2047
+ -- and snapshotForTxn keeps the first value per pathKey.
2048
+ existingContainer, existingKey = resolveContainer(tree, path, false)
2049
+ preValue = if existingContainer then existingContainer[existingKey] else nil
2050
+ existingLength = if type(preValue) == "table" then #(preValue :: any) else 0
2051
+ index = math.clamp(pos or existingLength + 1, 1, existingLength + 1)
2052
+ end
2053
+
2054
+ -- Seed AFTER validation (a rejected item must not leave a phantom element),
2055
+ -- BEFORE the snapshot so intermediate declared elements replicate as real ops.
2056
+ seedMissingElements(tree, path, schema, opts)
2057
+ markDerivedDirty(tree, pathKey)
2058
+ snapshotForTxn(tree, path, pathKey, preValue)
2059
+
2060
+ local arr = ensureContainerValue(tree, path, schema)
2061
+ -- Every element from `index` up shifts, so a listener bound to an element path is
2062
+ -- now looking at a different element. Snapshot before the shift and diff after.
2063
+ local descendantOlds = snapshotDescendants(tree, pathKey)
2064
+ table.insert(arr, index, value)
2065
+
2066
+ emitOp(tree, { Kind = "Insert", Path = table.clone(path), Value = value, Index = index }, schema, opts)
2067
+ fire(tree, pathKey, "OnInsert", value, index)
2068
+ fireDescendants(tree, descendantOlds)
2069
+ if not deferSelfState(tree, pathKey, path) then
2070
+ fire(tree, pathKey, "Changed", arr, arr)
2071
+ end
2072
+ fireAncestors(tree, path)
2073
+ settleAfterWrite(tree)
2074
+ end
2075
+
2076
+ function applyArrayRemove(
2077
+ tree: Tree,
2078
+ path: { string | number },
2079
+ schema: SchemaNode?,
2080
+ pos: number?,
2081
+ opts: WriteOpts
2082
+ ): any
2083
+ if not opts.NoValidate and not opts.FromRemote then
2084
+ refuseStructuralWrite(schema, path, "Remove by index")
2085
+ end
2086
+ local container, key = resolveContainer(tree, path, false)
2087
+ local arr = if container then container[key] else nil
2088
+ if type(arr) ~= "table" or #arr == 0 then
2089
+ return nil
2090
+ end
2091
+ -- No argument means "the last element". An explicit index outside the array is a
2092
+ -- no-op, not a clamp: clamping turns an off-by-one or a stale index into a silent
2093
+ -- deletion of the wrong element.
2094
+ local index: number
2095
+ if pos == nil then
2096
+ index = #arr
2097
+ else
2098
+ if pos ~= math.floor(pos) or pos < 1 or pos > #arr then
2099
+ return nil
2100
+ end
2101
+ index = pos
2102
+ end
2103
+
2104
+ local pathKey = Util.pathKey(path)
2105
+ markDerivedDirty(tree, pathKey)
2106
+ snapshotForTxn(tree, path, pathKey, arr)
2107
+ -- The same shift as Insert, in the other direction.
2108
+ local descendantOlds = snapshotDescendants(tree, pathKey)
2109
+ local item = table.remove(arr, index)
2110
+
2111
+ emitOp(tree, { Kind = "Remove", Path = table.clone(path), Index = index }, schema, opts)
2112
+ fire(tree, pathKey, "OnRemove", item, index)
2113
+ fireDescendants(tree, descendantOlds)
2114
+ if not deferSelfState(tree, pathKey, path) then
2115
+ fire(tree, pathKey, "Changed", arr, arr)
2116
+ end
2117
+ fireAncestors(tree, path)
2118
+ settleAfterWrite(tree)
2119
+ return item
2120
+ end
2121
+
2122
+ local function applyClear(tree: Tree, path: { string | number }, schema: SchemaNode?, opts: WriteOpts)
2123
+ -- A Scribe.Flags and a Scribe.SetOf both clear legitimately to {}, so only the
2124
+ -- big is refused here.
2125
+ if not opts.NoValidate and not opts.FromRemote and schema and schema.ValueType == "big" then
2126
+ refuseStructuralWrite(schema, path, "Clear")
2127
+ end
2128
+ local container, key = resolveContainer(tree, path, opts.FromRemote == true, schema)
2129
+ local value = if container then container[key] else nil
2130
+ if type(value) ~= "table" then
2131
+ if not (opts.FromRemote and container) then
2132
+ return
2133
+ end
2134
+ -- A remote Clear implies the container existed server-side at emission, so if
2135
+ -- the op that created it was coalesced away, materialize it as {} to keep
2136
+ -- existence and Count() parity.
2137
+ value = {}
2138
+ container[key] = value
2139
+ noteKeyDelta(container, key, false, true)
2140
+ end
2141
+ local pathKey = Util.pathKey(path)
2142
+ -- Clear accepts any table node, a static record included, so this is the one
2143
+ -- non-Set path that can blank a derived input.
2144
+ markDerivedDirty(tree, pathKey)
2145
+ snapshotForTxn(tree, path, pathKey, value)
2146
+ local descendantOlds = snapshotDescendants(tree, pathKey)
2147
+ table.clear(value)
2148
+ noteContainerCleared(value)
2149
+
2150
+ emitOp(tree, { Kind = "Clear", Path = table.clone(path) }, schema, opts)
2151
+ -- Bulk semantics: the parent Changed fires once and per-entry key events do not. A
2152
+ -- descendant leaf listener is not a per-entry event: its value really did change.
2153
+ -- Descendants come BEFORE the container's own state, the only order both paths can
2154
+ -- share: inside a batch the self fire is deferred to the flush and lands last anyway,
2155
+ -- so firing it first when unbatched gave one Clear two orders.
2156
+ fireDescendants(tree, descendantOlds)
2157
+ if not deferSelfState(tree, pathKey, path) then
2158
+ fire(tree, pathKey, "Changed", value, value)
2159
+ end
2160
+ fireAncestors(tree, path)
2161
+ settleAfterWrite(tree)
2162
+ end
2163
+
2164
+ -- Recomputes every dirty derived field in the compiler's topological order, so a
2165
+ -- field reading another derived field sees the settled value in the same sweep. Each
2166
+ -- recompute writes through applySet, so an unchanged result costs nothing.
2167
+ local function runSettle(tree: Tree)
2168
+ local ordered = tree.Compiled.DerivedNodes
2169
+ local devMode = tree.Params.DevMode == true
2170
+ local onIssue = tree.Params.OnDerivedIssue
2171
+
2172
+ for _ = 1, MAX_SETTLE_PASSES do
2173
+ local dirty = tree._derivedDirty
2174
+ if dirty == nil then
2175
+ break
2176
+ end
2177
+ -- Sweeping `ordered` rather than the dirty set is what settles chains of any
2178
+ -- depth in ONE pass: a dependent sits after its inputs, so a mark laid down
2179
+ -- by the recompute above is still ahead of the cursor.
2180
+ for _, node in ordered do
2181
+ if dirty[node] then
2182
+ dirty[node] = nil
2183
+ local spec = node.Derived :: any
2184
+ local inputs = spec.Inputs
2185
+ local count = #inputs
2186
+ local values = table.create(count)
2187
+ for i, input in inputs do
2188
+ values[i] = DerivedModule.ReadForm(input, readValue(tree, input.Path :: any))
2189
+ end
2190
+ local ok, value = DerivedModule.Compute(node, values, count)
2191
+ Metrics.Add("DerivedRecomputes")
2192
+ if ok then
2193
+ if not spec.Transmit then
2194
+ -- The transmit rule, counted: a recompute that cost no bytes.
2195
+ Metrics.Add("DerivedOpsSuppressed")
2196
+ end
2197
+ applySet(tree, node.Path :: any, node, value, {
2198
+ -- Dev mode sends locally computed values too, so the client can
2199
+ -- compare and report an impure function. Production sends nothing.
2200
+ Replicate = spec.Transmit or devMode,
2201
+ })
2202
+ else
2203
+ Metrics.Add("DerivedErrors")
2204
+ -- Never rethrow: a Set on an input must not fail because a compute
2205
+ -- function has a typo. Logged once per field per tree, or the throw
2206
+ -- on every write evicts the ring holding the evidence.
2207
+ local logged = tree._derivedLogged
2208
+ if logged == nil then
2209
+ logged = {}
2210
+ tree._derivedLogged = logged
2211
+ end
2212
+ if onIssue and not (logged :: any)[node] then
2213
+ (logged :: any)[node] = true
2214
+ onIssue("DERIVED_ERROR", spec.Label, tostring(value))
2215
+ end
2216
+ end
2217
+ end
2218
+ end
2219
+ if next(dirty) == nil then
2220
+ tree._derivedDirty = nil
2221
+ break
2222
+ end
2223
+ end
2224
+
2225
+ local leftover = tree._derivedDirty
2226
+ if leftover ~= nil then
2227
+ if onIssue then
2228
+ local names = {}
2229
+ for node in leftover do
2230
+ table.insert(names, (node.Derived :: any).Label)
2231
+ end
2232
+ table.sort(names)
2233
+ onIssue(
2234
+ "DERIVED_FEEDBACK",
2235
+ table.concat(names, ", "),
2236
+ `still dirty after {MAX_SETTLE_PASSES} passes: a listener keeps writing an input from inside the `
2237
+ .. "recompute it triggered"
2238
+ )
2239
+ end
2240
+ tree._derivedDirty = nil
2241
+ end
2242
+ end
2243
+
2244
+ settleDerived = function(tree: Tree)
2245
+ if tree._derivedDirty == nil or tree._derivedSettling then
2246
+ return
2247
+ end
2248
+ -- The guard is cleared even when a recompute's write throws. Leaving it set would
2249
+ -- silently retire every derived field on this tree for the rest of the session.
2250
+ tree._derivedSettling = true
2251
+ local ok, err = pcall(runSettle, tree)
2252
+ tree._derivedSettling = false
2253
+ if not ok then
2254
+ error(err, 0)
2255
+ end
2256
+ end
2257
+
2258
+ --- Compares each derived value the server sent this frame against the one this realm
2259
+ --- computed, once the local recompute has run. A disagreement is an impure compute
2260
+ --- function, which nothing else can detect.
2261
+ local function runDerivedAudit(tree: Tree)
2262
+ local audit = tree._derivedAudit
2263
+ if audit == nil then
2264
+ return
2265
+ end
2266
+ tree._derivedAudit = nil
2267
+ local onIssue = tree.Params.OnDerivedIssue
2268
+ if onIssue == nil then
2269
+ return
2270
+ end
2271
+ for _, pending in audit do
2272
+ local mine = readValue(tree, pending.Path)
2273
+ if not Util.leafEquals(mine, pending.Server) then
2274
+ onIssue(
2275
+ "DERIVED_MISMATCH",
2276
+ pending.Label,
2277
+ `server computed {tostring(pending.Server)}, this realm computed {tostring(mine)}: the `
2278
+ .. "compute function is not pure (os.time / math.random / a realm-specific upvalue?)"
2279
+ )
2280
+ end
2281
+ end
2282
+ end
2283
+
2284
+ -- Applies a whole frame's ops as ONE batch, so N ops under the same container give one
2285
+ -- container Changed. The receiving half of Server.Batch: the server already coalesced
2286
+ -- the batch into one frame. Leaf fires are untouched.
2287
+ function Tree.ApplyOps(self: Tree, ops: { Op })
2288
+ if self.Dead then
2289
+ return
2290
+ end
2291
+ self._batchDepth += 1
2292
+ local ok, err = pcall(function()
2293
+ for _, op in ops do
2294
+ self:ApplyOp(op)
2295
+ end
2296
+ end)
2297
+ self._batchDepth -= 1
2298
+ if self._batchDepth == 0 then
2299
+ -- One recompute per FRAME, not per op: the server already coalesced these
2300
+ -- ops into a single flush.
2301
+ settleDerived(self)
2302
+ runDerivedAudit(self)
2303
+ -- Flush even when an op threw: the ops before it landed, and a listener
2304
+ -- that never hears about them is worse than one that hears late.
2305
+ flushPendingAncestors(self)
2306
+ end
2307
+ if not ok then
2308
+ error(err, 0)
2309
+ end
2310
+ end
2311
+
2312
+ --[=[
2313
+ Recomputes every derived field from current state, whatever the dirty set says.
2314
+
2315
+ Used once per profile load, where the tree has just been pointed at real data
2316
+ that no write ever passed through: the session store still holds the compile-time
2317
+ defaults, which were computed from the template's defaults rather than from this
2318
+ player's values.
2319
+ ]=]
2320
+ function Tree.SeedDerived(self: Tree)
2321
+ local ordered = self.Compiled.DerivedNodes
2322
+ if #ordered == 0 then
2323
+ return
2324
+ end
2325
+ local dirty = self._derivedDirty
2326
+ if dirty == nil then
2327
+ dirty = {}
2328
+ self._derivedDirty = dirty
2329
+ end
2330
+ for _, node in ordered do
2331
+ (dirty :: any)[node] = true
2332
+ end
2333
+ settleDerived(self)
2334
+ end
2335
+
2336
+ -- Applies an op received over the wire (client mirror / gift delivery replays).
2337
+ function Tree.ApplyOp(self: Tree, op: Op)
2338
+ if self.Dead then
2339
+ return
2340
+ end
2341
+ -- Resolve the exact schema node (dynamic tail resolves to any-nodes).
2342
+ local baseSchema, dynStart = Template.Resolve(self.Compiled, op.Path)
2343
+ local exactSchema: SchemaNode? = baseSchema
2344
+ for i = dynStart, #op.Path do
2345
+ exactSchema = if exactSchema then Template.ChildSchema(exactSchema, op.Path[i]) else nil
2346
+ end
2347
+
2348
+ -- Purity audit. A locally computed derived field is not sent in production, so
2349
+ -- receiving one means the server is in dev mode and wants the two compared.
2350
+ --
2351
+ -- The comparison cannot happen HERE: this realm recomputes at the end of the frame,
2352
+ -- not per op, so reading the path now returns the pre-frame value, which differs on
2353
+ -- every derived op (one is emitted only when the value changed). Record the server's
2354
+ -- value and let runDerivedAudit compare once both realms have seen the same inputs.
2355
+ if exactSchema ~= nil and exactSchema.Derived ~= nil and not exactSchema.Derived.Transmit then
2356
+ if self.Params.OnDerivedIssue then
2357
+ local audit = self._derivedAudit
2358
+ if audit == nil then
2359
+ audit = {}
2360
+ self._derivedAudit = audit
2361
+ end
2362
+ (audit :: any)[#audit + 1] = {
2363
+ Path = table.clone(op.Path),
2364
+ Label = exactSchema.Derived.Label,
2365
+ Server = op.Value,
2366
+ }
2367
+ end
2368
+ end
2369
+ local opts: WriteOpts = { FromRemote = true, NoValidate = true }
2370
+ if op.Kind == "Set" or op.Kind == "Init" then
2371
+ applySet(self, op.Path, exactSchema, op.Value, opts)
2372
+ elseif op.Kind == "Insert" then
2373
+ applyInsert(self, op.Path, exactSchema, op.Value, op.Index, opts)
2374
+ elseif op.Kind == "Remove" then
2375
+ applyArrayRemove(self, op.Path, exactSchema, op.Index, opts)
2376
+ elseif op.Kind == "Clear" then
2377
+ applyClear(self, op.Path, exactSchema, opts)
2378
+ end
2379
+ -- Outside a frame the apply above settled derived itself, so the audit can run
2380
+ -- now. Inside one, ApplyOps runs it after the frame's single recompute.
2381
+ if self._batchDepth == 0 then
2382
+ runDerivedAudit(self)
2383
+ end
2384
+ end
2385
+
2386
+ -- Runs `apply` with per-op fires suppressed, then fires Changed once per observed
2387
+ -- path the mutation actually changed. A whole-container Set never fires descendants,
2388
+ -- so a nested Observe registered before the mutation would miss its value. Used by
2389
+ -- ReplayInit and edit-mode Mock. Cost is O(listeners), not O(data).
2390
+ function Tree.ReplayFire(self: Tree, apply: () -> ())
2391
+ if self.Dead then
2392
+ apply()
2393
+ return
2394
+ end
2395
+ -- Snapshot the pre-apply value of every observed path.
2396
+ local olds: { [string]: any } = {}
2397
+ for pathKey, path in self._paths do
2398
+ local byEvent = self._listeners[pathKey]
2399
+ if byEvent and byEvent.Changed then
2400
+ olds[pathKey] = readValue(self, path)
2401
+ end
2402
+ end
2403
+ self._replaying = true
2404
+ local ok, err = pcall(apply)
2405
+ -- Derived fields settle INSIDE the replay, with fires still suppressed, so their
2406
+ -- new values reach the single diff pass below instead of arriving as a second
2407
+ -- round of events. Only on success: a half-applied snapshot is not worth deriving.
2408
+ if ok then
2409
+ pcall(settleDerived, self)
2410
+ pcall(runDerivedAudit, self)
2411
+ end
2412
+ self._replaying = false -- always cleared, even if `apply` threw
2413
+ if not ok then
2414
+ error(err, 0)
2415
+ end
2416
+ -- Collect first (a fired listener may add or remove listeners), then fire.
2417
+ -- leafEquals is false for tables and buffers, so container observers always fire,
2418
+ -- matching a live whole-container Set; scalar leaves fire only on a real change.
2419
+ local pending: { { Key: string, New: any, Old: any } } = {}
2420
+ for pathKey, path in self._paths do
2421
+ local byEvent = self._listeners[pathKey]
2422
+ if byEvent and byEvent.Changed then
2423
+ local current = readValue(self, path)
2424
+ if not Util.leafEquals(current, olds[pathKey]) then
2425
+ table.insert(pending, { Key = pathKey, New = current, Old = olds[pathKey] })
2426
+ end
2427
+ end
2428
+ end
2429
+ for _, entry in pending do
2430
+ fire(self, entry.Key, "Changed", entry.New, entry.Old)
2431
+ end
2432
+ end
2433
+
2434
+ -- Applies the initial snapshot, firing nested observers registered before Init. The
2435
+ -- caller has already reset the mirror to defaults.
2436
+ function Tree.ReplayInit(self: Tree, ops: { Op })
2437
+ self:ReplayFire(function()
2438
+ for _, op in ops do
2439
+ self:ApplyOp(op)
2440
+ end
2441
+ end)
2442
+ end
2443
+
2444
+ -- Batch / Transaction ------------------------------------------------
2445
+
2446
+ function Tree.RunBatch(self: Tree, fn: () -> ())
2447
+ assertAlive(self)
2448
+ self._batchDepth += 1
2449
+ local ok, err = pcall(fn :: any)
2450
+ self._batchDepth -= 1
2451
+ if self._batchDepth == 0 then
2452
+ -- Before the flush and before OnBatchEnd: one recompute for the whole batch,
2453
+ -- whose ops join the same replication frame as the writes that caused it.
2454
+ settleDerived(self)
2455
+ -- Listeners before replication, matching the unbatched ordering.
2456
+ flushPendingAncestors(self)
2457
+ local onBatchEnd: (() -> ())? = self.Params.OnBatchEnd
2458
+ if onBatchEnd then
2459
+ onBatchEnd()
2460
+ end
2461
+ end
2462
+ if not ok then
2463
+ error(err, 0)
2464
+ end
2465
+ end
2466
+
2467
+ -- Register a pre-transaction value for a RAW store mutation, i.e. a write that does
2468
+ -- not go through applySet (the _Scribe.Timed store, whose keys are full pathKeys
2469
+ -- containing \31 that the accessor tree rejects). The first write to a key records
2470
+ -- its pre-txn value for rollback; commits keep the write. No-op outside a transaction.
2471
+ function Tree.RecordRawWrite(self: Tree, store: { [string]: any }, key: string)
2472
+ local txn = self._txn
2473
+ if not txn or txn.RawRestores[key] ~= nil then
2474
+ return
2475
+ end
2476
+ txn.RawRestores[key] = { Store = store, Value = store[key] }
2477
+ end
2478
+
2479
+ -- The rollback half of RunTransaction. Its own function so the caller can pcall it
2480
+ -- and still drain the queued fires when a restore or a recompute throws: a tree left
2481
+ -- with `_fireQueue` set would go permanently silent.
2482
+ local function rollbackTransaction(self: Tree, txn: any)
2483
+ -- Roll back every touched field to its pre-transaction value; listeners are told
2484
+ -- afterwards, in one drain.
2485
+ --
2486
+ -- Restores EMIT replication ops. A listener woken by the drain can write a field this
2487
+ -- txn also touched, and that write replicates, so only an emitted restore keeps the
2488
+ -- client's baseline equal to the server's. ORDERED, because those listener writes are
2489
+ -- neither snapshotted nor rolled back. Sorting does not stop the write; it makes the
2490
+ -- outcome the same every run, which Universe.Digest depends on outright.
2491
+ local ordered: { { Path: { string | number }, Value: any } } = {}
2492
+ local orderKeys: { [any]: string } = {}
2493
+ for pathKey, snapshot in txn.Snapshots :: { [string]: { Path: { string | number }, Value: any } } do
2494
+ ordered[#ordered + 1] = snapshot
2495
+ orderKeys[snapshot] = pathKey
2496
+ end
2497
+ -- Shallowest first, then by path key: if a snapshot pair is ever not disjoint, the
2498
+ -- ancestor must land before the descendant it contains, not be overwritten by it.
2499
+ table.sort(
2500
+ ordered,
2501
+ function(a: { Path: { string | number }, Value: any }, b: { Path: { string | number }, Value: any })
2502
+ if #a.Path ~= #b.Path then
2503
+ return #a.Path < #b.Path
2504
+ end
2505
+ return orderKeys[a] < orderKeys[b]
2506
+ end
2507
+ )
2508
+ for _, snapshot in ordered do
2509
+ local baseSchema, dynStart = Template.Resolve(self.Compiled, snapshot.Path)
2510
+ local exactSchema: SchemaNode? = baseSchema
2511
+ for i = dynStart, #snapshot.Path do
2512
+ exactSchema = if exactSchema then Template.ChildSchema(exactSchema, snapshot.Path[i]) else nil
2513
+ end
2514
+ applySet(self, snapshot.Path, exactSchema, snapshot.Value, {
2515
+ NoValidate = true,
2516
+ })
2517
+ end
2518
+ -- Restore raw store writes that bypassed applySet; a nil pre-txn value restores
2519
+ -- by removing the key.
2520
+ for key, restore in txn.RawRestores :: { [string]: { Store: { [string]: any }, Value: any } } do
2521
+ restore.Store[key] = restore.Value
2522
+ end
2523
+ -- Prune containers materialized during the transaction, deepest first, so no
2524
+ -- phantom empty tables survive. A created path covered by a snapshot is
2525
+ -- authoritative pre-txn state the restore just recreated: never prune those.
2526
+ local created = txn.Created :: { { string | number } }
2527
+ local snapshots = txn.Snapshots :: { [string]: { Path: { string | number }, Value: any } }
2528
+ local function coveredBySnapshot(createdPath: { string | number }): boolean
2529
+ for _, snap in snapshots do
2530
+ if #snap.Path == #createdPath then
2531
+ local same = true
2532
+ for i = 1, #snap.Path do
2533
+ if snap.Path[i] ~= createdPath[i] then
2534
+ same = false
2535
+ break
2536
+ end
2537
+ end
2538
+ if same then
2539
+ return true
2540
+ end
2541
+ elseif pathIsStrictAncestor(snap.Path, createdPath) then
2542
+ return true
2543
+ end
2544
+ end
2545
+ return false
2546
+ end
2547
+ for i = #created, 1, -1 do
2548
+ if not coveredBySnapshot(created[i]) then
2549
+ local container, key = resolveContainer(self, created[i], false)
2550
+ -- No emptiness requirement: a path in Created did not exist before the
2551
+ -- transaction. Necessary too, since a declared element materializes from its
2552
+ -- defaults and so is never empty.
2553
+ if container ~= nil and type(container[key]) == "table" then
2554
+ -- Prune through applySet so the removal EMITS: a restore op beneath this
2555
+ -- created container has just materialized it on the client, and a silent
2556
+ -- raw removal would strand that phantom {} forever.
2557
+ local baseSchema, dynStart = Template.Resolve(self.Compiled, created[i])
2558
+ local exactSchema: SchemaNode? = baseSchema
2559
+ for j = dynStart, #created[i] do
2560
+ exactSchema = if exactSchema then Template.ChildSchema(exactSchema, created[i][j]) else nil
2561
+ end
2562
+ applySet(self, created[i], exactSchema, nil, { NoValidate = true })
2563
+ end
2564
+ end
2565
+ end
2566
+ -- The restores above settle as they go, since the transaction is closed by now.
2567
+ -- This is the backstop for a body that dirtied a field where every restore was a
2568
+ -- no-op, leaving marks unclaimed until the next unrelated write.
2569
+ settleDerived(self)
2570
+ end
2571
+
2572
+ -- `onSeeded`, when given, is called on the COMMIT path with the path of every
2573
+ -- declared container element this transaction materialized IMPLICITLY: a write
2574
+ -- descended through a key that named no element. A deliberate whole-element Set is
2575
+ -- not one of these. The receipt path uses it; see GRANT_SEEDED_ELEMENT.
2576
+ function Tree.RunTransaction(
2577
+ self: Tree,
2578
+ fn: () -> (),
2579
+ onSeeded: ((seeded: { { string | number } }) -> ())?
2580
+ ): (boolean, string?)
2581
+ assertAlive(self)
2582
+ if self._txn then
2583
+ error("Scribe: transactions do not nest", 2)
2584
+ end
2585
+ -- Nor does a transaction on a DIFFERENT player nest inside this one, which is the
2586
+ -- shape a trade is written in. The guard above only sees one player's tree, and
2587
+ -- neither half of such a pair is atomic with the other: an outer throw after the
2588
+ -- inner commit mints value, an inner rollback under a committing outer destroys it.
2589
+ if OPEN_TXN_TREE ~= nil then
2590
+ error(
2591
+ `Scribe: a transaction is already open on another player, and transactions do not span players: `
2592
+ .. CROSS_TREE_TXN_WHY,
2593
+ 2
2594
+ )
2595
+ end
2596
+ self._txn = { Snapshots = {}, Below = {}, Ops = {}, Created = {}, Seeded = {}, RawRestores = {}, Economy = {} }
2597
+ OPEN_TXN_TREE = self
2598
+ -- Everything already queued belongs to an enclosing batch, not to this
2599
+ -- transaction, so a rollback must leave it alone.
2600
+ local outerOrder = self._pendingAncestorOrder
2601
+ local pendingMark = if outerOrder then #outerOrder else 0
2602
+ -- RESTORED, not decremented, at the end. A Data.Batch opened inside `fn` raises the
2603
+ -- depth on `fn`'s coroutine, and closing that coroutine on the yield path does not
2604
+ -- unwind pending frames in Luau, so RunBatch's decrement dies with the stack.
2605
+ -- Decrementing only our own would strand the tree above zero, where
2606
+ -- flushPendingAncestors never runs and every container listener goes silent.
2607
+ local depthBefore = self._batchDepth
2608
+ self._batchDepth += 1
2609
+ -- Run fn in its OWN coroutine so a yield can be detected. Every write path absorbs
2610
+ -- into `self._txn` while it is set, so a concurrent write landing during a yield
2611
+ -- would be pulled into this transaction and rolled back with it, reverting a receipt
2612
+ -- grant and losing paid currency. Refuse the yield and roll back fn's writes so far.
2613
+ -- The inner xpcall preserves the original traceback for the non-yield case.
2614
+ local co = coroutine.create(function()
2615
+ return xpcall(fn :: any, function(e)
2616
+ return debug.traceback(tostring(e), 2)
2617
+ end)
2618
+ end)
2619
+ local resumed, innerOk, innerErr = coroutine.resume(co)
2620
+ local ok, err
2621
+ if coroutine.status(co) ~= "dead" then
2622
+ coroutine.close(co) -- cancel it so the scheduler never resumes it after rollback
2623
+ ok, err = false, YIELD_ERROR
2624
+ elseif not resumed then
2625
+ ok, err = false, tostring(innerOk) -- coroutine itself errored (should not happen)
2626
+ else
2627
+ ok, err = innerOk, innerErr
2628
+ end
2629
+ -- Settle while the transaction is still open, so a recompute is journaled with the
2630
+ -- writes that caused it and commits or rolls back atomically with them.
2631
+ if ok then
2632
+ local settleOk, settleErr = pcall(settleDerived, self)
2633
+ if not settleOk then
2634
+ ok, err = false, tostring(settleErr)
2635
+ end
2636
+ end
2637
+
2638
+ local txn = self._txn :: any
2639
+ self._txn = nil
2640
+ -- Cleared in lockstep with `_txn`, so the restores, the queued drain and the
2641
+ -- OnOp / OnEconomy / onSeeded callbacks all run outside the transaction.
2642
+ OPEN_TXN_TREE = nil
2643
+ self._batchDepth = depthBefore
2644
+ if not ok then
2645
+ discardPendingAncestors(self, pendingMark)
2646
+ end
2647
+
2648
+ if ok then
2649
+ local onOp: ((op: Op, schema: SchemaNode?) -> ())? = self.Params.OnOp
2650
+ if onOp then
2651
+ for _, entry in txn.Ops :: { { Op: Op, Schema: SchemaNode? } } do
2652
+ onOp(entry.Op, entry.Schema)
2653
+ end
2654
+ end
2655
+ local onEconomy: ((path: { string | number }, delta: number, newValue: number, tags: { [string]: any }) -> ())? =
2656
+ self.Params.OnEconomy
2657
+ if onEconomy then
2658
+ for _, event in txn.Economy :: { { Path: { string | number }, Delta: number, New: number, Tags: any } } do
2659
+ onEconomy(event.Path, event.Delta, event.New, event.Tags)
2660
+ end
2661
+ end
2662
+ -- After the ops, so anything reported here describes journaled writes, and only on
2663
+ -- the committed path. pcall, unlike the two callbacks above, because this one is a
2664
+ -- DIAGNOSTIC and the transaction has already committed: a throw would skip
2665
+ -- flushPendingAncestors and surface as a failed grant, which Roblox retries into a
2666
+ -- double grant. OnOp and OnEconomy are load-bearing and stay unguarded.
2667
+ if onSeeded and #txn.Seeded > 0 then
2668
+ local reported = pcall(onSeeded, txn.Seeded :: { { string | number } })
2669
+ if not reported then
2670
+ warn("[Scribe] seeded-element reporter errored")
2671
+ end
2672
+ end
2673
+ if self._batchDepth == 0 then
2674
+ flushPendingAncestors(self)
2675
+ local onBatchEnd: (() -> ())? = self.Params.OnBatchEnd
2676
+ if onBatchEnd then
2677
+ onBatchEnd()
2678
+ end
2679
+ end
2680
+ return true, nil
2681
+ end
2682
+
2683
+ -- Restores run with listener dispatch QUEUED rather than immediate (see `fire`), so
2684
+ -- the tree is whole before any listener sees it. A listener write made during the
2685
+ -- drain is an ordinary post-rollback write: it lands, emits, and is not rolled back.
2686
+ -- Rolling it back too would need an unbounded fixpoint, since undoing it re-fires
2687
+ -- the listener that wrote it.
2688
+ local queue: { { any } } = {}
2689
+ self._fireQueue = queue
2690
+ local rolledBack, rollbackErr = pcall(rollbackTransaction, self, txn)
2691
+ self._fireQueue = nil
2692
+ for _, entry in queue do
2693
+ local args = entry[3]
2694
+ fire(self, entry[1], entry[2], table.unpack(args, 1, args.n))
2695
+ end
2696
+ if not rolledBack then
2697
+ error(rollbackErr, 0)
2698
+ end
2699
+ return false, tostring(err)
2700
+ end
2701
+
2702
+ function Tree.Destroy(self: Tree)
2703
+ self.Dead = true
2704
+ table.clear(self._listeners)
2705
+ -- _paths holds one entry per listened path, so leaving it behind would keep every
2706
+ -- path array alive on a tree destroyed with listeners still connected. Accessors
2707
+ -- need no equivalent sweep: the per-parent _children caches are weak-valued.
2708
+ table.clear(self._paths)
2709
+ table.clear(self._descendants)
2710
+ end
2711
+
2712
+ -- Accessor methods -----------------------------------------------------------------
2713
+
2714
+ type Accessor = any
2715
+
2716
+ local function accessorSchema(accessor: Accessor): SchemaNode?
2717
+ return rawget(accessor, F_SCHEMA) :: any
2718
+ end
2719
+
2720
+ local function accessorTree(accessor: Accessor): Tree
2721
+ return rawget(accessor, F_TREE) :: any
2722
+ end
2723
+
2724
+ local function accessorPath(accessor: Accessor): { string | number }
2725
+ return rawget(accessor, F_PATH) :: any
2726
+ end
2727
+
2728
+ local function accessorKey(accessor: Accessor): string
2729
+ return rawget(accessor, F_KEY) :: any
2730
+ end
2731
+
2732
+ local function parseIncrementArgs(tagsOrReplicate: any): ({ [string]: any }?, boolean?)
2733
+ if type(tagsOrReplicate) == "boolean" then
2734
+ return nil, tagsOrReplicate
2735
+ elseif type(tagsOrReplicate) == "table" then
2736
+ return tagsOrReplicate, nil
2737
+ end
2738
+ return nil, nil
2739
+ end
2740
+
2741
+ -- Declared datatype fields store a packed buffer; the accessor converts at
2742
+ -- the boundary so callers only ever see the real datatype.
2743
+ local function unpackIfDatatype(schema: SchemaNode?, value: any): any
2744
+ if schema and schema.ValueType == "datatype" and type(value) == "buffer" then
2745
+ return Datatypes.Unpack(schema.Datatype :: string, value)
2746
+ end
2747
+ return value
2748
+ end
2749
+
2750
+ -- Read-boundary unpack that also handles containers: one with packed descendants
2751
+ -- comes back as a fresh table with every buffer and mantissa pair converted, so a
2752
+ -- container read never leaks a stored shape. Unpacked subtrees are shared by
2753
+ -- reference, and a container with nothing packed below returns unchanged.
2754
+ local function unpackRead(schema: SchemaNode?, value: any): any
2755
+ -- A big is stored as { mantissa, exponent } and read as the object with
2756
+ -- arithmetic on it, the same split datatype fields use.
2757
+ if schema and schema.ValueType == "big" then
2758
+ return if value == nil then nil else Big.from(value)
2759
+ end
2760
+ if type(value) == "table" then
2761
+ if schema ~= nil and Template.IsPacked(schema) then
2762
+ local out: { [any]: any } = {}
2763
+ for k, v in value do
2764
+ out[k] = unpackRead(Template.ChildSchema(schema, k), v)
2765
+ end
2766
+ return out
2767
+ end
2768
+ return value
2769
+ end
2770
+ return unpackIfDatatype(schema, value)
2771
+ end
2772
+
2773
+ -- Schema of a container's entries: the compiled element for a Scribe.ArrayOf /
2774
+ -- Scribe.DictOf, otherwise the generic dynamic pseudo-node (or nil for a leaf).
2775
+ local function elementSchemaOf(schema: SchemaNode?): SchemaNode?
2776
+ return if schema then Template.ChildSchema(schema, 1) else nil
2777
+ end
2778
+
2779
+ -- Whether `schema` sits anywhere inside an ArrayOf/DictOf element subtree. Fields
2780
+ -- there may legitimately not exist yet, unlike static fields, which Reconcile
2781
+ -- guarantees present.
2782
+ local function inElementSubtree(schema: SchemaNode?): boolean
2783
+ local cursor = schema
2784
+ while cursor do
2785
+ if cursor.IsElement then
2786
+ return true
2787
+ end
2788
+ cursor = cursor.Parent
2789
+ end
2790
+ return false
2791
+ end
2792
+
2793
+ -- Canonical packed form of a datatype, for comparison only. Packing is not
2794
+ -- byte-canonical for every codec, so a value Get() handed out would not re-pack to the
2795
+ -- bytes it came from; routing both sides through the same unpack+repack lands them on
2796
+ -- one representative, which makes `Has(Get()[i])` work. `precision` must be the same on
2797
+ -- both sides, hence threaded rather than defaulted.
2798
+ local function canonicalDatatype(name: string, value: any, precision: (string | number)?): buffer?
2799
+ local packed: buffer
2800
+ if type(value) == "buffer" then
2801
+ packed = value
2802
+ elseif typeof(value) == name then
2803
+ local ok, result = pcall(Datatypes.Pack, name, value, precision)
2804
+ if not ok then
2805
+ return nil
2806
+ end
2807
+ packed = result
2808
+ else
2809
+ return nil
2810
+ end
2811
+ local unpackOk, unpacked = pcall(Datatypes.Unpack, name, packed)
2812
+ if not unpackOk then
2813
+ return packed
2814
+ end
2815
+ local repackOk, repacked = pcall(Datatypes.Pack, name, unpacked, precision)
2816
+ return if repackOk then repacked else packed
2817
+ end
2818
+
2819
+ -- Structural equality between a STORED entry and a caller-supplied needle, resolved
2820
+ -- through the element schema so packed datatype and big leaves compare by value.
2821
+ local function entryEquals(schema: SchemaNode?, stored: any, needle: any): boolean
2822
+ if schema and schema.ValueType == "big" then
2823
+ -- The stored side is a { mantissa, exponent } pair and the needle is whatever a
2824
+ -- read handed back, so both go through Big.from; otherwise the pair-vs-object
2825
+ -- walk never matches and Has/Find/RemoveValue silently no-op.
2826
+ local a, b = Big.from(stored), Big.from(needle)
2827
+ return a ~= nil and b ~= nil and Big.compare(a, b) == 0
2828
+ end
2829
+ if schema and schema.ValueType == "datatype" then
2830
+ local name = schema.Datatype :: string
2831
+ local a = canonicalDatatype(name, stored, schema.Precision)
2832
+ local b = canonicalDatatype(name, needle, schema.Precision)
2833
+ return a ~= nil and b ~= nil and Util.bufferEquals(a, b)
2834
+ end
2835
+ if type(stored) == "buffer" or type(needle) == "buffer" then
2836
+ return type(stored) == "buffer" and type(needle) == "buffer" and Util.bufferEquals(stored, needle)
2837
+ end
2838
+ if type(stored) ~= "table" or type(needle) ~= "table" then
2839
+ return stored == needle
2840
+ end
2841
+ local seen = 0
2842
+ for k, v in stored do
2843
+ if not entryEquals(if schema then Template.ChildSchema(schema, k) else nil, v, (needle :: any)[k]) then
2844
+ return false
2845
+ end
2846
+ seen += 1
2847
+ end
2848
+ for _ in needle do
2849
+ seen -= 1
2850
+ end
2851
+ return seen == 0
2852
+ end
2853
+
2854
+ -- Element-aware `table.find`. A declared element is compared structurally, because
2855
+ -- entries reach callers unpacked and copied, so identity never holds. Untyped
2856
+ -- containers keep identity semantics, which existing code relies on.
2857
+ local function findElement(schema: SchemaNode?, arr: { any }, item: any): number?
2858
+ if schema and schema.Container == "Dict" then
2859
+ error(
2860
+ "Scribe: Find/Has/RemoveValue search array entries; a Scribe.DictOf is keyed, "
2861
+ .. "so read the key directly (or Remove(key))",
2862
+ 0
2863
+ )
2864
+ end
2865
+ local element = elementSchemaOf(schema)
2866
+ if element == nil or not (element.IsElement or element.ValueType == "datatype") then
2867
+ return table.find(arr, item)
2868
+ end
2869
+ for i, v in arr do
2870
+ if entryEquals(element, v, item) then
2871
+ return i
2872
+ end
2873
+ end
2874
+ return nil
2875
+ end
2876
+
2877
+ -- Clone counterpart: a full deep copy with packed descendants unpacked, so Clone()
2878
+ -- of a datatype- or big-bearing container yields an independent value in its read
2879
+ -- shape rather than the stored one.
2880
+ local function cloneUnpack(schema: SchemaNode?, value: any): any
2881
+ if schema and schema.ValueType == "big" then
2882
+ -- A Big object is immutable and built fresh here, so it needs no extra copy.
2883
+ return if value == nil then nil else Big.from(value)
2884
+ end
2885
+ if type(value) ~= "table" then
2886
+ local unpacked = unpackIfDatatype(schema, value)
2887
+ -- A raw buffer leaf must be copied, not aliased: buffers are mutable and Clone
2888
+ -- promises an independent value. A datatype leaf already became an immutable
2889
+ -- Roblox datatype above.
2890
+ if type(unpacked) == "buffer" then
2891
+ return Util.cloneBuffer(unpacked)
2892
+ end
2893
+ return unpacked
2894
+ end
2895
+ local out: { [any]: any } = {}
2896
+ for k, v in value do
2897
+ out[k] = cloneUnpack(if schema then Template.ChildSchema(schema, k) else nil, v)
2898
+ end
2899
+ return out
2900
+ end
2901
+
2902
+ -- Is this accessor GAME CODE's handle on Scribe's own ledger? Shared by both
2903
+ -- reserved-root guards: the write refusal in accessorIndex and the copy-on-read below.
2904
+ -- Neither term can change for a given accessor, so callers evaluate this once when a
2905
+ -- method is built.
2906
+ local function isPublicReserved(accessor: Accessor): boolean
2907
+ return accessorPath(accessor)[1] == Template.RESERVED_ROOT and not PRIVILEGED[accessor]
2908
+ end
2909
+
2910
+ -- The independent copy Clone() hands back: unpack-and-deep-clone when anything below
2911
+ -- is packed, an ordinary deep clone otherwise. Shared with the reserved-root read
2912
+ -- guard, which needs the identical value.
2913
+ local function detachedCopy(schema: SchemaNode?, value: any): any
2914
+ if Template.IsPacked(schema) then
2915
+ return cloneUnpack(schema, value)
2916
+ end
2917
+ return Util.deepClone(value)
2918
+ end
2919
+
2920
+ -- The read boundary. An ordinary read unpacks and hands back the live stored table by
2921
+ -- reference, which is deliberate; a read of the reserved root BY GAME CODE hands back a
2922
+ -- detached deep copy, or the write guard in accessorIndex is decorative and clearing the
2923
+ -- ledger through a reader lets the next retried receipt grant twice. Deep, because the
2924
+ -- ledger nests. Not table.freeze, which is permanent in Luau and would break the
2925
+ -- library's own writes through Tree.Reserved.
2926
+ local function readOut(guarded: boolean, schema: SchemaNode?, value: any): any
2927
+ if guarded and type(value) == "table" then
2928
+ return detachedCopy(schema, value)
2929
+ end
2930
+ return unpackRead(schema, value)
2931
+ end
2932
+
2933
+ -- The whole-data value the ROOT accessor reads. Reading the store directly is wrong in
2934
+ -- both directions: it carries Scribe's library-owned roots, which the declared type
2935
+ -- never had, and it is only one of the two stores, so Session roots go missing. Building
2936
+ -- from the DECLARED roots gives exactly the keys the template promises. Scribe's
2937
+ -- internals stay reachable by indexing the accessor (`data._Scribe.Perks`).
2938
+ local function rootShell(tree: Tree, clone: boolean): { [string]: any }
2939
+ local out: { [string]: any } = {}
2940
+ local children = tree.Compiled.Root.Children
2941
+ if children == nil then
2942
+ return out
2943
+ end
2944
+ for key, childSchema in children do
2945
+ if key == Template.RESERVED_ROOT or key == Template.SESSION_ROOT then
2946
+ continue
2947
+ end
2948
+ local value = storeFor(tree, key)[key]
2949
+ if value == nil then
2950
+ continue
2951
+ end
2952
+ if not clone then
2953
+ out[key] = unpackRead(childSchema, value)
2954
+ elseif Template.IsPacked(childSchema) then
2955
+ out[key] = cloneUnpack(childSchema, value)
2956
+ else
2957
+ out[key] = Util.deepClone(value)
2958
+ end
2959
+ end
2960
+ return out
2961
+ end
2962
+
2963
+ -- Every root read hands back the same frozen shell, so Get, Observe and Changed
2964
+ -- cannot disagree about what "all of the data" means.
2965
+ local function frozenRootShell(tree: Tree): { [string]: any }
2966
+ return table.freeze(rootShell(tree, false))
2967
+ end
2968
+
2969
+ -- A root Observe/Changed re-reads every root on every write, and a root holding a
2970
+ -- datatype or a Scribe.Big must be rebuilt key by key to be read at all, so over a few
2971
+ -- thousand packed elements one unrelated write costs milliseconds. The library cannot
2972
+ -- make that cheap safely: skipping the rebuild means sharing one view, and that view
2973
+ -- aliases live store tables. The fix belongs in the game, which should listen to the
2974
+ -- container it cares about. Said once, in DevMode.
2975
+ local ROOT_OBSERVE_WARN_NODES = 512
2976
+ local warnedRootObserve: { [any]: boolean } = setmetatable({}, { __mode = "k" }) :: any
2977
+
2978
+ local function countNodes(value: any, budget: number): number
2979
+ if type(value) ~= "table" or budget <= 0 then
2980
+ return 1
2981
+ end
2982
+ local n = 1
2983
+ for _, child in value do
2984
+ n += countNodes(child, budget - n)
2985
+ if n >= budget then
2986
+ break
2987
+ end
2988
+ end
2989
+ return n
2990
+ end
2991
+
2992
+ local function warnIfRootObserveIsExpensive(tree: Tree, what: string)
2993
+ if not tree.Params.DevMode or warnedRootObserve[tree] then
2994
+ return
2995
+ end
2996
+ local warnFn = tree.Params.LogWarn
2997
+ if warnFn == nil then
2998
+ return
2999
+ end
3000
+ local children = tree.Compiled.Root.Children
3001
+ if children == nil then
3002
+ return
3003
+ end
3004
+ for key, childSchema in children do
3005
+ if key ~= Template.RESERVED_ROOT and key ~= Template.SESSION_ROOT and Template.IsPacked(childSchema) then
3006
+ local nodes = countNodes(storeFor(tree, key)[key], ROOT_OBSERVE_WARN_NODES)
3007
+ if nodes >= ROOT_OBSERVE_WARN_NODES then
3008
+ warnedRootObserve[tree] = true
3009
+ warnFn(
3010
+ `a root {what} re-reads every root on every write, and "{key}" holds a datatype or `
3011
+ .. `Scribe.Big across {nodes}+ values, which must be unpacked each time. Listen to the `
3012
+ .. `container you care about instead (data.{key}.{what}) -- a container only fires for `
3013
+ .. "writes at or under it, so unrelated writes cost nothing. DevMode-only warning."
3014
+ )
3015
+ return
3016
+ end
3017
+ end
3018
+ end
3019
+ end
3020
+ -- Whether this node holds children, and so receives coalesced ancestor fires rather
3021
+ -- than leaf transitions. The root always does; a dynamic node is judged by what is
3022
+ -- stored there now, the best answer available at connect time.
3023
+ local function isContainerNode(tree: Tree, schema: SchemaNode?, path: { string | number }): boolean
3024
+ if #path == 0 then
3025
+ return true
3026
+ end
3027
+ -- Kind == "any" is the pseudo-node Template synthesizes for an undeclared key
3028
+ -- under an untyped `{}` subtree. It is never nil, so testing `schema ~= nil`
3029
+ -- alone would classify every such node as a leaf and skip the check below.
3030
+ if schema ~= nil and schema.Kind ~= "any" then
3031
+ return schema.Kind == "table" or schema.Children ~= nil
3032
+ end
3033
+ return type(readValue(tree, path)) == "table"
3034
+ end
3035
+
3036
+ local METHOD_FACTORIES: { [string]: (Accessor) -> any } = {}
3037
+
3038
+ -- Reads settle first, so a derived field never hands back a value its inputs have
3039
+ -- moved past, inside a batch or mid-transaction alike. One nil compare when nothing
3040
+ -- is dirty, which is the common case.
3041
+ local function settleForRead(tree: Tree)
3042
+ if tree._derivedDirty ~= nil then
3043
+ settleDerived(tree)
3044
+ end
3045
+ end
3046
+
3047
+ METHOD_FACTORIES.Get = function(accessor)
3048
+ local guarded = isPublicReserved(accessor)
3049
+ return function()
3050
+ local tree = accessorTree(accessor)
3051
+ assertAlive(tree)
3052
+ settleForRead(tree)
3053
+ local path = accessorPath(accessor)
3054
+ if #path == 0 then
3055
+ -- Frozen so `Get().Coins = 1` raises at the offending line. Unfrozen, it
3056
+ -- either edits authoritative state unvalidated or is silently discarded,
3057
+ -- depending only on whether the template declares a datatype anywhere.
3058
+ return frozenRootShell(tree)
3059
+ end
3060
+ return readOut(guarded, accessorSchema(accessor), readValue(tree, path))
3061
+ end
3062
+ end
3063
+
3064
+ METHOD_FACTORIES.Set = function(accessor)
3065
+ return function(value: any, replicate: boolean?)
3066
+ local tree = accessorTree(accessor)
3067
+ assertAlive(tree)
3068
+ local schema = accessorSchema(accessor)
3069
+ local stored = applySet(tree, accessorPath(accessor), schema, value, { Replicate = replicate })
3070
+ return unpackRead(schema, stored)
3071
+ end
3072
+ end
3073
+
3074
+ METHOD_FACTORIES.Update = function(accessor)
3075
+ return function(fn: (any) -> any, replicate: boolean?)
3076
+ local tree = accessorTree(accessor)
3077
+ assertAlive(tree)
3078
+ local schema = accessorSchema(accessor)
3079
+ local current = unpackRead(schema, readValue(tree, accessorPath(accessor)))
3080
+ local stored = applySet(tree, accessorPath(accessor), schema, fn(current), { Replicate = replicate })
3081
+ return unpackRead(schema, stored)
3082
+ end
3083
+ end
3084
+
3085
+ METHOD_FACTORIES.Clone = function(accessor)
3086
+ return function()
3087
+ local tree = accessorTree(accessor)
3088
+ assertAlive(tree)
3089
+ settleForRead(tree)
3090
+ local path = accessorPath(accessor)
3091
+ if #path == 0 then
3092
+ -- Deliberately NOT frozen: an editable copy is the point of Clone, and
3093
+ -- it is already detached from the store.
3094
+ return rootShell(tree, true)
3095
+ end
3096
+ -- detachedCopy deep-clones and unpacks together when anything below is packed,
3097
+ -- so the copy is independent and in its read shape.
3098
+ return detachedCopy(accessorSchema(accessor), readValue(tree, path))
3099
+ end
3100
+ end
3101
+
3102
+ -- Flags helpers. Each reads the current set, edits it and writes the whole field
3103
+ -- back, so a flag change is one validated, replicated write firing one Changed.
3104
+ local function flagsSchema(accessor: Accessor, method: string): SchemaNode
3105
+ local schema = accessorSchema(accessor)
3106
+ if not schema or schema.ValueType ~= "flags" then
3107
+ error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Flags field ({method})`, 3)
3108
+ end
3109
+ return schema
3110
+ end
3111
+
3112
+ local function flagsSet(
3113
+ tree: Tree,
3114
+ accessor: Accessor,
3115
+ schema: SchemaNode,
3116
+ name: string,
3117
+ on: boolean,
3118
+ replicate: boolean?
3119
+ )
3120
+ local index = schema.MemberIndex :: { [string]: number }
3121
+ if index[name] == nil then
3122
+ error(`Scribe: "{tostring(name)}" is not a member of "{Util.pathString(accessorPath(accessor))}"`, 3)
3123
+ end
3124
+ local current = readValue(tree, accessorPath(accessor))
3125
+ local enabled: { [string]: boolean } = {}
3126
+ if type(current) == "table" then
3127
+ for _, member in current :: { string } do
3128
+ enabled[member] = true
3129
+ end
3130
+ end
3131
+ -- `or false` matters: an unset flag reads nil, and nil == false is false, so a
3132
+ -- Disable on an already-off flag would otherwise write and fire Changed.
3133
+ if (enabled[name] or false) == on then
3134
+ return -- no transition, so no write, no Changed, no replication op
3135
+ end
3136
+ enabled[name] = on or nil
3137
+ local out = {}
3138
+ for _, member in schema.Members :: { string } do
3139
+ if enabled[member] then
3140
+ table.insert(out, member)
3141
+ end
3142
+ end
3143
+ applySet(tree, accessorPath(accessor), schema, out, { Replicate = replicate })
3144
+ end
3145
+
3146
+ METHOD_FACTORIES.Enable = function(accessor)
3147
+ return function(name: string, replicate: boolean?)
3148
+ local tree = accessorTree(accessor)
3149
+ assertAlive(tree)
3150
+ flagsSet(tree, accessor, flagsSchema(accessor, "Enable"), name, true, replicate)
3151
+ end
3152
+ end
3153
+
3154
+ METHOD_FACTORIES.Disable = function(accessor)
3155
+ return function(name: string, replicate: boolean?)
3156
+ local tree = accessorTree(accessor)
3157
+ assertAlive(tree)
3158
+ flagsSet(tree, accessor, flagsSchema(accessor, "Disable"), name, false, replicate)
3159
+ end
3160
+ end
3161
+
3162
+ -- Scribe.SetOf membership. Both go through the whole-value write path, so
3163
+ -- validateWrite's dedupe-and-sort maintains the invariant; these only decide
3164
+ -- whether a write is needed at all.
3165
+ local function setSchema(accessor: Accessor, method: string): SchemaNode
3166
+ local schema = accessorSchema(accessor)
3167
+ if not schema or not schema.Unique then
3168
+ error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.SetOf field ({method})`, 3)
3169
+ end
3170
+ return schema
3171
+ end
3172
+
3173
+ METHOD_FACTORIES.Add = function(accessor)
3174
+ return function(item: any, replicate: boolean?)
3175
+ local tree = accessorTree(accessor)
3176
+ assertAlive(tree)
3177
+ local schema = setSchema(accessor, "Add")
3178
+ local path = accessorPath(accessor)
3179
+ if item == nil then
3180
+ error(`Scribe: cannot Add nil to "{Util.pathString(path)}"`, 3)
3181
+ end
3182
+ local current = readValue(tree, path)
3183
+ local arr = if type(current) == "table" then current :: { any } else {}
3184
+ if findElement(schema, arr, item) ~= nil then
3185
+ return false -- already a member: no write, no op, no Changed
3186
+ end
3187
+ local next_ = table.clone(arr)
3188
+ table.insert(next_, item)
3189
+ applySet(tree, path, schema, next_, { Replicate = replicate })
3190
+ return true
3191
+ end
3192
+ end
3193
+
3194
+ -- Scribe.Big arithmetic. Each reads, applies the operation and writes the whole
3195
+ -- field, so bounds, replication and the economy event run on the normal write path.
3196
+ local function bigSchema(accessor: Accessor, method: string): SchemaNode
3197
+ local schema = accessorSchema(accessor)
3198
+ if not schema or schema.ValueType ~= "big" then
3199
+ error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Big field ({method})`, 3)
3200
+ end
3201
+ return schema
3202
+ end
3203
+
3204
+ local function bigOperand(accessor: Accessor, method: string, value: any): any
3205
+ local parsed = Big.from(value)
3206
+ if parsed == nil then
3207
+ error(`Scribe: {method} on "{Util.pathString(accessorPath(accessor))}" needs a number or numeric string`, 3)
3208
+ end
3209
+ return parsed
3210
+ end
3211
+
3212
+ local function bigApply(accessor: Accessor, method: string, value: any, replicate: boolean?, op: (any, any) -> any): any
3213
+ local tree = accessorTree(accessor)
3214
+ assertAlive(tree)
3215
+ local schema = bigSchema(accessor, method)
3216
+ local path = accessorPath(accessor)
3217
+ local operand = bigOperand(accessor, method, value)
3218
+ -- A Nullable leaf has no default and is legitimately absent, so there is nothing to
3219
+ -- arithmetic against. Starting from 0 would contradict every other Scribe.Optional
3220
+ -- leaf, where Increment on an absent value errors.
3221
+ local current = Big.from(readValue(tree, path)) or Big.from(schema.Default)
3222
+ if current == nil then
3223
+ if schema.Nullable then
3224
+ validationError(path, `{method} on an absent Scribe.Optional value`)
3225
+ end
3226
+ current = Big.from(0)
3227
+ end
3228
+ local result = op(current, operand)
3229
+ if result == nil then
3230
+ error(`Scribe: {method} on "{Util.pathString(path)}" divided by zero`, 3)
3231
+ end
3232
+ return unpackRead(schema, applySet(tree, path, schema, result, { Replicate = replicate }))
3233
+ end
3234
+
3235
+ METHOD_FACTORIES.Multiply = function(accessor)
3236
+ return function(factor: any, replicate: boolean?)
3237
+ return bigApply(accessor, "Multiply", factor, replicate, Big.mul)
3238
+ end
3239
+ end
3240
+
3241
+ METHOD_FACTORIES.Divide = function(accessor)
3242
+ return function(factor: any, replicate: boolean?)
3243
+ return bigApply(accessor, "Divide", factor, replicate, Big.div)
3244
+ end
3245
+ end
3246
+
3247
+ local function incrementImpl(accessor: Accessor, delta: any, tagsOrReplicate: any, defaultFlow: string): any
3248
+ local tree = accessorTree(accessor)
3249
+ assertAlive(tree)
3250
+ local path = accessorPath(accessor)
3251
+ local bigNode = accessorSchema(accessor)
3252
+ if not (bigNode and bigNode.ValueType == "big") and defaultFlow == "Sink" and type(delta) == "number" then
3253
+ delta = -delta
3254
+ end
3255
+ if bigNode and bigNode.ValueType == "big" then
3256
+ -- Same economy plumbing as a plain number, with arithmetic that does not
3257
+ -- lose the value at 2^53.
3258
+ local method = if defaultFlow == "Source" then "Increment" else "Decrement"
3259
+ local signed = bigOperand(accessor, method, delta)
3260
+ if defaultFlow == "Sink" then
3261
+ signed = Big.negate(signed)
3262
+ end
3263
+ local tags, replicate = parseIncrementArgs(tagsOrReplicate)
3264
+ local stored = Big.from(readValue(tree, path)) or Big.from(bigNode.Default)
3265
+ if stored == nil and bigNode.Nullable then
3266
+ validationError(path, `{method} on an absent Scribe.Optional value`)
3267
+ end
3268
+ local before: Big.Big = stored or BIG_ZERO
3269
+ local result = bigApply(accessor, method, signed, replicate, Big.add)
3270
+ if tags and tree.Params.OnEconomy then
3271
+ local after: Big.Big = Big.from(result) or BIG_ZERO
3272
+ -- Report the EFFECTIVE change so a Min/Max clamp does not over-report.
3273
+ -- LogEconomyEvent takes a double, so the conversion happens here;
3274
+ -- Big.toNumber saturates past the double range, which is lossy but
3275
+ -- reaches the log, unlike a table that Analytics' pcall would swallow.
3276
+ local effective = Big.sub(after, before)
3277
+ if Big.compare(effective, BIG_ZERO) ~= 0 then
3278
+ local applied = table.clone(tags)
3279
+ if applied.Flow == nil then
3280
+ applied.Flow = defaultFlow
3281
+ end
3282
+ local effectiveDelta = Big.toNumber(effective)
3283
+ local newValue = Big.toNumber(after)
3284
+ local txn = tree._txn
3285
+ if txn then
3286
+ table.insert(txn.Economy, { Path = path, Delta = effectiveDelta, New = newValue, Tags = applied })
3287
+ else
3288
+ tree.Params.OnEconomy(path, effectiveDelta, newValue, applied)
3289
+ end
3290
+ end
3291
+ end
3292
+ return result
3293
+ end
3294
+ if type(delta) ~= "number" or delta ~= delta then
3295
+ validationError(path, "Increment delta must be a number")
3296
+ end
3297
+ local schema = accessorSchema(accessor)
3298
+ local current = readValue(tree, path)
3299
+ if current == nil then
3300
+ -- A declared element leaf not yet written starts from its compiled default
3301
+ -- rather than erroring, so `Resources.Wood.Increment(5)` on a fresh key
3302
+ -- yields 5. Scribe.Optional leaves have no default and keep erroring.
3303
+ if schema and type(schema.Default) == "number" and inElementSubtree(schema) then
3304
+ current = schema.Default
3305
+ end
3306
+ end
3307
+ if type(current) ~= "number" then
3308
+ validationError(path, `Increment on non-number value ({typeof(current)})`)
3309
+ end
3310
+ local tags, replicate = parseIncrementArgs(tagsOrReplicate)
3311
+ local newValue = applySet(tree, path, schema, current + delta, { Replicate = replicate }) :: number
3312
+ -- Report the EFFECTIVE change, not the requested delta: a bounded field may clamp
3313
+ -- or reject, so logging the raw delta over-reports and firing on a no-op logs a
3314
+ -- transaction the balance never made.
3315
+ local effectiveDelta = newValue - current
3316
+ if tags and tree.Params.OnEconomy and effectiveDelta ~= 0 then
3317
+ local applied = table.clone(tags)
3318
+ if applied.Flow == nil then
3319
+ applied.Flow = defaultFlow
3320
+ end
3321
+ local txn = tree._txn
3322
+ if txn then
3323
+ -- Deferred like replication ops: fired on commit, dropped on rollback,
3324
+ -- so a rolled-back Increment never logs a transaction.
3325
+ table.insert(txn.Economy, { Path = path, Delta = effectiveDelta, New = newValue, Tags = applied })
3326
+ else
3327
+ tree.Params.OnEconomy(path, effectiveDelta, newValue, applied)
3328
+ end
3329
+ end
3330
+ return newValue
3331
+ end
3332
+
3333
+ METHOD_FACTORIES.Increment = function(accessor)
3334
+ return function(delta: number, tagsOrReplicate: any?)
3335
+ return incrementImpl(accessor, delta, tagsOrReplicate, "Source")
3336
+ end
3337
+ end
3338
+
3339
+ METHOD_FACTORIES.Decrement = function(accessor)
3340
+ return function(delta: number, tagsOrReplicate: any?)
3341
+ local tree = accessorTree(accessor)
3342
+ if tree.Params.DevMode and type(delta) == "number" and delta < 0 then
3343
+ local warnFn = tree.Params.LogWarn
3344
+ if warnFn then
3345
+ warnFn(
3346
+ `Decrement called with a negative delta at "{Util.pathString(accessorPath(accessor))}", likely a sign error`
3347
+ )
3348
+ end
3349
+ end
3350
+ return incrementImpl(accessor, delta, tagsOrReplicate, "Sink")
3351
+ end
3352
+ end
3353
+
3354
+ -- Min/Max read the declarator's bounds off the static schema, so they work on both
3355
+ -- realms and before data has loaded.
3356
+ METHOD_FACTORIES.Min = function(accessor)
3357
+ return function(): number?
3358
+ local schema = accessorSchema(accessor)
3359
+ return if schema then schema.Min else nil
3360
+ end
3361
+ end
3362
+
3363
+ METHOD_FACTORIES.Max = function(accessor)
3364
+ return function(): number?
3365
+ local schema = accessorSchema(accessor)
3366
+ return if schema then schema.Max else nil
3367
+ end
3368
+ end
3369
+
3370
+ -- The declarator's default, straight off the static schema: a fresh datatype, a Big,
3371
+ -- a deep copy for tables and buffers, or the scalar itself.
3372
+ METHOD_FACTORIES.Default = function(accessor)
3373
+ return function(): any
3374
+ local schema = accessorSchema(accessor)
3375
+ if schema == nil then
3376
+ return nil
3377
+ end
3378
+ if Template.IsPacked(schema) then
3379
+ -- The stored Default holds the PACKED form, so deep-clone and unpack
3380
+ -- together, matching Clone(); a plain deepClone would hand back the
3381
+ -- stored shape.
3382
+ return cloneUnpack(schema, schema.Default)
3383
+ end
3384
+ return Util.deepClone(schema.Default)
3385
+ end
3386
+ end
3387
+
3388
+ METHOD_FACTORIES.Toggle = function(accessor)
3389
+ return function(nameOrReplicate: any, replicate: boolean?)
3390
+ local tree = accessorTree(accessor)
3391
+ assertAlive(tree)
3392
+ local path = accessorPath(accessor)
3393
+ local schema = accessorSchema(accessor)
3394
+ if schema and schema.ValueType == "flags" then
3395
+ -- On a Scribe.Flags field Toggle names the flag to flip, since the field
3396
+ -- holds a set rather than one boolean.
3397
+ if type(nameOrReplicate) ~= "string" then
3398
+ error(`Scribe: Toggle on a Scribe.Flags field takes a member name`, 3)
3399
+ end
3400
+ local index = schema.MemberIndex :: { [string]: number }
3401
+ if index[nameOrReplicate] == nil then
3402
+ error(`Scribe: "{nameOrReplicate}" is not a member of "{Util.pathString(path)}"`, 3)
3403
+ end
3404
+ local current = readValue(tree, path)
3405
+ local on = false
3406
+ if type(current) == "table" then
3407
+ for _, member in current :: { string } do
3408
+ if member == nameOrReplicate then
3409
+ on = true
3410
+ break
3411
+ end
3412
+ end
3413
+ end
3414
+ flagsSet(tree, accessor, schema, nameOrReplicate, not on, replicate)
3415
+ return not on
3416
+ end
3417
+ local replicateFlag = nameOrReplicate :: boolean?
3418
+ local current = readValue(tree, path)
3419
+ if current == nil and schema and type(schema.Default) == "boolean" and inElementSubtree(schema) then
3420
+ -- Same fresh-element fallback as Increment: the entry materializes on
3421
+ -- first write, so Toggle starts from the declared default.
3422
+ current = schema.Default
3423
+ end
3424
+ if type(current) ~= "boolean" then
3425
+ validationError(path, `Toggle on non-boolean value ({typeof(current)})`)
3426
+ end
3427
+ return applySet(tree, path, schema, not current, { Replicate = replicateFlag })
3428
+ end
3429
+ end
3430
+
3431
+ METHOD_FACTORIES.Changed = function(accessor)
3432
+ local guarded = isPublicReserved(accessor)
3433
+ return function(fn: (any, any) -> ())
3434
+ local tree = accessorTree(accessor)
3435
+ local schema = accessorSchema(accessor)
3436
+ local path = accessorPath(accessor)
3437
+
3438
+ -- A container Changed takes no third `key` argument: one fire covers every
3439
+ -- child a batch or a frame touched, so no single key describes it. Refused at
3440
+ -- connect time rather than passing nil forever, which would make
3441
+ -- `if key == "Coins"` quietly stop matching. Arity is read once per connect.
3442
+ if isContainerNode(tree, schema, path) then
3443
+ local params, isVararg = debug.info(fn, "a")
3444
+ if not isVararg and params > 2 then
3445
+ error(
3446
+ `Scribe: a container Changed listener takes (new, old). "{Util.pathString(path)}" declares `
3447
+ .. `{params} parameters. The third key argument was removed because one fire can now cover `
3448
+ .. `several children. Use OnChildChanged(key, value) to learn which child moved.`,
3449
+ 3
3450
+ )
3451
+ end
3452
+ end
3453
+
3454
+ if #path == 0 then
3455
+ warnIfRootObserveIsExpensive(tree, "Changed")
3456
+ -- Match what Get hands back. The root's only fires are ancestor fires, where
3457
+ -- old and new are one reference, so a single shell serves both and a
3458
+ -- listener's `if new == old then return` holds.
3459
+ local inner = fn
3460
+ fn = function()
3461
+ local shell = frozenRootShell(tree)
3462
+ inner(shell, shell)
3463
+ end
3464
+ return connect(tree, path, "Changed", fn)
3465
+ end
3466
+ -- `guarded` joins IsPacked here because a listener is a reader: handed the live
3467
+ -- reserved table it could write through it, the same hole readOut closes on Get.
3468
+ if guarded or Template.IsPacked(schema) then
3469
+ local inner = fn
3470
+ fn = function(newValue, oldValue)
3471
+ local newUnpacked = readOut(guarded, schema, newValue)
3472
+ -- An ancestor container fire passes the SAME reference for new and old, so
3473
+ -- reuse the unpacked value: it skips a walk and keeps reference equality
3474
+ -- for a listener's `if new == old then return` guard.
3475
+ local oldUnpacked = if oldValue == newValue then newUnpacked else readOut(guarded, schema, oldValue)
3476
+ inner(newUnpacked, oldUnpacked)
3477
+ end
3478
+ end
3479
+ return connect(tree, path, "Changed", fn)
3480
+ end
3481
+ end
3482
+
3483
+ METHOD_FACTORIES.Observe = function(accessor)
3484
+ local guarded = isPublicReserved(accessor)
3485
+ return function(fn: (any) -> ())
3486
+ local tree = accessorTree(accessor)
3487
+ assertAlive(tree)
3488
+ local schema = accessorSchema(accessor)
3489
+ local path = accessorPath(accessor)
3490
+ local isRoot = #path == 0
3491
+ if isRoot then
3492
+ warnIfRootObserveIsExpensive(tree, "Observe")
3493
+ end
3494
+ local disconnect = connect(tree, path, "Changed", function(newValue)
3495
+ fn(if isRoot then frozenRootShell(tree) else readOut(guarded, schema, newValue))
3496
+ end)
3497
+ local ok, err = xpcall(function()
3498
+ fn(if isRoot then frozenRootShell(tree) else readOut(guarded, schema, readValue(tree, path)))
3499
+ end, function(e)
3500
+ return debug.traceback(tostring(e), 2)
3501
+ end)
3502
+ if not ok then
3503
+ tree.Params.LogError(`listener error at "{accessorKey(accessor)}" (Observe): {err}`)
3504
+ end
3505
+ return disconnect
3506
+ end
3507
+ end
3508
+
3509
+ METHOD_FACTORIES.Insert = function(accessor)
3510
+ return function(item: any, pos: number?, replicate: boolean?)
3511
+ local tree = accessorTree(accessor)
3512
+ assertAlive(tree)
3513
+ applyInsert(tree, accessorPath(accessor), accessorSchema(accessor), item, pos, { Replicate = replicate })
3514
+ end
3515
+ end
3516
+
3517
+ METHOD_FACTORIES.Remove = function(accessor)
3518
+ return function(posOrKey: any, replicate: boolean?)
3519
+ local tree = accessorTree(accessor)
3520
+ assertAlive(tree)
3521
+ local setNode = accessorSchema(accessor)
3522
+ if setNode and setNode.Unique then
3523
+ -- A set has no indices, so Remove names the member to drop.
3524
+ local path = accessorPath(accessor)
3525
+ local current = readValue(tree, path)
3526
+ local arr = if type(current) == "table" then current :: { any } else {}
3527
+ local at = findElement(setNode, arr, posOrKey)
3528
+ if at == nil then
3529
+ return false -- not a member: nothing to do
3530
+ end
3531
+ local next_ = table.clone(arr)
3532
+ table.remove(next_, at)
3533
+ applySet(tree, path, setNode, next_, { Replicate = replicate })
3534
+ return true
3535
+ end
3536
+ -- Branch on the SCHEMA, not the Lua type of the argument: a
3537
+ -- Scribe.MapOf("integer") takes number keys, and reading those as array indices
3538
+ -- would remove the wrong entry. The type fallback covers untyped nodes.
3539
+ if (setNode and setNode.Container == "Dict") or type(posOrKey) == "string" then
3540
+ -- Dictionary removal: sugar for Set(nil) with a useful return.
3541
+ local path = table.clone(accessorPath(accessor))
3542
+ table.insert(path, posOrKey)
3543
+ local schema = accessorSchema(accessor)
3544
+ local childSchema = if schema then Template.ChildSchema(schema, posOrKey) else nil
3545
+ local container, key = resolveContainer(tree, path, false)
3546
+ local old = if container then container[key] else nil
3547
+ if old ~= nil then
3548
+ applySet(tree, path, childSchema, nil, { Replicate = replicate })
3549
+ end
3550
+ -- Convert at the datatype boundary: a removed static datatype leaf is
3551
+ -- stored packed, so return the real value.
3552
+ return unpackRead(childSchema, old)
3553
+ end
3554
+ -- Same datatype boundary as the dictionary branch: an element of a
3555
+ -- Scribe.ArrayOf(Scribe.CFrame(...)) is stored packed, so returning it raw
3556
+ -- would hand the caller a buffer.
3557
+ local schema = accessorSchema(accessor)
3558
+ local removed =
3559
+ applyArrayRemove(tree, accessorPath(accessor), schema, posOrKey :: number?, { Replicate = replicate })
3560
+ return unpackRead(elementSchemaOf(schema), removed)
3561
+ end
3562
+ end
3563
+
3564
+ METHOD_FACTORIES.RemoveValue = function(accessor)
3565
+ return function(item: any, replicate: boolean?): (any, number?)
3566
+ local tree = accessorTree(accessor)
3567
+ assertAlive(tree)
3568
+ local schema = accessorSchema(accessor)
3569
+ local arr = readValue(tree, accessorPath(accessor))
3570
+ if type(arr) ~= "table" then
3571
+ return nil, nil
3572
+ end
3573
+ local index = findElement(schema, arr, item)
3574
+ if index == nil then
3575
+ return nil, nil
3576
+ end
3577
+ local removed = applyArrayRemove(tree, accessorPath(accessor), schema, index, { Replicate = replicate })
3578
+ return unpackRead(elementSchemaOf(schema), removed), index
3579
+ end
3580
+ end
3581
+
3582
+ METHOD_FACTORIES.Find = function(accessor)
3583
+ return function(item: any): number?
3584
+ local tree = accessorTree(accessor)
3585
+ assertAlive(tree)
3586
+ local arr = readValue(tree, accessorPath(accessor))
3587
+ if type(arr) ~= "table" then
3588
+ return nil
3589
+ end
3590
+ return findElement(accessorSchema(accessor), arr, item)
3591
+ end
3592
+ end
3593
+
3594
+ METHOD_FACTORIES.Has = function(accessor)
3595
+ return function(item: any)
3596
+ local tree = accessorTree(accessor)
3597
+ assertAlive(tree)
3598
+ local arr = readValue(tree, accessorPath(accessor))
3599
+ return type(arr) == "table" and findElement(accessorSchema(accessor), arr, item) ~= nil
3600
+ end
3601
+ end
3602
+
3603
+ METHOD_FACTORIES.Clear = function(accessor)
3604
+ return function(replicate: boolean?)
3605
+ local tree = accessorTree(accessor)
3606
+ assertAlive(tree)
3607
+ applyClear(tree, accessorPath(accessor), accessorSchema(accessor), { Replicate = replicate })
3608
+ end
3609
+ end
3610
+
3611
+ METHOD_FACTORIES.Count = function(accessor)
3612
+ return function()
3613
+ local tree = accessorTree(accessor)
3614
+ assertAlive(tree)
3615
+ local value = readValue(tree, accessorPath(accessor))
3616
+ if type(value) ~= "table" then
3617
+ return 0
3618
+ end
3619
+ return Util.count(value)
3620
+ end
3621
+ end
3622
+
3623
+ -- Value handed to an entry-level listener. Packed values are converted back and a
3624
+ -- table is copied: the fired value IS the stored one, so a listener mutating it
3625
+ -- would edit authoritative state with no validation and no replication.
3626
+ local function entryValueForListener(guarded: boolean, schema: SchemaNode?, value: any): any
3627
+ -- Reserved root read by game code gets the same detached copy readOut hands back:
3628
+ -- the live `{ Id, At }` record would let a listener blank an Id and un-dedupe
3629
+ -- that purchase.
3630
+ if guarded and type(value) == "table" then
3631
+ return detachedCopy(schema, value)
3632
+ end
3633
+ if Template.IsPacked(schema) then
3634
+ return cloneUnpack(schema, value)
3635
+ end
3636
+ -- Only a DECLARED element is copied. An untyped container must keep handing out the
3637
+ -- stored reference, because Has/Find/RemoveValue fall back to table.find and a copy
3638
+ -- would make a listener's own entry unfindable.
3639
+ if schema and schema.IsElement and type(value) == "table" then
3640
+ return Util.deepClone(value)
3641
+ end
3642
+ return value
3643
+ end
3644
+
3645
+ -- The listener kinds that receive a container ENTRY rather than the container itself,
3646
+ -- and so need the same datatype conversion Changed and Observe do.
3647
+ for _, event in { "OnInsert", "OnRemove", "OnKeyAdded", "OnKeyRemoved", "OnChildChanged" } do
3648
+ METHOD_FACTORIES[event] = function(accessor)
3649
+ local guarded = isPublicReserved(accessor)
3650
+ -- The root accessor's own path is empty, so isPublicReserved answers false for it,
3651
+ -- but these events carry a CHILD and one of the root's children IS the reserved
3652
+ -- root: without this, binding data.OnChildChanged hands game code the live ledger
3653
+ -- by reference. The PRIVILEGED term is unreachable today and stays, so a
3654
+ -- privileged root added later does not silently start receiving copies.
3655
+ local rootGuard = #accessorPath(accessor) == 0 and not PRIVILEGED[accessor]
3656
+ return function(fn: (...any) -> ())
3657
+ local tree = accessorTree(accessor)
3658
+ local schema = accessorSchema(accessor)
3659
+ local inner = fn
3660
+ local wrapped: (...any) -> ()
3661
+ if event == "OnInsert" or event == "OnRemove" then
3662
+ local element = elementSchemaOf(schema)
3663
+ wrapped = function(value: any, index: any)
3664
+ inner(entryValueForListener(guarded, element, value), index)
3665
+ end
3666
+ elseif event == "OnChildChanged" then
3667
+ -- Carries a transition, so both sides need unpacking. OnKeyAdded and
3668
+ -- OnKeyRemoved take a single value: an appearance has no prior and a
3669
+ -- disappearance has no successor.
3670
+ wrapped = function(key: any, newValue: any, oldValue: any)
3671
+ local childSchema = if schema then Template.ChildSchema(schema, key) else nil
3672
+ local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
3673
+ inner(
3674
+ key,
3675
+ entryValueForListener(g, childSchema, newValue),
3676
+ entryValueForListener(g, childSchema, oldValue)
3677
+ )
3678
+ end
3679
+ else
3680
+ wrapped = function(key: any, value: any)
3681
+ local childSchema = if schema then Template.ChildSchema(schema, key) else nil
3682
+ -- Same key-derived guard. Unreachable today, since the reserved root is
3683
+ -- created with the tree and never appears or disappears
3684
+ -- (RootChildLedgerGuard.spec pins that), but kept so the sibling wrappers
3685
+ -- do not differ for no reason.
3686
+ local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
3687
+ inner(key, entryValueForListener(g, childSchema, value))
3688
+ end
3689
+ end
3690
+ return connect(tree, accessorPath(accessor), event, wrapped)
3691
+ end
3692
+ end
3693
+ end
3694
+
3695
+ local function timedHooks(accessor: Accessor): TimedHooks
3696
+ local tree = accessorTree(accessor)
3697
+ local schema = accessorSchema(accessor)
3698
+ if not schema or not schema.Timed then
3699
+ error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Timed field`, 3)
3700
+ end
3701
+ local hooks = tree.Params.TimedHooks
3702
+ if not hooks then
3703
+ error("Scribe: timed fields are managed on the server", 3)
3704
+ end
3705
+ return hooks
3706
+ end
3707
+
3708
+ METHOD_FACTORIES.SetTimed = function(accessor)
3709
+ return function(value: any, seconds: number, replicate: boolean?)
3710
+ local tree = accessorTree(accessor)
3711
+ assertAlive(tree)
3712
+ timedHooks(accessor).SetTimed(accessor, value, seconds, replicate)
3713
+ end
3714
+ end
3715
+
3716
+ METHOD_FACTORIES.ExtendTimed = function(accessor)
3717
+ return function(seconds: number, replicate: boolean?)
3718
+ local tree = accessorTree(accessor)
3719
+ assertAlive(tree)
3720
+ timedHooks(accessor).ExtendTimed(accessor, seconds, replicate)
3721
+ end
3722
+ end
3723
+
3724
+ METHOD_FACTORIES.Active = function(accessor)
3725
+ return function()
3726
+ local tree = accessorTree(accessor)
3727
+ assertAlive(tree)
3728
+ return timedHooks(accessor).Active(accessor)
3729
+ end
3730
+ end
3731
+
3732
+ -- Accessor metatable -----------------------------------------------------------------
3733
+
3734
+ -- Every method that mutates; all of them are refused on a derived field. Listed by
3735
+ -- name rather than inferred, so a method added later has to make a deliberate choice
3736
+ -- rather than silently becoming writable.
3737
+ local MUTATOR_METHODS: { [string]: boolean } = {
3738
+ Set = true,
3739
+ Update = true,
3740
+ Increment = true,
3741
+ Decrement = true,
3742
+ Multiply = true,
3743
+ Divide = true,
3744
+ Toggle = true,
3745
+ Enable = true,
3746
+ Disable = true,
3747
+ Add = true,
3748
+ Insert = true,
3749
+ Remove = true,
3750
+ RemoveValue = true,
3751
+ Clear = true,
3752
+ SetTimed = true,
3753
+ ExtendTimed = true,
3754
+ }
3755
+
3756
+ -- One module-private identity per mutator name, used as the rawset key its built
3757
+ -- method is cached under. Private so nothing outside this file can name or plant a
3758
+ -- cached mutator. See accessorIndex for why they are not cached under their own name.
3759
+ local MUTATOR_CACHE_KEY: { [string]: any } = {}
3760
+ for name in MUTATOR_METHODS do
3761
+ MUTATOR_CACHE_KEY[name] = {}
3762
+ end
3763
+
3764
+ local function accessorIndex(accessor: Accessor, key: any, childOnly: boolean?): any
3765
+ local factory = if childOnly then nil else METHOD_FACTORIES[key]
3766
+ if factory then
3767
+ if MUTATOR_METHODS[key] then
3768
+ -- A write to a DIFFERENT player's tree is refused while a transaction is open: it
3769
+ -- cannot be rolled back with the transaction, so one half of a trade could commit
3770
+ -- while the other is undone. Reads never enter this branch. The residual: a handle
3771
+ -- taken BEFORE the transaction opened (`local inc = other.Coins.Increment`) is not
3772
+ -- refused, since no index happens at the call. Gated on OPEN_TXN_TREE because
3773
+ -- pathString allocates; level 3 blames the game code that indexed the mutator.
3774
+ if OPEN_TXN_TREE ~= nil then
3775
+ assertSameTreeWrite(accessorTree(accessor), Util.pathString(accessorPath(accessor)), 3)
3776
+ end
3777
+ -- The reserved root is Scribe's own ledger, and ServerOnly only keeps it off the
3778
+ -- wire. Clearing ProcessedPurchaseIds makes the next retried receipt grant a
3779
+ -- second time; dropping Version re-runs every migration against migrated data.
3780
+ -- Refused by CALLER, not by object: the library writes these paths through
3781
+ -- Tree.Reserved, which holds the capability.
3782
+ local path = accessorPath(accessor)
3783
+ if path[1] == Template.RESERVED_ROOT and not PRIVILEGED[accessor] then
3784
+ error(
3785
+ `Scribe: "{Util.pathString(path)}" is inside the reserved "{Template.RESERVED_ROOT}" root `
3786
+ .. `and cannot be written; it is Scribe's own ledger -- processed receipt ids, perks, `
3787
+ .. `gift credits, pending gifts, purchase logs, timers and the schema version. Read it `
3788
+ .. `with the typed readers (Owns, GetGiftCredits, GetPurchases) and change it through `
3789
+ .. `the APIs that own it (GrantPerk, RevokePerk, Purchase, PromptGift)`,
3790
+ 2
3791
+ )
3792
+ end
3793
+ local schema = accessorSchema(accessor)
3794
+ local derived = if schema then schema.Derived else nil
3795
+ if derived then
3796
+ local inputs = table.create(#derived.InputPaths)
3797
+ for i, segments in derived.InputPaths do
3798
+ inputs[i] = table.concat(segments, ".")
3799
+ end
3800
+ error(
3801
+ `Scribe: "{Util.pathString(accessorPath(accessor))}" is a derived field and cannot be written; `
3802
+ .. `it is computed from {table.concat(inputs, ", ")}`,
3803
+ 2
3804
+ )
3805
+ end
3806
+ -- Cached under a module-private identity rather than under `key`, so every
3807
+ -- `x.Set` keeps going through __index and past the guards. A plain rawset under
3808
+ -- `key`, as the non-mutator branch below does, would be satisfied off the
3809
+ -- accessor table on the second read: harmless for the fixed refusals, wrong for
3810
+ -- the transaction one, which changes with the caller. Cache the method, not the
3811
+ -- decision.
3812
+ local cached = rawget(accessor, MUTATOR_CACHE_KEY[key])
3813
+ if cached ~= nil then
3814
+ return cached
3815
+ end
3816
+ local built = factory(accessor)
3817
+ rawset(accessor, MUTATOR_CACHE_KEY[key], built)
3818
+ return built
3819
+ end
3820
+ local method = factory(accessor)
3821
+ rawset(accessor, key, method)
3822
+ return method
3823
+ end
3824
+
3825
+ local tree = accessorTree(accessor)
3826
+ assertAlive(tree)
3827
+ if type(key) ~= "string" and type(key) ~= "number" then
3828
+ error(`Scribe: invalid child key of type {typeof(key)}`, 2)
3829
+ end
3830
+ -- The pathKey separator (char 31) would let a crafted dynamic key alias a
3831
+ -- distinct path, corrupting coalescing, listeners and txn rollback.
3832
+ if type(key) == "string" and string.find(key, "\31", 1, true) then
3833
+ error("Scribe: dictionary keys may not contain control character \\31", 2)
3834
+ end
3835
+ -- Invalid UTF-8 in a dynamic key fails the DataStore save for the entire profile.
3836
+ -- Rejected here so the error points at the offending index, not a later save.
3837
+ if type(key) == "string" and not Util.isUtf8(key) then
3838
+ error("Scribe: dictionary keys must be valid UTF-8", 2)
3839
+ end
3840
+ -- Fractional or non-finite numeric keys do not survive the DataStore JSON round
3841
+ -- trip, which would diverge the stored key from its pathKey and listeners.
3842
+ if type(key) == "number" and (key ~= key or key == math.huge or key == -math.huge or key % 1 ~= 0) then
3843
+ error(`Scribe: numeric dictionary keys must be finite integers, got {tostring(key)}`, 2)
3844
+ end
3845
+
3846
+ local children = rawget(accessor, F_CHILDREN) :: { [any]: any }
3847
+ local child = children[key]
3848
+ if child == nil then
3849
+ local schema = accessorSchema(accessor)
3850
+ -- Kind alone is not enough: Scribe.Big and Scribe.Flags compile as Kind
3851
+ -- "table" because their stored form is one, so indexing them would let
3852
+ -- `Tutorial[1].Set(...)` overwrite an enabled flag in place.
3853
+ if schema and (schema.Kind == "leaf" or schema.ValueType == "big" or schema.ValueType == "flags") then
3854
+ error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is a leaf value and has no children`, 2)
3855
+ end
3856
+ local path = table.clone(accessorPath(accessor))
3857
+ table.insert(path, key)
3858
+ local childSchema = if schema then Template.ChildSchema(schema, key) else nil
3859
+ -- A declared element record has a fixed field set, so an undeclared key is a
3860
+ -- typo. Refusing it HERE is load-bearing: a nil child schema reads as untyped
3861
+ -- everywhere downstream, so a write under a misspelled field would bypass
3862
+ -- MaxKeys, MaxItems, MaxKeyLength and the array contiguity rule entirely.
3863
+ if childSchema == nil and schema and schema.Closed then
3864
+ error(
3865
+ `Scribe: "{tostring(key)}" is not a declared field of the element shape at `
3866
+ .. `"{Util.pathString(accessorPath(accessor))}"`,
3867
+ 2
3868
+ )
3869
+ end
3870
+ -- The capability follows the HANDLE down, so Tree.Reserved.Perks.VIP may
3871
+ -- write and Accessor[RESERVED_ROOT].Perks.VIP may not.
3872
+ child = newAccessor(tree, path, childSchema, PRIVILEGED[accessor])
3873
+ children[key] = child
3874
+ end
3875
+ return child
3876
+ end
3877
+
3878
+ -- An explicit child lookup shares every indexing guard, schema lookup and cache,
3879
+ -- but bypasses method lookup. In particular, dictionaries may store keys such as
3880
+ -- "Get", "Remove" or "Child" without hiding either the method or the entry.
3881
+ METHOD_FACTORIES.Child = function(accessor)
3882
+ return function(key: string | number)
3883
+ return accessorIndex(accessor, key, true)
3884
+ end
3885
+ end
3886
+
3887
+ -- Callable shorthand: node() gets, node(value) sets, node(fn) updates.
3888
+ local function accessorCall(accessor: Accessor, ...: any): any
3889
+ local n = select("#", ...)
3890
+ if n == 0 then
3891
+ return accessor.Get()
3892
+ end
3893
+ local first = ...
3894
+ if type(first) == "function" then
3895
+ return accessor.Update(first, select(2, ...))
3896
+ end
3897
+ -- `node(nil, nil)` is what a generalized `for` used to produce before __iter
3898
+ -- existed, and it reaches Set(nil) which deletes the node. A deliberate clear is
3899
+ -- `node.Set(nil)` with one argument; two nils is never intentional.
3900
+ if n == 2 and first == nil and select(2, ...) == nil then
3901
+ error("Scribe: accessor(nil, nil) would delete this node; use Set(nil) if that is what you mean", 2)
3902
+ end
3903
+ return accessor.Set(...)
3904
+ end
3905
+
3906
+ -- Without __iter, a generalized `for` falls back to __call and invokes it as the
3907
+ -- iterator with two nil arguments, which reaches `accessor.Set(nil, nil)` and DELETES
3908
+ -- the node. The loop body never runs, so `for k, v in data.Inventory do` reads as a
3909
+ -- no-op and silently destroys the container, then replicates and persists the deletion.
3910
+ local function accessorIter(): ()
3911
+ error(
3912
+ "Scribe: an accessor is not iterable. Iterate the value instead: "
3913
+ .. "`for key, entry in data.Inventory.Get() do` (read-only) or `.Clone()` for a table you may edit",
3914
+ 2
3915
+ )
3916
+ end
3917
+
3918
+ ACCESSOR_MT = {
3919
+ __index = accessorIndex,
3920
+ __call = accessorCall,
3921
+ __iter = accessorIter,
3922
+ }
3923
+
3924
+ Node.METHOD_NAMES = {} :: { [string]: boolean }
3925
+ for name in METHOD_FACTORIES do
3926
+ Node.METHOD_NAMES[name] = true
3927
+ end
3928
+
3929
+ -- The canonical write set, exported so a guard's spec can iterate it rather than
3930
+ -- hand-list it, and a mutator added later is covered without editing the spec.
3931
+ Node.MUTATOR_METHODS = table.freeze(MUTATOR_METHODS)
3932
+
3933
+ --- The cross-tree transaction refusal, for a writer that bypasses the accessor tree.
3934
+ --- Server/Timed writes the flat `_Scribe.Timed` store directly, so this export is the
3935
+ --- only way it can enforce the same rule with the same sentence.
3936
+ Node.AssertSameTreeWrite = assertSameTreeWrite
3937
+
3938
+ --- The pathKey of an accessor. Exported because the accessor's fields are keyed by
3939
+ --- module-private identities no other module can name.
3940
+ function Node.PathKeyOf(accessor: any): string
3941
+ return rawget(accessor, F_KEY) :: any
3942
+ end
3943
+
3944
+ --- The declared schema behind an accessor.
3945
+ function Node.SchemaOf(accessor: any): SchemaNode?
3946
+ return rawget(accessor, F_SCHEMA) :: any
3947
+ end
3948
+
3949
+ -- Deep-clone a value while unpacking every declared datatype descendant. Exposed for
3950
+ -- the client's Shared mirror, which stores the packed wire form but has no accessor
3951
+ -- tree to convert it on read.
3952
+ Node.CloneUnpack = cloneUnpack
3953
+
3954
+ return Node