@rbxts/scribe 2.5.0 → 2.6.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.
@@ -5,8 +5,7 @@
5
5
  -- Failed transient service-side; a retry may work
6
6
  -- Unresolved timed out and the write may have landed; never retry blindly
7
7
  -- Rejected permanently invalid; every retry fails identically
8
- -- Only the numeric prefix of the error string is read; the prose is not a contract.
9
- -- An unrecognised code classifies as Failed, with the code in the log context.
8
+ -- Classify by numeric code or throttle name; unknown codes default to Failed.
10
9
 
11
10
  local Health = require(script.Parent.Health)
12
11
  local Log = require(script.Parent.Log)
@@ -46,6 +45,12 @@ local function byFamily(code: number): Class
46
45
  return "Failed"
47
46
  end
48
47
 
48
+ -- Strip known engine prefixes before reading the leading code or throttle name.
49
+ local function withoutEnginePrefix(message: string): string
50
+ local rest = string.match(message, "^%s*HTTP %d+ %b()%s*(.*)$") or message
51
+ return string.match(rest, "^%s*DataStoreService:%s*(.*)$") or rest
52
+ end
53
+
49
54
  --- The numeric code a DataStore error message carries, or nil if it carries none.
50
55
  --- Anchored on purpose: a loose search for digits-then-colon would eventually match a
51
56
  --- number inside a key name and report a confident wrong class. nil classifies as
@@ -54,14 +59,43 @@ function Failure.CodeOf(message: any): number?
54
59
  if type(message) ~= "string" then
55
60
  return nil
56
61
  end
57
- return tonumber(string.match(message, "^%s*(%d+):"))
62
+ return tonumber(string.match(withoutEnginePrefix(message), "^%s*(%d+):"))
63
+ end
64
+
65
+ -- Named throttles have no numeric code. Anchor to avoid matching key names.
66
+ function Failure.IsNamedThrottle(message: any): boolean
67
+ if type(message) ~= "string" then
68
+ return false
69
+ end
70
+ return string.match(withoutEnginePrefix(message), "^%s*%a+Throttled?:") ~= nil
71
+ end
72
+
73
+ -- Lowercase markers for backend throttles wrapped in a 502.
74
+ local WRAPPED_THROTTLE_MARKERS = { "http 429", "too many requests", "request rate exceeds" }
75
+
76
+ -- Treat wrapped throttles as throttling for health and kick messages only.
77
+ -- Classify keeps 502 as Failed: gift refunds require proof that nothing was written.
78
+ function Failure.IsThrottleLike(message: any): boolean
79
+ if Failure.Classify(message) == "Throttled" then
80
+ return true
81
+ end
82
+ if Failure.CodeOf(message) ~= 502 then
83
+ return false
84
+ end
85
+ local text = string.lower(message)
86
+ for _, marker in WRAPPED_THROTTLE_MARKERS do
87
+ if string.find(text, marker, 1, true) then
88
+ return true
89
+ end
90
+ end
91
+ return false
58
92
  end
59
93
 
60
94
  --- Classify a DataStore error message.
61
95
  function Failure.Classify(message: any): Class
62
96
  local code = Failure.CodeOf(message)
63
97
  if code == nil then
64
- return "Failed"
98
+ return if Failure.IsNamedThrottle(message) then "Throttled" else "Failed"
65
99
  end
66
100
  return EXPLICIT[code] or byFamily(code)
67
101
  end
@@ -106,7 +140,9 @@ function Failure.Report(report: Report): (Class, boolean)
106
140
  local classified = report.Error ~= nil or report.Class ~= nil
107
141
  local class: Class = report.Class or Failure.Classify(report.Error)
108
142
 
109
- local counted, folded = Health.ReportFailure(report.Subsystem, report.Key, class)
143
+ -- Fold wrapped throttles in health without changing the reported class.
144
+ local healthClass = if class ~= "Throttled" and Failure.IsThrottleLike(report.Error) then "Throttled" else class
145
+ local counted, folded = Health.ReportFailure(report.Subsystem, report.Key, healthClass)
110
146
 
111
147
  local metric = report.Metric
112
148
  if metric ~= nil then
