@rbxts/scribe 2.5.0 → 2.6.1

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.
@@ -82,6 +82,7 @@ export type SchemaNode = {
82
82
  InputPaths: { { string } },
83
83
  Compute: (...any) -> any,
84
84
  Transmit: boolean, -- server computes and REPLICATES (an input the audience cannot see)
85
+ ClientComputes: boolean, -- field and inputs are visible to the client
85
86
  OfflineComputable: boolean, -- root-level, and every input persists
86
87
  Label: string,
87
88
  }?,
@@ -128,12 +129,16 @@ export type Compiled = {
128
129
  HasShared: boolean,
129
130
  DynamicNodes: { SchemaNode }, -- fields with a Scribe.Dynamic factory, in id order
130
131
  DerivedNodes: { SchemaNode }, -- Scribe.Derived fields in topological order
131
- -- pathKey of an input (or any ancestor of one) -> the fields to recompute. A
132
- -- write looks up its own pathKey and finds every dependent in one hop.
132
+ -- Written pathKey -> fields to recompute, including record replacements.
133
133
  DerivedByWrite: { [string]: { SchemaNode } },
134
- -- Root views. Player is the compiled itself when no store is declared; views share
135
- -- everything but Root, RootOrder and HasShared by reference.
134
+ -- Ancestor pathKey -> derived fields to carry across record replacements.
135
+ -- Includes transmitted fields on the client.
136
+ DerivedBelow: { [string]: { SchemaNode } },
137
+ -- Views scope roots and derived indexes; everything else is shared.
138
+ -- Without a store, Player is the full compile.
136
139
  Views: { Player: Compiled, Store: Compiled? },
140
+ -- Other view's roots, forbidden for writes. Nil on the full compile.
141
+ ForeignRoots: { [string]: boolean }?,
137
142
  Config: CompileConfig,
138
143
  }
139
144
 
@@ -1185,6 +1190,41 @@ function Template.CoerceMapKeys(compiled: Compiled, data: any)
1185
1190
  walk(compiled.Root, data, 0)
1186
1191
  end
1187
1192
 
1193
+ -- Copy and filter the index; empty entries would still trigger a settle.
1194
+ local function scopeIndex(
1195
+ index: { [string]: { SchemaNode } },
1196
+ keep: (SchemaNode) -> boolean
1197
+ ): { [string]: { SchemaNode } }
1198
+ local keptIndex: { [string]: { SchemaNode } } = {}
1199
+ for pathKey, nodes in index do
1200
+ local kept: { SchemaNode } = {}
1201
+ for _, node in nodes do
1202
+ if keep(node) then
1203
+ table.insert(kept, node)
1204
+ end
1205
+ end
1206
+ if #kept > 0 then
1207
+ keptIndex[pathKey] = kept
1208
+ end
1209
+ end
1210
+ return keptIndex
1211
+ end
1212
+
1213
+ -- Preserve topological order without mutating the shared compile.
1214
+ local function scopeDerived(
1215
+ nodes: { SchemaNode },
1216
+ byWrite: { [string]: { SchemaNode } },
1217
+ keep: (SchemaNode) -> boolean
1218
+ ): ({ SchemaNode }, { [string]: { SchemaNode } })
1219
+ local keptNodes: { SchemaNode } = {}
1220
+ for _, node in nodes do
1221
+ if keep(node) then
1222
+ table.insert(keptNodes, node)
1223
+ end
1224
+ end
1225
+ return keptNodes, scopeIndex(byWrite, keep)
1226
+ end
1227
+
1188
1228
  function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1189
1229
  local cfg: CompileConfig = config or {}
1190
1230
  if type(userTemplate) ~= "table" then
@@ -1356,9 +1396,10 @@ function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1356
1396
  -- Before the hash fold, which folds the result.
1357
1397
  local derivedNodes: { SchemaNode } = {}
1358
1398
  local derivedByWrite: { [string]: { SchemaNode } } = {}
1399
+ local derivedBelow: { [string]: { SchemaNode } } = {}
1359
1400
  if #pendingDerived > 0 then
1360
1401
  local reservedRoots = { [RESERVED_ROOT] = true, [SESSION_ROOT] = true }
1361
- derivedNodes, derivedByWrite =
1402
+ derivedNodes, derivedByWrite, derivedBelow =
1362
1403
  DerivedModule.Resolve(root, pendingDerived :: any, reservedRoots, compileError :: any)
1363
1404
  DerivedModule.SeedDefaults(derivedNodes :: any, compileError :: any)
1364
1405
 
@@ -1550,13 +1591,12 @@ function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1550
1591
  DynamicNodes = dynamicNodes,
1551
1592
  DerivedNodes = derivedNodes,
1552
1593
  DerivedByWrite = derivedByWrite,
1594
+ DerivedBelow = derivedBelow,
1553
1595
  Views = nil :: any,
1554
1596
  Config = cfg,
1555
1597
  }
1556
1598
 
1557
- -- A view is the compiled with its root scoped to a subset of the children. Node reads
1558
- -- only Root, DerivedByWrite, DerivedNodes and Template.Resolve, so this costs nothing
1559
- -- in Node itself.
1599
+ -- Scope each tree's roots and derived indexes without copying the full schema.
1560
1600
  local function makeView(keys: { string }): Compiled
1561
1601
  local viewChildren: { [string]: SchemaNode } = {}
1562
1602
  local viewOrdinal: { [string]: number } = {}
@@ -1580,6 +1620,22 @@ function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1580
1620
  view.Root = viewRoot
1581
1621
  view.RootOrder = keys
1582
1622
  view.HasShared = viewShared
1623
+
1624
+ -- Each tree computes only its own fields; cross-view inputs are already rejected.
1625
+ local function onViewRoot(node: SchemaNode): boolean
1626
+ return viewChildren[node.Path[1]] ~= nil
1627
+ end
1628
+ view.DerivedNodes, view.DerivedByWrite = scopeDerived(derivedNodes, derivedByWrite, onViewRoot)
1629
+ view.DerivedBelow = scopeIndex(derivedBelow, onViewRoot)
1630
+
1631
+ -- Clients share one tree, so foreign-root writes would overwrite the other store.
1632
+ local foreign: { [string]: boolean } = {}
1633
+ for key in children do
1634
+ if viewChildren[key] == nil then
1635
+ foreign[key] = true
1636
+ end
1637
+ end
1638
+ view.ForeignRoots = table.freeze(foreign)
1583
1639
  return view
1584
1640
  end
1585
1641
 
@@ -1599,6 +1655,20 @@ function Template.Compile(userTemplate: any, config: CompileConfig?): Compiled
1599
1655
  return compiled
1600
1656
  end
1601
1657
 
1658
+ -- Recompute only client-visible fields. Keep DerivedBelow for carrying transmitted
1659
+ -- values across record writes. Edit mode uses the full compile for Data.Mock.
1660
+ function Template.ClientView(compiled: Compiled): Compiled
1661
+ local view: Compiled = table.clone(compiled)
1662
+ view.DerivedNodes, view.DerivedByWrite = scopeDerived(
1663
+ compiled.DerivedNodes,
1664
+ compiled.DerivedByWrite,
1665
+ function(node: SchemaNode): boolean
1666
+ return (node.Derived :: any).ClientComputes == true
1667
+ end
1668
+ )
1669
+ return view
1670
+ end
1671
+
1602
1672
  -- Shared with Node, whose read paths all have to agree on which nodes need an unpack.
1603
1673
  function Template.IsPacked(node: SchemaNode?): boolean
1604
1674
  return node ~= nil and isPacked(node)
@@ -1665,6 +1735,24 @@ function Template.VisibilityOf(compiled: Compiled, path: { string | number }): V
1665
1735
  return node.Visibility
1666
1736
  end
1667
1737
 
1738
+ -- Insert/Remove must not expose server-only element values or indices.
1739
+ function Template.OpVisibility(
1740
+ compiled: Compiled,
1741
+ op: { Kind: string, Path: { string | number } },
1742
+ schema: SchemaNode?
1743
+ ): Visibility
1744
+ if schema == nil then
1745
+ return Template.VisibilityOf(compiled, op.Path)
1746
+ end
1747
+ if op.Kind == "Insert" or op.Kind == "Remove" then
1748
+ local element = Template.ChildSchema(schema, 1)
1749
+ if element ~= nil and element.Visibility == "ServerOnly" then
1750
+ return "ServerOnly"
1751
+ end
1752
+ end
1753
+ return schema.Visibility
1754
+ end
1755
+
1668
1756
  -- The persistence axis, for callers that only have a path. Separate from
1669
1757
  -- VisibilityOf because a field can be Session (never saves) AND ServerOnly or
1670
1758
  -- Shared (who receives it) at the same time.
@@ -1,4 +1,4 @@
1
1
  --!strict
2
2
  -- Single source of truth for the release version. Keep wally.toml in sync.