@@ -32,6 +32,8 @@ export type TreeParams = {
32
32
  IsServer: boolean,
33
33
  Label: string,
34
34
  OnOp: ((op: Op, schema: SchemaNode?) -> ())?,
35
+ -- Notify persistence even when replication is disabled.
36
+ OnUnreplicatedOp: ((op: Op, schema: SchemaNode?) -> ())?,
35
37
  OnAnomaly: ((path: { string | number }, value: any, reason: string) -> ())?,
36
38
  BoundsPolicy: ("Clamp" | "Reject")?,
37
39
  DevMode: boolean?,
@@ -74,6 +76,8 @@ export type Tree = typeof(setmetatable(
74
76
  -- The library's handle on the reserved `_Scribe` root: the only accessor
75
77
  -- permitted to write there, and never returned by any public API.
76
78
  Reserved: any,
79
+ -- Private write handle for `_ScribeSession`.
80
+ ReservedSession: any,
77
81
  Dead: boolean,
78
82
  _listeners: { [string]: { [string]: { [any]: (...any) -> () } } },
79
83
  -- Path array per listened pathKey; the pathKey string is lossy and cannot be
@@ -94,10 +98,14 @@ export type Tree = typeof(setmetatable(
94
98
  -- Set only while a failed transaction rolls back: dispatch is queued here and
95
99
  -- drained once the tree is whole again. See `fire` and `rollbackTransaction`.
96
100
  _fireQueue: { { any } }?,
101
+ -- Defer recomputes until rollback finishes restoring the tree.
102
+ _restoring: boolean,
103
+ -- Provisional values carried through a record write; discard if recompute throws.
104
+ _carried: { [SchemaNode]: true }?,
97
105
  _txn: {
98
106
  Snapshots: { [string]: { Path: { string | number }, Value: any } },
99
107
  Below: { [string]: { [string]: boolean } },
100
- Ops: { { Op: Op, Schema: SchemaNode? } },
108
+ Ops: { { Op: Op, Schema: SchemaNode?, Unreplicated: boolean } },
101
109
  Created: { { string | number } },
102
110
  Seeded: { { string | number } },
103
111
  Economy: { { Path: { string | number }, Delta: number, New: number, Tags: { [string]: any } } },
@@ -123,10 +131,8 @@ local F_KEY = {} :: any
123
131
  local F_SCHEMA = {} :: any
124
132
  local F_CHILDREN = {} :: any
125
133
 
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.
134
+ -- Private write capability for both reserved roots. An upvalue prevents rawset forgery;
135
+ -- weak keys let child accessors be collected and rebuilt from privileged parents.
130
136
  local PRIVILEGED: { [any]: true } = setmetatable({}, { __mode = "k" }) :: any
131
137
 
132
138
  -- The ONE tree whose transaction is open right now, or nil. `Tree._txn` is per-tree,
@@ -197,6 +203,7 @@ function Node.NewTree(params: TreeParams): Tree
197
203
  Compiled = params.Compiled,
198
204
  Accessor = nil :: any,
199
205
  Reserved = nil :: any,
206
+ ReservedSession = nil :: any,
200
207
  Dead = false,
201
208
  _listeners = {},
202
209
  _paths = {},
@@ -206,6 +213,8 @@ function Node.NewTree(params: TreeParams): Tree
206
213
  _pendingAncestors = nil,
207
214
  _pendingAncestorOrder = nil,
208
215
  _fireQueue = nil,
216
+ _restoring = false,
217
+ _carried = nil,
209
218
  _txn = nil,
210
219
  _derivedDirty = nil,
211
220
  _derivedSettling = false,
@@ -222,6 +231,12 @@ function Node.NewTree(params: TreeParams): Tree
222
231
  if rootChildren then rootChildren[Template.RESERVED_ROOT] else nil,
223
232
  true
224
233
  )
234
+ self.ReservedSession = newAccessor(
235
+ self,
236
+ { Template.SESSION_ROOT },
237
+ if rootChildren then rootChildren[Template.SESSION_ROOT] else nil,
238
+ true
239
+ )
225
240
  return self
226
241
  end
227
242
 
@@ -504,6 +519,8 @@ local function checkContainerKey(
504
519
  end
505
520
  end
506
521
 
522
+ local markDerivedDirty: (tree: Tree, pathKey: string) -> ()
523
+
507
524
  -- Resolves the container holding path's last segment, materializing missing
508
525
  -- intermediates when `create`. `schema` is the LAST segment's schema; the
509
526
  -- per-segment ones come from walking its Parent chain, which mirrors the path.
@@ -570,10 +587,13 @@ local function resolveContainer(
570
587
  local segHad = container[seg] ~= nil
571
588
  container[seg] = nextContainer
572
589
  noteKeyDelta(container, seg, segHad, true)
590
+ local createdPath = table.move(path, 1, i, 1, table.create(i) :: { string | number })
591
+ -- Recreated records need their previously skipped derived fields recomputed.
592
+ markDerivedDirty(tree, Util.pathKey(createdPath))
573
593
  -- Recorded so a rollback can prune containers that never existed pre-txn.
574
594
  local txn = tree._txn
575
595
  if txn then
576
- txn.Created[#txn.Created + 1] = table.move(path, 1, i, 1, table.create(i) :: { string | number })
596
+ txn.Created[#txn.Created + 1] = createdPath
577
597
  end
578
598
  elseif type(nextContainer) ~= "table" then
579
599
  if not create then
@@ -1396,15 +1416,17 @@ type WriteOpts = {
1396
1416
  }
1397
1417
 
1398
1418
  local function emitOp(tree: Tree, op: Op, schema: SchemaNode?, opts: WriteOpts)
1399
- if opts.NoOp or opts.FromRemote or opts.Replicate == false then
1419
+ if opts.NoOp or opts.FromRemote then
1400
1420
  return
1401
1421
  end
1402
- local onOp = tree.Params.OnOp
1422
+ -- Unreplicated writes still need to mark the profile dirty.
1423
+ local unreplicated = opts.Replicate == false
1424
+ local onOp = if unreplicated then tree.Params.OnUnreplicatedOp else tree.Params.OnOp
1403
1425
  if onOp == nil then
1404
1426
  return
1405
1427
  end
1406
1428
  if tree._txn then
1407
- table.insert(tree._txn.Ops, { Op = op, Schema = schema })
1429
+ table.insert(tree._txn.Ops, { Op = op, Schema = schema, Unreplicated = unreplicated })
1408
1430
  else
1409
1431
  onOp(op, schema)
1410
1432
  end
@@ -1422,7 +1444,7 @@ local MAX_SETTLE_PASSES = 4
1422
1444
  -- Assigned below applyClear: settling writes through applySet.
1423
1445
  local settleDerived: (tree: Tree) -> ()
1424
1446
 
1425
- local function markDerivedDirty(tree: Tree, pathKey: string)
1447
+ markDerivedDirty = function(tree: Tree, pathKey: string)
1426
1448
  local dependents = tree.Compiled.DerivedByWrite[pathKey]
1427
1449
  if dependents == nil then
1428
1450
  return
@@ -1438,9 +1460,7 @@ local function markDerivedDirty(tree: Tree, pathKey: string)
1438
1460
  end
1439
1461
 
1440
1462
  -- 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.
1463
+ -- it: batch flush, transaction commit, ReplayFire, rollbackTransaction or runSettle.
1444
1464
  local function settleAfterWrite(tree: Tree)
1445
1465
  if
1446
1466
  tree._derivedDirty == nil
@@ -1448,6 +1468,7 @@ local function settleAfterWrite(tree: Tree)
1448
1468
  or tree._batchDepth > 0
1449
1469
  or tree._txn ~= nil
1450
1470
  or tree._replaying
1471
+ or tree._restoring
1451
1472
  then
1452
1473
  return
1453
1474
  end
@@ -1766,6 +1787,53 @@ local function canonicalStoredEquals(schema: SchemaNode?, old: any, new: any): b
1766
1787
  return false
1767
1788
  end
1768
1789
 
1790
+ -- Carry derived values through record replacement until recompute. Local writes
1791
+ -- cannot supply them; remote writes and restores fill only gaps. Missing parents stay gone.
1792
+ local function carryDerived(
1793
+ tree: Tree,
1794
+ below: { SchemaNode },
1795
+ depth: number,
1796
+ old: any,
1797
+ new: { [any]: any },
1798
+ overwrite: boolean,
1799
+ remote: boolean
1800
+ )
1801
+ for _, node in below do
1802
+ -- A missing transmitted field is absent on the server; do not fill a stale default.
1803
+ if remote and not (node.Derived :: any).ClientComputes then
1804
+ continue
1805
+ end
1806
+ local out = node.Path
1807
+ local last = #out
1808
+ local parent: any = new
1809
+ for i = depth + 1, last - 1 do
1810
+ parent = parent[out[i]]
1811
+ if type(parent) ~= "table" then
1812
+ break
1813
+ end
1814
+ end
1815
+ if type(parent) == "table" and (overwrite or parent[out[last]] == nil) then
1816
+ local was: any = old
1817
+ for i = depth + 1, last do
1818
+ if type(was) ~= "table" then
1819
+ was = nil
1820
+ break
1821
+ end
1822
+ was = was[out[i]]
1823
+ end
1824
+ parent[out[last]] = was
1825
+ if was ~= nil then
1826
+ local carried = tree._carried
1827
+ if carried == nil then
1828
+ carried = {}
1829
+ tree._carried = carried
1830
+ end
1831
+ (carried :: any)[node] = true
1832
+ end
1833
+ end
1834
+ end
1835
+ end
1836
+
1769
1837
  function applySet(tree: Tree, path: { string | number }, schema: SchemaNode?, value: any, opts: WriteOpts): any
1770
1838
  -- validateWrite rebuilds tables entry-by-entry (no aliasing); unvalidated
1771
1839
  -- table writes are cloned explicitly instead.
@@ -1844,6 +1912,21 @@ function applySet(tree: Tree, path: { string | number }, schema: SchemaNode?, va
1844
1912
  end
1845
1913
 
1846
1914
  local pathKey = Util.pathKey(path)
1915
+ -- Carry before emitOp so transmitted fields travel with the record.
1916
+ if type(newValue) == "table" then
1917
+ local below = tree.Compiled.DerivedBelow[pathKey]
1918
+ if below ~= nil then
1919
+ carryDerived(
1920
+ tree,
1921
+ below,
1922
+ #path,
1923
+ old,
1924
+ newValue,
1925
+ not opts.NoValidate and not opts.FromRemote,
1926
+ opts.FromRemote == true
1927
+ )
1928
+ end
1929
+ end
1847
1930
  -- After the no-op early-out, so an unchanged write never triggers a recompute,
1848
1931
  -- and before the fires, so a listener reading a derived field sees it settled.
1849
1932
  markDerivedDirty(tree, pathKey)
@@ -2139,15 +2222,52 @@ local function applyClear(tree: Tree, path: { string | number }, schema: SchemaN
2139
2222
  noteKeyDelta(container, key, false, true)
2140
2223
  end
2141
2224
  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.
2225
+ -- Clear can remove derived inputs and outputs from static records too.
2144
2226
  markDerivedDirty(tree, pathKey)
2145
2227
  snapshotForTxn(tree, path, pathKey, value)
2146
2228
  local descendantOlds = snapshotDescendants(tree, pathKey)
2229
+ -- Keep direct derived fields until recompute; nested records stay cleared.
2230
+ -- Alternating node/value pairs.
2231
+ local kept: { any }? = nil
2232
+ local below = tree.Compiled.DerivedBelow[pathKey]
2233
+ if below ~= nil then
2234
+ local depth = #path + 1
2235
+ for _, node in below do
2236
+ local was = if #node.Path == depth then value[node.Path[depth]] else nil
2237
+ if was ~= nil then
2238
+ local list = kept or {}
2239
+ kept = list
2240
+ list[#list + 1] = node
2241
+ list[#list + 1] = was
2242
+ end
2243
+ end
2244
+ end
2147
2245
  table.clear(value)
2148
2246
  noteContainerCleared(value)
2247
+ if kept ~= nil then
2248
+ local carried = tree._carried
2249
+ if carried == nil then
2250
+ carried = {}
2251
+ tree._carried = carried
2252
+ end
2253
+ for i = 1, #kept, 2 do
2254
+ local name = kept[i].Path[#path + 1]
2255
+ value[name] = kept[i + 1]
2256
+ noteKeyDelta(value, name, false, true);
2257
+ (carried :: any)[kept[i]] = true
2258
+ end
2259
+ end
2149
2260
 
2150
2261
  emitOp(tree, { Kind = "Clear", Path = table.clone(path) }, schema, opts)
2262
+ if kept ~= nil then
2263
+ -- Shared mirrors lost these fields to Clear; resend server-computed values.
2264
+ for i = 1, #kept, 2 do
2265
+ local node = kept[i]
2266
+ if (node.Derived :: any).Transmit then
2267
+ emitOp(tree, { Kind = "Set", Path = table.clone(node.Path) :: any, Value = kept[i + 1] }, node, opts)
2268
+ end
2269
+ end
2270
+ end
2151
2271
  -- Bulk semantics: the parent Changed fires once and per-entry key events do not. A
2152
2272
  -- descendant leaf listener is not a per-entry event: its value really did change.
2153
2273
  -- Descendants come BEFORE the container's own state, the only order both paths can
@@ -2180,6 +2300,16 @@ local function runSettle(tree: Tree)
2180
2300
  for _, node in ordered do
2181
2301
  if dirty[node] then
2182
2302
  dirty[node] = nil
2303
+ -- Recompute must not recreate a removed parent record.
2304
+ local carried = tree._carried
2305
+ local wasCarried = carried ~= nil and (carried :: any)[node] == true
2306
+ if wasCarried then
2307
+ (carried :: any)[node] = nil
2308
+ end
2309
+ local outPath = node.Path
2310
+ if #outPath > 1 and type(readValue(tree, table.move(outPath, 1, #outPath - 1, 1, {}))) ~= "table" then
2311
+ continue
2312
+ end
2183
2313
  local spec = node.Derived :: any
2184
2314
  local inputs = spec.Inputs
2185
2315
  local count = #inputs
@@ -2200,6 +2330,12 @@ local function runSettle(tree: Tree)
2200
2330
  Replicate = spec.Transmit or devMode,
2201
2331
  })
2202
2332
  else
2333
+ if wasCarried then
2334
+ -- Carried values may be uncomputed snapshot defaults; discard on failure.
2335
+ applySet(tree, node.Path :: any, node, nil, {
2336
+ Replicate = spec.Transmit or devMode,
2337
+ })
2338
+ end
2203
2339
  Metrics.Add("DerivedErrors")
2204
2340
  -- Never rethrow: a Set on an input must not fail because a compute
2205
2341
  -- function has a typo. Logged once per field per tree, or the throw
@@ -2511,9 +2647,21 @@ local function rollbackTransaction(self: Tree, txn: any)
2511
2647
  for i = dynStart, #snapshot.Path do
2512
2648
  exactSchema = if exactSchema then Template.ChildSchema(exactSchema, snapshot.Path[i]) else nil
2513
2649
  end
2650
+ local derived = if exactSchema then exactSchema.Derived else nil
2514
2651
  applySet(self, snapshot.Path, exactSchema, snapshot.Value, {
2515
2652
  NoValidate = true,
2653
+ -- Restore derived fields with the same replication rule as recompute.
2654
+ Replicate = if derived then derived.Transmit or self.Params.DevMode == true else nil,
2516
2655
  })
2656
+ if derived and exactSchema then
2657
+ -- A settle inside the transaction may have consumed an earlier dirty mark.
2658
+ local dirty = self._derivedDirty
2659
+ if dirty == nil then
2660
+ dirty = {}
2661
+ self._derivedDirty = dirty
2662
+ end
2663
+ (dirty :: any)[exactSchema] = true
2664
+ end
2517
2665
  end
2518
2666
  -- Restore raw store writes that bypassed applySet; a nil pre-txn value restores
2519
2667
  -- by removing the key.
@@ -2563,9 +2711,7 @@ local function rollbackTransaction(self: Tree, txn: any)
2563
2711
  end
2564
2712
  end
2565
2713
  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.
2714
+ -- Recompute once from the restored tree, including marks left by no-op restores.
2569
2715
  settleDerived(self)
2570
2716
  end
2571
2717
 
@@ -2647,9 +2793,11 @@ function Tree.RunTransaction(
2647
2793
 
2648
2794
  if ok then
2649
2795
  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)
2796
+ local onUnreplicatedOp: ((op: Op, schema: SchemaNode?) -> ())? = self.Params.OnUnreplicatedOp
2797
+ for _, entry in txn.Ops :: { { Op: Op, Schema: SchemaNode?, Unreplicated: boolean } } do
2798
+ local callback = if entry.Unreplicated then onUnreplicatedOp else onOp
2799
+ if callback then
2800
+ callback(entry.Op, entry.Schema)
2653
2801
  end
2654
2802
  end
2655
2803
  local onEconomy: ((path: { string | number }, delta: number, newValue: number, tags: { [string]: any }) -> ())? =
@@ -2687,7 +2835,10 @@ function Tree.RunTransaction(
2687
2835
  -- the listener that wrote it.
2688
2836
  local queue: { { any } } = {}
2689
2837
  self._fireQueue = queue
2838
+ self._restoring = true
2690
2839
  local rolledBack, rollbackErr = pcall(rollbackTransaction, self, txn)
2840
+ -- Resume normal recomputes even if rollback threw.
2841
+ self._restoring = false
2691
2842
  self._fireQueue = nil
2692
2843
  for _, entry in queue do
2693
2844
  local args = entry[3]
@@ -2899,12 +3050,77 @@ local function cloneUnpack(schema: SchemaNode?, value: any): any
2899
3050
  return out
2900
3051
  end
2901
3052
 
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.
3053
+ -- Guard the written path, including children named by Remove(key).
3054
+ -- `level` points to the caller's frame.
3055
+ local function refuseWrite(
3056
+ tree: Tree,
3057
+ path: { string | number },
3058
+ schema: SchemaNode?,
3059
+ privileged: boolean,
3060
+ level: number
3061
+ )
3062
+ -- Only Tree.Reserved may write the ledger; ServerOnly alone does not protect it.
3063
+ if path[1] == Template.RESERVED_ROOT and not privileged then
3064
+ error(
3065
+ `Scribe: "{Util.pathString(path)}" is inside the reserved "{Template.RESERVED_ROOT}" root `
3066
+ .. `and cannot be written; it is Scribe's own ledger -- processed receipt ids, perks, `
3067
+ .. `gift credits, pending gifts, purchase logs, timers and the schema version. Read it `
3068
+ .. `with the typed readers (Owns, GetGiftCredits, GetPurchases) and change it through `
3069
+ .. `the APIs that own it (GrantPerk, RevokePerk, Purchase, PromptGift)`,
3070
+ level
3071
+ )
3072
+ end
3073
+ -- Protect the ownership cache, save info and timers too.
3074
+ if path[1] == Template.SESSION_ROOT and not privileged then
3075
+ error(
3076
+ `Scribe: "{Util.pathString(path)}" is inside the reserved "{Template.SESSION_ROOT}" root `
3077
+ .. `and cannot be written; it is Scribe's per-session state -- the pass ownership cache, `
3078
+ .. `the save info and the timers. Read it with Owns, OwnsAsync and GetSaveInfo`,
3079
+ level
3080
+ )
3081
+ end
3082
+ -- Both views share the client's tree, so foreign-root writes would corrupt it.
3083
+ local root = path[1]
3084
+ local foreign = tree.Compiled.ForeignRoots
3085
+ if foreign ~= nil and type(root) == "string" and foreign[root] then
3086
+ if tree.Params.IsServerStore then
3087
+ error(
3088
+ `Scribe: "{Util.pathString(path)}" is inside the per-player root "{root}" and cannot be `
3089
+ .. `written on the ServerStore; store writes reach every client, so this one would `
3090
+ .. `overwrite each player's own copy. Write it on that player's data instead`,
3091
+ level
3092
+ )
3093
+ end
3094
+ error(
3095
+ `Scribe: "{Util.pathString(path)}" is inside the ServerStore root "{root}" and cannot be `
3096
+ .. `written on a player's data; each client keeps the store and its own data in one `
3097
+ .. `tree, so the write would overwrite that player's copy of the store. Write the store `
3098
+ .. `through Data.ServerStore.{root}, and remove a "{root}" key an earlier version saved `
3099
+ .. `into a profile with a migration`,
3100
+ level
3101
+ )
3102
+ end
3103
+ local derived = if schema then schema.Derived else nil
3104
+ if derived then
3105
+ local inputs = table.create(#derived.InputPaths)
3106
+ for i, segments in derived.InputPaths do
3107
+ inputs[i] = table.concat(segments, ".")
3108
+ end
3109
+ error(
3110
+ `Scribe: "{Util.pathString(path)}" is a derived field and cannot be written; `
3111
+ .. `it is computed from {table.concat(inputs, ", ")}`,
3112
+ level
3113
+ )
3114
+ end
3115
+ end
3116
+
3117
+ local function isReservedRoot(key: any): boolean
3118
+ return key == Template.RESERVED_ROOT or key == Template.SESSION_ROOT
3119
+ end
3120
+
3121
+ -- Public reserved-root reads must return copies. Fixed for an accessor's lifetime.
2906
3122
  local function isPublicReserved(accessor: Accessor): boolean
2907
- return accessorPath(accessor)[1] == Template.RESERVED_ROOT and not PRIVILEGED[accessor]
3123
+ return isReservedRoot(accessorPath(accessor)[1]) and not PRIVILEGED[accessor]
2908
3124
  end
2909
3125
 
2910
3126
  -- The independent copy Clone() hands back: unpack-and-deep-clone when anything below
@@ -3071,10 +3287,17 @@ METHOD_FACTORIES.Set = function(accessor)
3071
3287
  end
3072
3288
  end
3073
3289
 
3290
+ -- Reject before calling the callback: the root read exposes the live saved table.
3291
+ local ROOT_UPDATE_REFUSAL = "Scribe: Update cannot be called on the root of the data: it would hand your "
3292
+ .. "function the saved table itself. Call Update on one of its fields"
3293
+
3074
3294
  METHOD_FACTORIES.Update = function(accessor)
3075
3295
  return function(fn: (any) -> any, replicate: boolean?)
3076
3296
  local tree = accessorTree(accessor)
3077
3297
  assertAlive(tree)
3298
+ if #accessorPath(accessor) == 0 then
3299
+ error(ROOT_UPDATE_REFUSAL, 2)
3300
+ end
3078
3301
  local schema = accessorSchema(accessor)
3079
3302
  local current = unpackRead(schema, readValue(tree, accessorPath(accessor)))
3080
3303
  local stored = applySet(tree, accessorPath(accessor), schema, fn(current), { Replicate = replicate })
@@ -3542,6 +3765,8 @@ METHOD_FACTORIES.Remove = function(accessor)
3542
3765
  table.insert(path, posOrKey)
3543
3766
  local schema = accessorSchema(accessor)
3544
3767
  local childSchema = if schema then Template.ChildSchema(schema, posOrKey) else nil
3768
+ -- accessorIndex checked the parent; Remove must guard the child too.
3769
+ refuseWrite(tree, path, childSchema, PRIVILEGED[accessor] == true, 3)
3545
3770
  local container, key = resolveContainer(tree, path, false)
3546
3771
  local old = if container then container[key] else nil
3547
3772
  if old ~= nil then
@@ -3647,11 +3872,7 @@ end
3647
3872
  for _, event in { "OnInsert", "OnRemove", "OnKeyAdded", "OnKeyRemoved", "OnChildChanged" } do
3648
3873
  METHOD_FACTORIES[event] = function(accessor)
3649
3874
  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.
3875
+ -- Root child events also need copies when they carry a reserved root.
3655
3876
  local rootGuard = #accessorPath(accessor) == 0 and not PRIVILEGED[accessor]
3656
3877
  return function(fn: (...any) -> ())
3657
3878
  local tree = accessorTree(accessor)
@@ -3669,7 +3890,7 @@ for _, event in { "OnInsert", "OnRemove", "OnKeyAdded", "OnKeyRemoved", "OnChild
3669
3890
  -- disappearance has no successor.
3670
3891
  wrapped = function(key: any, newValue: any, oldValue: any)
3671
3892
  local childSchema = if schema then Template.ChildSchema(schema, key) else nil
3672
- local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
3893
+ local g = guarded or (rootGuard and isReservedRoot(key))
3673
3894
  inner(
3674
3895
  key,
3675
3896
  entryValueForListener(g, childSchema, newValue),
@@ -3683,7 +3904,7 @@ for _, event in { "OnInsert", "OnRemove", "OnKeyAdded", "OnKeyRemoved", "OnChild
3683
3904
  -- created with the tree and never appears or disappears
3684
3905
  -- (RootChildLedgerGuard.spec pins that), but kept so the sibling wrappers
3685
3906
  -- do not differ for no reason.
3686
- local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
3907
+ local g = guarded or (rootGuard and isReservedRoot(key))
3687
3908
  inner(key, entryValueForListener(g, childSchema, value))
3688
3909
  end
3689
3910
  end
@@ -3774,35 +3995,13 @@ local function accessorIndex(accessor: Accessor, key: any, childOnly: boolean?):
3774
3995
  if OPEN_TXN_TREE ~= nil then
3775
3996
  assertSameTreeWrite(accessorTree(accessor), Util.pathString(accessorPath(accessor)), 3)
3776
3997
  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
3998
+ refuseWrite(
3999
+ accessorTree(accessor),
4000
+ accessorPath(accessor),
4001
+ accessorSchema(accessor),
4002
+ PRIVILEGED[accessor] == true,
4003
+ 3
4004
+ )
3806
4005
  -- Cached under a module-private identity rather than under `key`, so every
3807
4006
  -- `x.Set` keeps going through __index and past the guards. A plain rawset under
3808
4007
  -- `key`, as the non-mutator branch below does, would be satisfied off the
@@ -3892,6 +4091,9 @@ local function accessorCall(accessor: Accessor, ...: any): any
3892
4091
  end
3893
4092
  local first = ...
3894
4093
  if type(first) == "function" then
4094
+ if #accessorPath(accessor) == 0 then
4095
+ error(ROOT_UPDATE_REFUSAL, 2)
4096
+ end
3895
4097
  return accessor.Update(first, select(2, ...))
3896
4098
  end
3897
4099
  -- `node(nil, nil)` is what a generalized `for` used to produce before __iter
@@ -384,6 +384,8 @@ local JobId = game.JobId
384
384
 
385
385
  local AutoSaveIndex = 1 -- Next profile to auto save
386
386
  local LastAutoSave = os.clock()
387
+ -- SCRIBE PATCH: last liveness sweep.
388
+ local LastLivenessSweep = os.clock()
387
389
 
388
390
  local LoadIndex = 0
389
391
 
@@ -831,6 +833,9 @@ local function SaveProfileAsync(profile, is_ending_session, is_overwriting, last
831
833
  error(`[{script.Name}]: Developer code likely set "Profile.Data" to a non-table value! (STORE:{profile.ProfileStore.Name}; KEY:{profile.Key})`)
832
834
  end
833
835
 
836
+ -- SCRIBE PATCH: track all save attempts for the liveness sweep.
837
+ profile.scribe_save_started = os.clock()
838
+
834
839
  -- SCRIBE PATCH: a context owned by THIS call, handed to OnSave and returned to
835
840
  -- the caller, so a handler can record something about the save it is running
836
841
  -- inside. Anything stored on `entry` instead would be a single slot shared by
@@ -2928,6 +2933,22 @@ RunService.Heartbeat:Connect(function()
2928
2933
  end
2929
2934
  end
2930
2935
 
2936
+ -- SCRIBE PATCH: departures can stretch the rotation past ASSUME_DEAD. Bound each
2937
+ -- profile's save gap, leaving time for one retry before its session looks dead.
2938
+ local liveness_clock = os.clock()
2939
+ if liveness_clock - LastLivenessSweep >= 1 and ProfileStore.IsClosing == false then
2940
+ LastLivenessSweep = liveness_clock
2941
+ local cap = math.min(AUTO_SAVE_PERIOD, ASSUME_DEAD / 2)
2942
+ for _, profile in ipairs(table.clone(AutoSaveList)) do
2943
+ -- Earlier save handlers may have ended another session in this sweep.
2944
+ if liveness_clock - (profile.scribe_save_started or profile.load_timestamp) >= cap and profile:IsActive() then
2945
+ RemoveProfileFromAutoSave(profile)
2946
+ AddProfileToAutoSave(profile)
2947
+ task.spawn(SaveProfileAsync, profile)
2948
+ end
2949
+ end
2950
+ end
2951
+
2931
2952
  -- Critical state handling:
2932
2953
 
2933
2954
  if ProfileStore.IsCriticalState == false then