3
3
 
4
- return "2.5.0"
4
+ return "2.6.1"
@@ -78,10 +78,13 @@ function Commands.new(ctx: any)
78
78
  local self = {} :: any
79
79
  local options = ctx.Options
80
80
  local rateLimit: number = options.CommandRateLimit or 20
81
+ local requestTimeout: number = tonumber(options.RequestTimeout) or 10
81
82
  -- How long a settled idempotency record answers repeats. Derived rather than
82
83
  -- configured: the window only has to outlast the client's own retry window, which
83
84
  -- RequestTimeout defines. The floor keeps a short RequestTimeout from undercutting it.
84
- local idempotencyTTL: number = math.max(120, (tonumber(options.RequestTimeout) or 10) * 4)
85
+ local idempotencyTTL: number = math.max(120, requestTimeout * 4)
86
+ -- Leave half the request window for transport and snapshot delivery.
87
+ local holdBudget: number = requestTimeout / 2
85
88
 
86
89
  local registry: { [string]: Registered } = {}
87
90
  -- The longest name any command is registered under, floored so an ordinary typo still
@@ -225,8 +228,13 @@ function Commands.new(ctx: any)
225
228
  return Wire.Finish(w)
226
229
  end
227
230
 
228
- -- Send one reply frame; returns the bytes sent.
229
- local function reply(entry: any, correlation: number, ok: boolean, results: { any }): buffer
231
+ --- Encodes the refusal for a connected player whose session ended.
232
+ function self.EncodeNotReady(correlation: number): buffer
233
+ return encodeReply(correlation, false, { "not-ready" })
234
+ end
235
+
236
+ -- Returns encoded bytes. Handler replies may wait for a repair until holdUntil.
237
+ local function reply(entry: any, correlation: number, ok: boolean, results: { any }, holdUntil: number?): buffer
230
238
  -- encodeReply clamps to MAX_RETURNS, and the caller just sees trailing nils, so
231
239
  -- say so. Only meaningful on success; failure replies are single-value.
232
240
  local resultCount = (results :: any).n or #results
@@ -245,16 +253,20 @@ function Commands.new(ctx: any)
245
253
  Log.Warn("Commands", "COMMAND_REPLY_ENCODE_FAIL", tostring(bytes), { Player = entry.Player })
246
254
  bytes = encodeReply(correlation, false, { "reply-encode-failed" })
247
255
  end
248
- ctx.Replication.SendTo(entry, bytes)
256
+ if holdUntil ~= nil then
257
+ ctx.Replication.SendReply(entry, bytes, holdUntil)
258
+ else
259
+ ctx.Replication.SendTo(entry, bytes)
260
+ end
249
261
  return bytes
250
262
  end
251
263
 
252
- -- A copy of a settled reply with the header's correlation overwritten.
253
- local function replay(entry: any, correlation: number, bytes: buffer)
264
+ -- Replays a settled reply with this request's correlation and repair deadline.
265
+ local function replay(entry: any, correlation: number, bytes: buffer, holdUntil: number)
254
266
  local copy = buffer.create(buffer.len(bytes))
255
267
  buffer.copy(copy, 0, bytes)
256
268
  buffer.writeu32(copy, 1, correlation)
257
- ctx.Replication.SendTo(entry, copy)
269
+ ctx.Replication.SendReply(entry, copy, holdUntil)
258
270
  end
259
271
 
260
272
  -- Idempotency cache --------------------------------------------------------
@@ -277,7 +289,7 @@ function Commands.new(ctx: any)
277
289
 
278
290
  -- Finish an in-flight record: answer every duplicate parked on it, and decide
279
291
  -- whether it survives to answer later retries.
280
- local function settleIdempotent(entry: any, record: IdemRecord?, ok: boolean, bytes: buffer)
292
+ local function settleIdempotent(entry: any, record: IdemRecord?, ok: boolean, bytes: buffer, holdUntil: number)
281
293
  if record == nil then
282
294
  return
283
295
  end
@@ -296,7 +308,7 @@ function Commands.new(ctx: any)
296
308
  end
297
309
  end
298
310
  for _, correlation in waiters do
299
- replay(entry, correlation, bytes)
311
+ replay(entry, correlation, bytes, holdUntil)
300
312
  end
301
313
  end
302
314
 
@@ -622,7 +634,8 @@ function Commands.new(ctx: any)
622
634
  if existing ~= nil then
623
635
  if existing.Done then
624
636
  Metrics.Add("CommandsDeduped")
625
- replay(entry, correlation, existing.Reply :: buffer)
637
+ -- A repair snapshot also carries the cached handler's writes.
638
+ replay(entry, correlation, existing.Reply :: buffer, now + holdBudget)
626
639
  elseif #existing.Waiters < MAX_IDEMPOTENT_WAITERS then
627
640
  -- Still running, so park this correlation on it; settleIdempotent
628
641
  -- answers every duplicate when the handler returns.
@@ -687,6 +700,7 @@ function Commands.new(ctx: any)
687
700
  local active = (activeByName[name] or 0) + 1
688
701
  activeByName[name] = active
689
702
  Metrics.Set(registered.ActiveMetric, active)
703
+ local storeMark = ctx.Replication.StoreOpsQueued()
690
704
  local startedAt = Clock.Monotonic()
691
705
  local ok, err = xpcall(function()
692
706
  results = table.pack(registered.Handler(entry.Player, table.unpack(args, 1, argc))) :: any
@@ -698,6 +712,14 @@ function Commands.new(ctx: any)
698
712
  active = activeByName[name] - 1
699
713
  activeByName[name] = active
700
714
  Metrics.Set(registered.ActiveMetric, active)
715
+ -- Send owner writes before the reply, even on error. Shared writes still batch.
716
+ ctx.Replication.FlushOwnerQueue(entry)
717
+ -- Broadcast early only if store writes were queued during this handler.
718
+ if ctx.Replication.StoreOpsQueued() ~= storeMark then
719
+ ctx.Replication.FlushStoreQueue()
720
+ end
721
+ -- A repair carries writes from a closed queue; handler time counts toward its wait.
722
+ local holdUntil = startedAt + holdBudget
701
723
  if not ok then
702
724
  Metrics.Add("CommandErrors")
703
725
  Metrics.Add(registered.ErrorMetric)
@@ -715,11 +737,11 @@ function Commands.new(ctx: any)
715
737
  Suppressed = if suppressed > 0 then suppressed else nil,
716
738
  })
717
739
  end
718
- settleIdempotent(entry, record, false, reply(entry, correlation, false, { "error" }))
740
+ settleIdempotent(entry, record, false, reply(entry, correlation, false, { "error" }, holdUntil), holdUntil)
719
741
  return
720
742
  end
721
743
  Metrics.Add("CommandsHandled")
722
- settleIdempotent(entry, record, true, reply(entry, correlation, true, results))
744
+ settleIdempotent(entry, record, true, reply(entry, correlation, true, results, holdUntil), holdUntil)
723
745
  end
724
746
 
725
747
  return self
@@ -668,7 +668,7 @@ function DebugHook.Attach(Data: any, ctx: any): (() -> ())?
668
668
  local function accessorAt(entry: any, path: { string | number }): any
669
669
  local accessor = entry.Tree.Accessor
670
670
  for _, seg in path do
671
- accessor = accessor[seg]
671
+ accessor = accessor.Child(seg)
672
672
  end
673
673
  return accessor
674
674
  end
@@ -346,7 +346,7 @@ function Leaderboards.new(ctx: any)
346
346
  if write ~= nil and commit then
347
347
  local tree = entry.Tree
348
348
  if tree ~= nil and not tree.Dead then
349
- tree.Reserved.Boards[board.Name].Set(write)
349
+ tree.Reserved.Boards.Child(board.Name).Set(write)
350
350
  else
351
351
  records[board.Name] = write
352
352
  end
@@ -749,7 +749,7 @@ function Leaderboards.new(ctx: any)
749
749
  local ok, value = pcall(function()
750
750
  local accessor = tree.Accessor
751
751
  for _, segment in board.StatPath do
752
- accessor = accessor[segment]
752
+ accessor = accessor.Child(segment)
753
753
  end
754
754
  return accessor.Get()
755
755
  end)
@@ -1741,7 +1741,7 @@ function Leaderboards.new(ctx: any)
1741
1741
  local ok, err = pcall(function()
1742
1742
  local accessor = entry.Tree.Accessor
1743
1743
  for _, segment in board.StatPath do
1744
- accessor = accessor[segment]
1744
+ accessor = accessor.Child(segment)
1745
1745
  end
1746
1746
  local value = accessor.Get()
1747
1747
  if board.IsBig or type(value) == "number" then
@@ -17,6 +17,7 @@ local Clock = require(Internal.Clock)
17
17
  local Sched = require(Internal.Sched)
18
18
  local Rng = require(Internal.Rng)
19
19
  local Failure = require(Internal.Failure)
20
+ local Big = require(Internal.Big)
20
21
  -- For MAX_IDEMPOTENCY_KEY_BYTES only. Wire's own requires are Internal leaves, so
21
22
  -- this adds no module to the bundle and no cycle.
22
23
  local Wire = require(Internal.Wire)
@@ -42,6 +43,8 @@ local PURCHASE_IDEM_PREFIX = "@pi|"
42
43
  -- eviction can let a retry apply a purchase twice (PURCHASE_CLAIM_EVICTED). A game that
43
44
  -- outruns it should shorten PurchaseClaimTTL rather than raise this.
44
45
  local PURCHASE_CLAIM_CAP = 1000
46
+ -- Literal zero always parses.
47
+ local BIG_ZERO = Big.from(0) :: Big.Big
45
48
 
46
49
  function Monetization.new(ctx: any)
47
50
  local self = {} :: any
@@ -320,6 +323,11 @@ function Monetization.new(ctx: any)
320
323
  return entry.Tree.Reserved
321
324
  end
322
325
 
326
+ -- Internal write access to `_ScribeSession`.
327
+ local function sessionAcc(entry: any): any
328
+ return entry.Tree.ReservedSession
329
+ end
330
+
323
331
  local function reservedRaw(data: { [string]: any }): { [string]: any }
324
332
  local reserved = data[Template.RESERVED_ROOT]
325
333
  if type(reserved) ~= "table" then
@@ -799,7 +807,7 @@ function Monetization.new(ctx: any)
799
807
  error("Scribe: GrantPerk requires a Ready player (use Data.WaitForData)", 2)
800
808
  end
801
809
  checkPerkName(key)
802
- reservedAcc(entry).Perks[key].Set(true)
810
+ reservedAcc(entry).Perks.Child(key).Set(true)
803
811
  Log.Info("Monetization", "PERK_GRANTED", `perk "{key}" granted`, { Player = player, Perk = key })
804
812
  end
805
813
 
@@ -808,7 +816,7 @@ function Monetization.new(ctx: any)
808
816
  if not entry or entry.State ~= "Ready" then
809
817
  error("Scribe: RevokePerk requires a Ready player", 2)
810
818
  end
811
- reservedAcc(entry).Perks[key].Set(nil)
819
+ reservedAcc(entry).Perks.Child(key).Set(nil)
812
820
  Log.Info("Monetization", "PERK_REVOKED", `perk "{key}" revoked`, { Player = player, Perk = key })
813
821
  end
814
822
 
@@ -935,7 +943,7 @@ function Monetization.new(ctx: any)
935
943
 
936
944
  local function setOwnsCache(entry: any, key: string, owned: boolean)
937
945
  if entry.Tree and not entry.Tree.Dead then
938
- entry.Tree.Accessor[Template.SESSION_ROOT].OwnsCache[key].Set(if owned then true else nil)
946
+ sessionAcc(entry).OwnsCache.Child(key).Set(if owned then true else nil)
939
947
  end
940
948
  end
941
949
 
@@ -944,7 +952,7 @@ function Monetization.new(ctx: any)
944
952
  if not entry.Tree or entry.Tree.Dead then
945
953
  return owned
946
954
  end
947
- local kept = owned or entry.Tree.Accessor[Template.SESSION_ROOT].OwnsCache[key].Get() == true
955
+ local kept = owned or sessionAcc(entry).OwnsCache.Child(key).Get() == true
948
956
  setOwnsCache(entry, key, kept)
949
957
  return kept
950
958
  end
@@ -1008,17 +1016,14 @@ function Monetization.new(ctx: any)
1008
1016
  if not entry.Tree or entry.Tree.Dead then
1009
1017
  return
1010
1018
  end
1011
- local accessor = entry.Tree.Accessor
1012
1019
  scanOwnership(entry, true) -- baseline: record current state without firing
1013
1020
  local function onChange()
1014
1021
  scanOwnership(entry)
1015
1022
  end
1016
1023
  entry.OwnsWatchers = {
1017
- -- Through the privileged handle, not the public child: a public read hands back
1018
- -- a detached deep copy (readOut in Node.luau), and this callback ignores the
1019
- -- value entirely.
1024
+ -- Avoid public-read copies; the callback ignores the values.
1020
1025
  reservedAcc(entry).Perks.Changed(onChange),
1021
- accessor[Template.SESSION_ROOT].OwnsCache.Changed(onChange),
1026
+ sessionAcc(entry).OwnsCache.Changed(onChange),
1022
1027
  }
1023
1028
  end
1024
1029
 
@@ -1043,10 +1048,9 @@ function Monetization.new(ctx: any)
1043
1048
  Sched.Spawn(callback, owned)
1044
1049
  end
1045
1050
  end
1046
- local accessor = entry.Tree.Accessor
1047
- -- Privileged handle: see the note in watchOwnership.
1051
+ -- Avoid public-read copies, as in watchOwnership.
1048
1052
  local disconnectPerk = reservedAcc(entry).Perks.Changed(push)
1049
- local disconnectCache = accessor[Template.SESSION_ROOT].OwnsCache.Changed(push)
1053
+ local disconnectCache = sessionAcc(entry).OwnsCache.Changed(push)
1050
1054
  push()
1051
1055
  return function()
1052
1056
  disconnectPerk()
@@ -1062,7 +1066,7 @@ function Monetization.new(ctx: any)
1062
1066
  end
1063
1067
  entry.OwnershipReady = true
1064
1068
  if entry.Tree and not entry.Tree.Dead then
1065
- entry.Tree.Accessor[Template.SESSION_ROOT].OwnsSynced.Set(true)
1069
+ sessionAcc(entry).OwnsSynced.Set(true)
1066
1070
  end
1067
1071
  end
1068
1072
 
@@ -1206,7 +1210,7 @@ function Monetization.new(ctx: any)
1206
1210
  end
1207
1211
  if product.Grants then
1208
1212
  checkPerkName(product.Grants)
1209
- reservedAcc(entry).Perks[product.Grants].Set(true)
1213
+ reservedAcc(entry).Perks.Child(product.Grants).Set(true)
1210
1214
  end
1211
1215
  end
1212
1216
 
@@ -1656,7 +1660,7 @@ function Monetization.new(ctx: any)
1656
1660
  convertToCredit = not delivered
1657
1661
  end
1658
1662
  if convertToCredit then
1659
- local creditsAccessor = reservedAcc(entry).GiftCredits[product.Name]
1663
+ local creditsAccessor = reservedAcc(entry).GiftCredits.Child(product.Name)
1660
1664
  creditsAccessor.Set((tonumber(creditsAccessor.Get()) or 0) + 1)
1661
1665
  -- Receipt retries may outlive their original product slot.
1662
1666
  clearGiftRecord(entry, productIdStr, giftId)
@@ -1836,7 +1840,7 @@ function Monetization.new(ctx: any)
1836
1840
  -- GrantOrCredit: a no-op grant would burn Robux, so write a durable gift credit.
1837
1841
  -- A no-intent purchase never stacks onto a pending credit (declined above), but
1838
1842
  -- an aimed-gift conversion in handleGiftReceipt may, since that money is taken.
1839
- local creditsAccessor = reservedAcc(entry).GiftCredits[product.Name]
1843
+ local creditsAccessor = reservedAcc(entry).GiftCredits.Child(product.Name)
1840
1844
  creditsAccessor.Set((creditsAccessor.Get() or 0) + 1)
1841
1845
  robuxLog(entry, {
1842
1846
  PurchaseId = purchaseId,
@@ -2637,7 +2641,7 @@ function Monetization.new(ctx: any)
2637
2641
  local credits = tonumber(reserved.GiftCredits[productName]) or 0
2638
2642
  if credits > 0 then
2639
2643
  local giftId = Util.guid()
2640
- local creditAccessor = reservedAcc(entry).GiftCredits[productName]
2644
+ local creditAccessor = reservedAcc(entry).GiftCredits.Child(productName)
2641
2645
  -- Refunds re-read the live count instead of restoring the stale pre-read value: a
2642
2646
  -- receipt retry can issue a credit during the yields below, and an absolute
2643
2647
  -- restore would erase it. Both steps between the spend and this refund yield, so
@@ -2933,13 +2937,20 @@ function Monetization.new(ctx: any)
2933
2937
  end
2934
2938
 
2935
2939
  local cost = spec.Cost
2936
- if type(cost) ~= "table" or type(cost.Path) ~= "string" or type(cost.Amount) ~= "number" then
2940
+ local amountType = if type(cost) == "table" then type(cost.Amount) else nil
2941
+ if
2942
+ type(cost) ~= "table"
2943
+ or type(cost.Path) ~= "string"
2944
+ or (amountType ~= "number" and amountType ~= "string" and amountType ~= "table")
2945
+ then
2937
2946
  return false, "invalid Cost spec"
2938
2947
  end
2939
- local amount: number = cost.Amount
2948
+ -- Keep existing refusal reasons until the path confirms a Big currency.
2949
+ local amountIsNumber = amountType == "number"
2950
+ local amount: number = if amountIsNumber then cost.Amount else 0
2940
2951
  -- A non-positive amount would pass the funds check and CREDIT currency while
2941
2952
  -- still granting the item.
2942
- if amount <= 0 or amount ~= amount then
2953
+ if amountIsNumber and (amount <= 0 or amount ~= amount) then
2943
2954
  return false, "invalid Cost amount"
2944
2955
  end
2945
2956
  local costPath = Util.parsePath(cost.Path)
@@ -2948,12 +2959,12 @@ function Monetization.new(ctx: any)
2948
2959
  local walked, costAccessor = pcall(function()
2949
2960
  local acc = entry.Tree.Accessor
2950
2961
  for _, segment in costPath do
2951
- acc = acc[segment]
2962
+ acc = acc.Child(segment)
2952
2963
  end
2953
2964
  return acc
2954
2965
  end)
2955
2966
  if not walked then
2956
- return false, "invalid cost path"
2967
+ return false, if amountIsNumber then "invalid cost path" else "invalid Cost spec"
2957
2968
  end
2958
2969
  -- Follow the schema the way the accessor above does. Template.Resolve descends
2959
2970
  -- node.Children only, so a DictOf/ArrayOf element would stop the walk at the
@@ -2966,6 +2977,21 @@ function Monetization.new(ctx: any)
2966
2977
  end
2967
2978
  costSchema = next_
2968
2979
  end
2980
+ -- Keep Big balances and amounts out of double arithmetic.
2981
+ local bigAmount: Big.Big? = nil
2982
+ local bigFloor: Big.Big = BIG_ZERO
2983
+ if costSchema.ValueType == "big" then
2984
+ -- Invalid table operands may throw; return a refusal instead.
2985
+ local parsedOk, parsed = pcall(Big.from, cost.Amount)
2986
+ bigAmount = if parsedOk then parsed else nil
2987
+ if bigAmount == nil or Big.compare(bigAmount, BIG_ZERO) <= 0 then
2988
+ return false, "invalid Cost amount"
2989
+ end
2990
+ -- Compile already refused a Min that does not parse.
2991
+ bigFloor = Big.from(costSchema.Min or 0) :: Big.Big
2992
+ elseif not amountIsNumber then
2993
+ return false, "invalid Cost spec"
2994
+ end
2969
2995
  -- A fractional amount on an int currency rounds the debit toward zero, or to no
2970
2996
  -- debit at all, while the grant still runs.
2971
2997
  if costSchema.ValueType == "int" and amount % 1 ~= 0 then
@@ -2988,11 +3014,22 @@ function Monetization.new(ctx: any)
2988
3014
  end
2989
3015
  local function readBalance(): any
2990
3016
  local value = costAccessor.Get()
2991
- if value == nil and isElementLeaf and type(costSchema.Default) == "number" then
2992
- return costSchema.Default
3017
+ if value == nil and isElementLeaf then
3018
+ if type(costSchema.Default) == "number" then
3019
+ return costSchema.Default
3020
+ end
3021
+ -- A big element's default is its stored { mantissa, exponent } pair.
3022
+ if bigAmount ~= nil then
3023
+ return Big.from(costSchema.Default)
3024
+ end
2993
3025
  end
2994
3026
  return value
2995
3027
  end
3028
+ -- Check headroom and remainder: either subtraction can round past a non-zero floor.
3029
+ local function bigAffords(balance: any): boolean
3030
+ return Big.compare(Big.sub(balance, bigFloor), bigAmount :: Big.Big) >= 0
3031
+ and Big.compare(Big.sub(balance, bigAmount :: Big.Big), bigFloor) >= 0
3032
+ end
2996
3033
 
2997
3034
  -- Already granted under this key? Return the ORIGINAL outcome, matching the receipt
2998
3035
  -- path; the "this was a duplicate" signal goes to logs and metrics rather than into
@@ -3007,29 +3044,42 @@ function Monetization.new(ctx: any)
3007
3044
  end
3008
3045
 
3009
3046
  local current = readBalance()
3010
- if type(current) ~= "number" then
3011
- -- Two different refusals wearing one string. The accessor walk above already
3012
- -- SUCCEEDED, so the path is not a typo: it resolved to something real that cannot
3013
- -- be spent, Scribe.Big being the case that bites (stored as a table, while
3014
- -- Purchase does plain arithmetic). Only for a DECLARED non-numeric type: an
3015
- -- element of a dynamic container has no ValueType, and there the old string is
3016
- -- still the honest answer.
3047
+ local spendable = if bigAmount ~= nil then Big.isBig(current) else type(current) == "number"
3048
+ if not spendable then
3049
+ -- Distinguish a declared non-currency from an absent or untyped balance.
3017
3050
  local valueType = costSchema.ValueType
3018
- if valueType ~= nil and valueType ~= "any" and valueType ~= "int" and valueType ~= "number" then
3051
+ if
3052
+ valueType ~= nil
3053
+ and valueType ~= "any"
3054
+ and valueType ~= "int"
3055
+ and valueType ~= "number"
3056
+ and valueType ~= "big"
3057
+ then
3019
3058
  return false, "cost path is not a spendable number"
3020
3059
  end
3021
3060
  return false, "invalid cost path"
3022
3061
  end
3023
- if current - amount < floor then
3062
+ if bigAmount ~= nil then
3063
+ if not bigAffords(current) then
3064
+ return false, "insufficient funds"
3065
+ end
3066
+ elseif current - amount < floor then
3024
3067
  return false, "insufficient funds"
3025
3068
  end
3026
3069
 
3027
3070
  local ok, err = entry.Tree:RunTransaction(function()
3028
3071
  local balance = readBalance()
3029
- if balance - amount < floor then
3030
- error("insufficient funds")
3072
+ if bigAmount ~= nil then
3073
+ if not bigAffords(balance) then
3074
+ error("insufficient funds")
3075
+ end
3076
+ costAccessor.Set(Big.sub(balance, bigAmount :: Big.Big))
3077
+ else
3078
+ if balance - amount < floor then
3079
+ error("insufficient funds")
3080
+ end
3081
+ costAccessor.Set(balance - amount)
3031
3082
  end
3032
- costAccessor.Set(balance - amount)
3033
3083
  if spec.Grant then
3034
3084
  (spec.Grant :: (any) -> ())(entry.Tree.Accessor)
3035
3085
  end
@@ -3057,7 +3107,8 @@ function Monetization.new(ctx: any)
3057
3107
  Category = spec.Category,
3058
3108
  ItemId = spec.ItemId,
3059
3109
  Currency = tostring(costPath[#costPath]),
3060
- Amount = amount,
3110
+ -- Store the Big pair; conversion to a double can overflow.
3111
+ Amount = if bigAmount ~= nil then Big.toStored(bigAmount) else amount,
3061
3112
  Ts = Clock.Now(),
3062
3113
  Meta = spec.Meta,
3063
3114
  })
@@ -3070,7 +3121,12 @@ function Monetization.new(ctx: any)
3070
3121
  end
3071
3122
 
3072
3123
  -- Analytics only after commit so a rollback emits no event.
3073
- ctx.Analytics.Economy(player, costPath, -amount, costAccessor.Get(), {
3124
+ local delta, newValue = -amount, costAccessor.Get()
3125
+ if bigAmount ~= nil then
3126
+ -- Analytics uses doubles. The grant may have removed the balance.
3127
+ delta, newValue = -Big.toNumber(bigAmount), if Big.isBig(newValue) then Big.toNumber(newValue) else nil
3128
+ end
3129
+ ctx.Analytics.Economy(player, costPath, delta, newValue, {
3074
3130
  Source = spec.ItemId or spec.Category or "Purchase",
3075
3131
  Flow = "Sink",
3076
3132
  Item = spec.ItemId,
@@ -3104,8 +3160,10 @@ function Monetization.new(ctx: any)
3104
3160
  Log.Warn(
3105
3161
  "Gifting",
3106
3162
  "GIFT_CREDIT_UNKNOWN_PRODUCT",
3107
- `player holds {tostring(count)} gift credit(s) for "{tostring(creditName)}", which is not in Products; `
3108
- .. "they are unspendable until the product returns or a migration renames the credit key",
3163
+ `player holds {tostring(count)} gift credit(s) for "{tostring(creditName)}", which is in neither `
3164
+ .. "Products nor RetiredProducts; they stay unspendable until that name is declared again. For a "
3165
+ .. "removed product, add it to RetiredProducts with its original Id and grant. A migration cannot "
3166
+ .. "move them: the reserved root is library-owned and migration edits to it are discarded",
3109
3167
  { Player = entry.Player, Product = tostring(creditName) }
3110
3168
  )
3111
3169
  end