@quenty/datastore 13.44.0 → 13.46.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [13.46.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.45.0...@quenty/datastore@13.46.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+- Improve stuff ([ae11166](https://github.com/Quenty/NevermoreEngine/commit/ae1116636cea882a51754b0a74cb5a641bad9ae4))
+
+# [13.45.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.44.0...@quenty/datastore@13.45.0) (2026-07-21)
+
+### Features
+
+- Add ephemeral save slots ([16bd91b](https://github.com/Quenty/NevermoreEngine/commit/16bd91b87943a65165245cba90d44274585903d6))
+
 # [13.44.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.43.0...@quenty/datastore@13.44.0) (2026-07-21)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/datastore",
-  "version": "13.44.0",
+  "version": "13.46.0",
   "description": "Quenty's Datastore implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -29,26 +29,27 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "10.14.0",
-    "@quenty/bindtocloseservice": "8.35.0",
+    "@quenty/baseobject": "10.15.0",
+    "@quenty/bindtocloseservice": "8.36.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.10.0",
+    "@quenty/maid": "3.11.0",
     "@quenty/math": "2.7.5",
-    "@quenty/messagingserviceutils": "7.24.0",
-    "@quenty/nevermore-test-runner": "1.4.0",
-    "@quenty/pagesutils": "5.21.0",
-    "@quenty/promise": "10.20.0",
-    "@quenty/promisemaid": "5.20.0",
-    "@quenty/rx": "13.30.0",
-    "@quenty/servicebag": "11.19.0",
+    "@quenty/messagingserviceutils": "7.25.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/pagesutils": "5.22.0",
+    "@quenty/playermock": "1.1.0",
+    "@quenty/promise": "10.21.0",
+    "@quenty/promisemaid": "5.21.0",
+    "@quenty/rx": "13.31.0",
+    "@quenty/servicebag": "11.20.0",
     "@quenty/signal": "7.13.1",
     "@quenty/symbol": "3.5.2",
     "@quenty/table": "3.9.2",
-    "@quenty/valueobject": "13.33.0",
+    "@quenty/valueobject": "13.34.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b7e59984e586064ea3cec6176e79b3f7451ecdc5"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Server/DataStore.LoadErrors.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	Characterizes the shared load promise and the auto-save loop. The load view is cached
-	(PromiseViewUpToDate returns one shared promise), so every Load/LoadAll/Store/Observe attaches
-	its own continuation to the same promise; these tests pin that a settled load fans out its
-	resolution or rejection to every consumer, including ones attached mid-yield.
-
 	@class DataStoreLoadErrors.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -94,7 +89,6 @@ describe("auto-save loop", function()
 		local dataStore = controller.newDataStore("key")
 		dataStore:SetAutoSaveTimeSeconds(0.2)
 
-		-- Store triggers the initial load; once loaded, the auto-save loop starts and flushes.
 		dataStore:Store("coins", 5)
 
 		local saved = PromiseTestUtils.awaitValue(function()
@@ -119,8 +113,6 @@ describe("auto-save loop", function()
 
 		dataStore:Destroy()
 
-		-- After destroy the loop is gone: record the call count, wait past several auto-save
-		-- intervals, and confirm no new saves land.
 		local before = controller.mock:GetCallCount("UpdateAsync")
 		local settled = PromiseTestUtils.awaitValue(function()
 			return false

package/src/Server/DataStore.Overflow.spec.lua

@@ -1,11 +1,5 @@
 --!nonstrict
 --[[
-	Integration coverage for the overflow-save failure: when a key accumulates more data than Roblox
-	can serialize under its per-key size ceiling, the write throws and the save must fail loudly rather
-	than silently drop the data or corrupt what was already stored. Driven through the full DataStore
-	stack against a DataStoreMock configured with a small [DataStoreMock.SetMaxValueLength] so the
-	overflow triggers without a multi-megabyte payload.
-
 	@class DataStore.Overflow.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -19,8 +13,6 @@ local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
 local it = Jest.Globals.it
 
--- Asserts the promise settled within the timeout, so a hung promise fails the test (here) instead of
--- freezing the runner on the following :Yield().
 local function expectSettled(promise, timeout: number?)
 	expect(PromiseTestUtils.awaitSettled(promise, timeout)).toEqual(true)
 end
@@ -49,7 +41,6 @@ describe("DataStore overflow save", function()
 		writer:Store("data", "known-good")
 		expectSettled(writer:Save())
 
-		-- Now grow the same key past the ceiling and try to save again.
 		controller.mock:SetMaxValueLength(1024)
 		writer:Store("data", string.rep("A", 8192))
 
@@ -57,7 +48,6 @@ describe("DataStore overflow save", function()
 		expectSettled(savePromise, 5)
 		expect((savePromise:Yield())).toEqual(false)
 
-		-- The failed write must not have clobbered the stored value.
 		controller.mock:SetMaxValueLength(nil)
 		local reader = controller.newDataStore()
 		local loadPromise = reader:Load("data")
@@ -95,8 +85,6 @@ describe("DataStore overflow save", function()
 
 		expectSettled(dataStore:Load("data"))
 
-		-- The whole key value -- every substore merged together -- is what gets serialized, so a single
-		-- oversized substore entry overflows the entire save.
 		controller.mock:SetMaxValueLength(1024)
 		dataStore:GetSubStore("inventory"):Store("blob", string.rep("A", 8192))
 

package/src/Server/DataStore.Reentrance.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	Re-entrance and cancellation: when a datastore request is in flight (yielding) and its owning
-	maid is torn down (the DataStore is destroyed / the player leaves), the request thread must be
-	cancelled and never resume to write. A session-locked load can legitimately stay pending for a
-	long time while a lock command is outstanding.
-
 	@class DataStoreReentrance.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -20,18 +15,15 @@ local it = Jest.Globals.it
 describe("in-flight request cancellation (maid teardown)", function()
 	it("cancels a yielding load thread when the DataStore is destroyed (no leaked thread)", function()
 		local controller = DataStoreTestUtils.setup()
-		controller.mock:BlockRequests() -- the lock-acquire request hangs, so the load is stuck in flight
+		controller.mock:BlockRequests()
 
 		local dataStore = controller.newSessionLockedStore()
 		local promise = dataStore:PromiseLoadSuccessful()
 
 		expect(PromiseTestUtils.awaitSettled(promise, 1)).toEqual(false)
 
-		-- Destroy while the request thread is yielding -- its maid must cancel it.
 		dataStore:Destroy()
 
-		-- A properly cancelled thread never resumes, so the lock is never written. A leaked thread
-		-- would resume on unblock and write the lock envelope.
 		controller.mock:UnblockRequests()
 		local everWrote = PromiseTestUtils.awaitValue(function()
 			return controller.mock:GetRaw("player_1") ~= nil
@@ -44,7 +36,6 @@ describe("in-flight request cancellation (maid teardown)", function()
 	it("cancels a yielding save thread when the DataStore is destroyed", function()
 		local controller = DataStoreTestUtils.setup()
 
-		-- Load cleanly first (acquires the lock), then block so the SAVE request hangs in flight.
 		local dataStore = controller.newSessionLockedStore()
 		local loadPromise = dataStore:PromiseLoadSuccessful()
 		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
@@ -62,7 +53,6 @@ describe("in-flight request cancellation (maid teardown)", function()
 		dataStore:Destroy()
 		controller.mock:UnblockRequests()
 
-		-- The cancelled save thread must not resume and perform another UpdateAsync write.
 		local extraWrites = PromiseTestUtils.awaitValue(function()
 			return controller.mock:GetCallCount("UpdateAsync") > versionsBefore + 1
 		end, 2)
@@ -75,12 +65,11 @@ end)
 describe("lock command that does not settle", function()
 	it("keeps the load pending while the lock command is outstanding, then completes when it settles", function()
 		local controller = DataStoreTestUtils.setup()
-		controller.mock:BlockRequests() -- simulate a lock command that hasn't propagated yet (up to ~30s)
+		controller.mock:BlockRequests()
 
 		local dataStore = controller.newSessionLockedStore()
 		local promise = dataStore:PromiseLoadSuccessful()
 
-		-- Must NOT spuriously resolve or error while the lock command is outstanding.
 		expect(PromiseTestUtils.awaitSettled(promise, 2)).toEqual(false)
 
 		controller.mock:UnblockRequests()
@@ -101,10 +90,9 @@ describe("lock command that does not settle", function()
 		local first = controller.newSessionLockedStore()
 		local firstPromise = first:PromiseLoadSuccessful()
 		expect(PromiseTestUtils.awaitSettled(firstPromise, 1)).toEqual(false)
-		first:Destroy() -- cancel the in-flight lock command
+		first:Destroy()
 		controller.mock:UnblockRequests()
 
-		-- The cancelled attempt left no lock, so a fresh session acquires cleanly.
 		local second = controller.newSessionLockedStore()
 		local secondPromise = second:PromiseLoadSuccessful()
 		if not PromiseTestUtils.awaitSettled(secondPromise, 10) then

package/src/Server/DataStore.SessionLock.spec.lua

@@ -1,12 +1,5 @@
 --!nonstrict
 --[[
-	Deep characterization of the session-lock state machine (DataStoreLockHelper) and the
-	cross-server scenarios it governs: validate/invalidate a lock, steal a crashed session's lock,
-	block a live session, and prevent data duplication when a session is stolen. Two servers are
-	modeled as two DataStore objects sharing one DataStoreMock, with distinct SessionIds. The
-	blocking cases assume RunService:IsStudio() == false (true in the cloud test runner); in Studio,
-	ALWAYS_STEAL_LOCKS_IN_STUDIO makes every foreign lock stealable.
-
 	@class DataStoreSessionLock.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -27,7 +20,6 @@ local function foreignSession(sessionId: string?)
 	}
 end
 
--- Builds a stored profile locked by an arbitrary session.
 local function lockedBy(session, lastUpdateTime: number?, data: { [string]: any }?)
 	local profile = {}
 	if data then
@@ -98,7 +90,6 @@ describe("DataStoreLockHelper.AcquireLock", function()
 		local result = helper:AcquireLock(lockedBy(foreignSession(), os.time() - 700, { coins = 9 }), false)
 		expect(result.isValid).toEqual(true)
 		expect(result.stolenLockFromSession.SessionId).toEqual("foreign-session-id")
-		-- The crashed session's data survives the steal.
 		expect(result.unlockedProfile.coins).toEqual(9)
 		controller:destroy()
 	end)
@@ -274,14 +265,12 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 	it("blocks a new session's load while another session holds a fresh lock", function()
 		local controller = DataStoreTestUtils.setup()
 
-		-- A fresh, live foreign lock is present in the datastore.
 		controller.mock:SetRaw("player_1", lockedBy(foreignSession(), os.time(), { coins = 1 }))
 
 		local dataStore = controller.newDataStore()
 		dataStore:SetSessionLockingEnabled(true)
 		dataStore:SetUserIdList({ 1 })
 
-		-- The load is legitimately blocked (retrying to acquire), so it must NOT settle quickly.
 		local promise = dataStore:PromiseLoadSuccessful()
 		expect(PromiseTestUtils.awaitSettled(promise, 3)).toEqual(false)
 
@@ -289,12 +278,8 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 	end)
 
 	it("acquires the lock once the holding session releases it (retry resolves genuine contention)", function()
-		-- GUARD for the load-hang fix: a blocked load must still RESOLVE via retry when the holder
-		-- releases -- only genuine op FAILURES should fail fast, not lock contention (a successful op
-		-- that returns a locked profile).
 		local controller = DataStoreTestUtils.setup()
 
-		-- Session A acquires and holds the lock.
 		local sessionA = controller.newDataStore()
 		sessionA:SetSessionLockingEnabled(true)
 		sessionA:SetUserIdList({ 1 })
@@ -306,8 +291,6 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 		end
 		expect((loadA:Yield())).toEqual(true)
 
-		-- Session B starts loading; A's fresh lock blocks it, so B is retrying (not yet settled). Use a
-		-- tiny retry backoff so the test exercises the retry quickly instead of the ~6.5s production one.
 		local sessionB = controller.newDataStore()
 		sessionB:SetSessionLockingEnabled(true)
 		sessionB:SetUserIdList({ 1 })
@@ -315,7 +298,6 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 		local loadB = sessionB:PromiseLoadSuccessful()
 		expect(PromiseTestUtils.awaitSettled(loadB, 0.5)).toEqual(false)
 
-		-- A releases the lock; B's next retry attempt should acquire it and the load resolves.
 		local closeA = sessionA:SaveAndCloseSession()
 		if not PromiseTestUtils.awaitSettled(closeA, 10) then
 			expect("A close hung").toEqual("A close settled")
@@ -348,10 +330,8 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 		end
 		expect((loadA:Yield())).toEqual(true)
 
-		-- Another live session steals the lock and writes its own value directly into the datastore.
 		controller.mock:SetRaw("player_1", lockedBy(foreignSession("winner-session"), os.time(), { coins = 20 }))
 
-		-- Session A tries to save its own (now-orphaned) change.
 		sessionA:Store("coins", 10)
 		local saveA = sessionA:Save()
 		if not PromiseTestUtils.awaitSettled(saveA, 10) then
@@ -360,8 +340,6 @@ describe("session lock cross-server scenarios (full DataStore)", function()
 			return
 		end
 
-		-- A's write was cancelled, so the datastore still holds the winner's data -- not A's, and not
-		-- a merged/duplicated mix.
 		local raw = controller.mock:GetRaw("player_1")
 		expect(raw.coins).toEqual(20)
 		expect(raw.lock.ActiveSession.SessionId).toEqual("winner-session")
@@ -387,8 +365,6 @@ describe("session lock edge cases and failure modes", function()
 		end
 		expect((first:Yield())).toEqual(true)
 
-		-- The load is cached (_firstLoadPromise), so exactly one UpdateAsync acquires the lock -- a
-		-- second acquire would risk two "owners" of the session.
 		expect(controller.mock:GetCallCount("UpdateAsync")).toEqual(1)
 
 		controller:destroy()
@@ -419,8 +395,6 @@ describe("session lock edge cases and failure modes", function()
 			return
 		end
 
-		-- No corruption/duplication: the stored value is a valid number still owned by us, and the
-		-- last staged value won.
 		local raw = controller.mock:GetRaw("player_1")
 		expect(type(raw.coins)).toEqual("number")
 		expect(raw.coins).toEqual(2)
@@ -432,14 +406,9 @@ end)
 
 describe("why session locking exists (unlocked stores can duplicate)", function()
 	it("allows item duplication under a read-before-store race, without session locking", function()
-		-- The classic dupe that session locking prevents: two servers load the same profile, one
-		-- trades an item away and saves, but the other loaded BEFORE that save (or is a crashed
-		-- server's stale session) and writes its stale view back -- restoring the traded-away item.
-		-- This is EXPECTED behavior for unlocked stores; it is the whole motivation for locking.
 		local controller = DataStoreTestUtils.setup()
 		controller.mock:SetRaw("player_1", { items = { "rare_sword" } })
 
-		-- Two servers, NO session locking, both load the same starting state (B reads before A stores).
 		local serverA = controller.newDataStore()
 		local serverB = controller.newDataStore()
 
@@ -453,7 +422,6 @@ describe("why session locking exists (unlocked stores can duplicate)", function(
 		expect((aLoad:Wait())).toEqual({ "rare_sword" })
 		expect((bLoad:Wait())).toEqual({ "rare_sword" })
 
-		-- Server A: the player trades the sword away, and A saves it gone.
 		serverA:Store("items", {})
 		if not PromiseTestUtils.awaitSettled(serverA:Save(), 5) then
 			expect("A save hung").toEqual("A save settled")
@@ -462,7 +430,6 @@ describe("why session locking exists (unlocked stores can duplicate)", function(
 		end
 		expect(controller.mock:GetRaw("player_1").items).toEqual({})
 
-		-- Server B still holds the stale sword and writes it back on its own save.
 		serverB:Store("items", { "rare_sword" })
 		if not PromiseTestUtils.awaitSettled(serverB:Save(), 5) then
 			expect("B save hung").toEqual("B save settled")
@@ -470,7 +437,6 @@ describe("why session locking exists (unlocked stores can duplicate)", function(
 			return
 		end
 
-		-- The traded-away sword is back: duplicated. An unlocked store cannot prevent this.
 		expect(controller.mock:GetRaw("player_1").items).toEqual({ "rare_sword" })
 
 		controller:destroy()

package/src/Server/DataStore.TwoServerLock.spec.lua

@@ -1,11 +1,5 @@
 --!nonstrict
 --[[
-	Two servers fighting over one player's session-locked key: two DataStore objects (server A and
-	server B) share one DataStoreMock with distinct SessionIds, exactly like two live game servers.
-	This exercises the full cross-server lock lifecycle -- clean handoff via close, crash recovery via
-	stale-lock steal, a concurrent-load race, the MessagingService graceful-close handshake, and
-	session-stolen data integrity.
-
 	@class DataStoreTwoServerLock.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -49,7 +43,6 @@ describe("two servers: clean handoff and crash recovery", function()
 	it("recovers a crashed server's saved data by stealing its stale lock", function()
 		local controller = DataStoreTestUtils.setup()
 
-		-- A acquires, saves coins under its lock, then "crashes" (no clean close).
 		local serverA = controller.newServer()
 		expect(controller.awaitOwn(serverA)).toEqual(true)
 		serverA:Store("coins", 7)
@@ -59,12 +52,10 @@ describe("two servers: clean handoff and crash recovery", function()
 			return
 		end
 
-		-- Age A's lock so it looks like a long-dead (crashed) server, then abandon A.
 		local raw = controller.mock:GetRaw(KEY)
 		raw.lock.LastUpdateTime = os.time() - 1000000
 		controller.mock:SetRaw(KEY, raw)
 
-		-- B loads: steals the stale lock and recovers A's saved coins.
 		local serverB = controller.newServer()
 		local coins = serverB:Load("coins")
 		if not PromiseTestUtils.awaitSettled(coins, 10) then
@@ -87,14 +78,13 @@ describe("two servers: clean handoff and crash recovery", function()
 		local loadA = serverA:PromiseLoadSuccessful()
 		local loadB = serverB:PromiseLoadSuccessful()
 
-		-- One acquires quickly; the other is blocked (retrying against the winner's fresh lock).
 		expect(PromiseTestUtils.awaitValue(function()
 			return not loadA:IsPending() or not loadB:IsPending()
 		end, 5)).toEqual(true)
 
 		local aSettled = not loadA:IsPending()
 		local bSettled = not loadB:IsPending()
-		expect(aSettled ~= bSettled).toEqual(true) -- exactly one
+		expect(aSettled ~= bSettled).toEqual(true)
 
 		local owner = controller.mock:GetRaw(KEY).lock.ActiveSession.SessionId
 		expect(owner == serverA:GetSessionId() or owner == serverB:GetSessionId()).toEqual(true)
@@ -108,7 +98,6 @@ describe("two servers: clean handoff and crash recovery", function()
 		local serverA = controller.newServer()
 		expect(controller.awaitOwn(serverA)).toEqual(true)
 
-		-- B takes over by writing its own lock + data directly (as if it stole the session).
 		controller.mock:SetRaw(KEY, {
 			coins = 100,
 			lock = {
@@ -117,7 +106,6 @@ describe("two servers: clean handoff and crash recovery", function()
 			},
 		})
 
-		-- A tries to save its own value; the write is cancelled (SessionStolen), B's data survives.
 		local stolen = nil
 		serverA.SessionStolen:Connect(function(session)
 			stolen = session
@@ -145,7 +133,6 @@ describe("two servers: MessagingService graceful close", function()
 
 		local _serverB, helperB = controller.newServer({ messaging = true })
 
-		-- B gracefully asks A (the lock holder) to close.
 		local graceful = helperB:PromiseCloseSessionGraceful(game.PlaceId, game.JobId, serverA:GetSessionId())
 		if not PromiseTestUtils.awaitSettled(graceful, 15) then
 			expect("graceful close hung").toEqual("resolved")
@@ -154,7 +141,6 @@ describe("two servers: MessagingService graceful close", function()
 		end
 		expect((graceful:Yield())).toEqual(true)
 
-		-- A honored the request and released its lock.
 		expect(PromiseTestUtils.awaitValue(function()
 			local raw = controller.mock:GetRaw(KEY)
 			return raw ~= nil and raw.lock == nil
@@ -166,13 +152,9 @@ describe("two servers: MessagingService graceful close", function()
 	it("evicts the holder during a messaging-enabled load and then acquires (production flow)", function()
 		local controller = DataStoreTestUtils.setup()
 
-		-- A holds the lock and will honor a graceful close request.
 		local serverA = controller.newServer({ messaging = true, autoCloseOnRequest = true })
 		expect(controller.awaitOwn(serverA)).toEqual(true)
 
-		-- B loads with messaging enabled: blocked by A's fresh lock, its load asks A to close, then
-		-- (after the propagation delay) retries and acquires. This is the real cross-server handoff.
-		-- Use a tiny propagation delay so the test does not wait the production 5s.
 		local serverB = controller.newServer({ messaging = true })
 		serverB:SetSessionMessagingCloseDelaySeconds(0.1)
 		local loadB = serverB:PromiseLoadSuccessful()

package/src/Server/DataStore.spec.lua

@@ -1,8 +1,5 @@
 --!nonstrict
 --[[
-	Integration coverage for DataStore against a mocked Roblox datastore: the load/save round-trip
-	and how it behaves when datastore operations fail (e.g. the 509 Personal-RCC block).
-
 	@class DataStore.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -16,8 +13,6 @@ local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
 local it = Jest.Globals.it
 
--- Asserts the promise settled within the timeout, so a hung promise fails the test (here) instead of
--- freezing the runner on the following :Yield().
 local function expectSettled(promise, timeout: number?)
 	expect(PromiseTestUtils.awaitSettled(promise, timeout)).toEqual(true)
 end
@@ -225,8 +220,6 @@ describe("DataStore with session locking", function()
 		dataStore:SetSessionLockingEnabled(true)
 		dataStore:SetUserIdList({ 1 })
 
-		-- PromiseLoadSuccessful maps the error to a boolean, so read the rejection from
-		-- PromiseViewUpToDate to assert the underlying datastore error propagates.
 		local outcome, err = PromiseTestUtils.awaitOutcome(dataStore:PromiseViewUpToDate())
 
 		expect(outcome).toEqual("rejected")

package/src/Server/DataStoreLockHelper.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	Characterization coverage for DataStore session locking, exercised through a real DataStore
-	against a mocked Roblox datastore. It pins the observable behaviour of the lock lifecycle: a
-	healthy acquire wraps the stored profile in a lock envelope, SaveAndCloseSession releases it,
-	user data survives a lock/unlock round-trip, and a stale lock left by a dead session is stolen.
-
 	@class DataStoreLockHelper.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -68,7 +63,6 @@ describe("DataStore session locking", function()
 		end
 		expect((closePromise:Yield())).toEqual(true)
 
-		-- Closing strips the lock envelope back off the stored value.
 		local raw = controller.mock:GetRaw("player_1")
 		expect(type(raw)).toEqual("table")
 		expect(raw.lock).toEqual(nil)
@@ -125,10 +119,6 @@ describe("DataStore session locking", function()
 	it("steals a stale lock left by a dead session", function()
 		local controller = DataStoreTestUtils.setup()
 
-		-- Seed a lock owned by a long-dead session. LastUpdateTime is far enough in the past that
-		-- os.time() - LastUpdateTime exceeds GetAutoSaveTimeSeconds() * 2.1 (default 300 * 2.1 = 630s),
-		-- so the lock is stolen on the first acquire attempt (no retry backoff). Seed user data too,
-		-- to prove it survives the steal.
 		controller.mock:SetRaw("player_1", {
 			coins = 7,
 			lock = {
@@ -156,7 +146,6 @@ describe("DataStore session locking", function()
 		local raw = controller.mock:GetRaw("player_1")
 		expect(raw.lock.ActiveSession.SessionId).toEqual(dataStore:GetSessionId())
 
-		-- The dead session's user data survived the steal.
 		local loadPromise = dataStore:Load("coins")
 		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
 			expect("hung").toEqual("settled")
@@ -183,7 +172,6 @@ describe("DataStore session locking", function()
 		end
 		expect((loadPromise:Yield())).toEqual(true)
 
-		-- Another session steals the lock out from under us directly in the datastore.
 		controller.mock:SetRaw("player_1", {
 			coins = 1,
 			lock = {

package/src/Server/DataStoreMessageHelper.spec.lua

@@ -1,11 +1,5 @@
 --!nonstrict
 --[[
-	Coverage for DataStoreMessageHelper, the coordinator that drives graceful cross-server
-	session-close over MessagingService. The full request/complete handshake needs a second server
-	to answer, so cross-server behaviour is characterized rather than asserted; what a single server
-	can verify (construction, the "cannot message self" guard, messaging wiring, and the
-	MessagingServiceUtils.toHumanReadable formatter) is exercised here.
-
 	@class DataStoreMessageHelper.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -53,7 +47,6 @@ describe("DataStoreMessageHelper.new", function()
 		local controller = DataStoreTestUtils.setup()
 		local helper = controller.newMessageHelper()
 
-		-- The test destroys the helper itself; the maid then skips it, so there is no double-Destroy.
 		expect(function()
 			helper:Destroy()
 		end).never.toThrow()
@@ -81,8 +74,6 @@ end)
 
 describe("DataStoreMessageHelper.PromiseCloseSessionGraceful", function()
 	it("should return a promise (cross-server outcome is not unit-testable single-server)", function()
-		-- The graceful handshake needs a second server to answer, so we only assert it returns a
-		-- promise; its settlement is environment dependent and covered by real multi-server usage.
 		local controller = DataStoreTestUtils.setup()
 		local helper = controller.newMessageHelper()
 
@@ -97,7 +88,6 @@ describe("DataStore.SetSessionMessagingEnabled wiring", function()
 	it("should enable then disable session messaging without erroring", function()
 		local controller = DataStoreTestUtils.setup()
 		local dataStore = controller.newDataStore()
-		-- Messaging is documented to work alongside session locking; enable both like real usage.
 		dataStore:SetSessionLockingEnabled(true)
 		dataStore:SetUserIdList({ 1 })
 

package/src/Server/GameDataStoreService.lua

@@ -83,8 +83,11 @@ function GameDataStoreService.PromiseDataStore(self: GameDataStoreService): Prom
 			if not dataStore.Destroy then
 				return
 			end
-			-- Best-effort: swallow a rejection (e.g. the load failed) so it is not uncaught.
-			dataStore:Save():Catch(function() end)
+			-- A failed load makes Save() reject unconditionally; skip it so teardown does not
+			-- manufacture a guaranteed rejection.
+			if not dataStore:DidLoadFail() then
+				dataStore:Save()
+			end
 			dataStore:Destroy()
 		end)
 

package/src/Server/GameDataStoreService.spec.lua

@@ -1,9 +1,5 @@
 --!nonstrict
 --[[
-	Integration coverage for GameDataStoreService wired through a real ServiceBag, with the underlying
-	datastore injected via the SetRobloxDataStore test seam. It is not session-locking, so a failing
-	load rejects promptly rather than hanging.
-
 	@class GameDataStoreService.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -98,7 +94,6 @@ describe("GameDataStoreService persistence", function()
 		end
 		expect((savePromise:Yield())).toEqual(true)
 
-		-- Non-session-locking, so the raw persisted value is the plain data table.
 		local raw = controller.mock:GetRaw("version1")
 		expect(raw).never.toBeNil()
 		expect(raw.motd).toEqual("hello")
@@ -121,7 +116,6 @@ describe("GameDataStoreService.SetRobloxDataStore", function()
 	it("should throw on a non-datastore argument", function()
 		local controller = setup()
 
-		-- isDataStore is validated before the already-resolved check, so a bad arg throws regardless.
 		expect(function()
 			controller.service:SetRobloxDataStore({})
 		end).toThrow("Bad robloxDataStore")
@@ -151,7 +145,6 @@ describe("GameDataStoreService failure handling", function()
 		local ok, dataStore = promise:Yield()
 		expect(ok).toEqual(true)
 
-		-- Non-session-locking: a failing load rejects promptly, so this settles false rather than hanging.
 		local loadPromise = dataStore:PromiseLoadSuccessful()
 		if not PromiseTestUtils.awaitSettled(loadPromise, 5) then
 			expect("hung").toEqual("settled")
@@ -204,8 +197,6 @@ describe("GameDataStoreService teardown", function()
 
 		dataStore:Store("motd", "goodbye")
 
-		-- Destroy must fire a synchronous Save before tearing the store down, so the value is
-		-- already in the store the instant destroy() returns -- asserted with no awaiting.
 		controller:destroy()
 
 		local raw = controller.mock:GetRaw("version1")

package/src/Server/InMemoryDataStore.lua

@@ -0,0 +1,73 @@
+--!strict
+--[=[
+	A [DataStoreStage] root that lives entirely in memory: it is never backed by a Roblox datastore, so
+	nothing it holds is ever written or read across sessions. Reads resolve to whatever has been staged in
+	memory (defaults when unset) and writes stay local to this object, vanishing when it is destroyed.
+
+	Every read/write/substore/observe method comes from [DataStoreStage] unchanged -- the base class computes
+	its view purely from in-memory snapshots. The only thing a stage normally needs a parent for is
+	[DataStoreStage.PromiseViewUpToDate] (loading its base layer from the datastore above it); a root has no
+	parent, so this class resolves that immediately against its own view. That single override is the whole
+	difference between this and [DataStore], which loads/saves through Roblox.
+
+	Use it wherever code wants a real store surface for data that must not persist -- e.g. a throwaway session
+	slot -- without paying for [DataStore]'s load, save, autosave, and session-locking machinery.
+
+	```lua
+	local store = InMemoryDataStore.new()
+	store:Store("coins", 5)
+	print(store:Load("coins"):Yield()) -- 5, never touches a datastore
+	```
+
+	@server
+	@class InMemoryDataStore
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreStage = require("DataStoreStage")
+local Promise = require("Promise")
+
+local InMemoryDataStore = setmetatable({}, DataStoreStage)
+InMemoryDataStore.ClassName = "InMemoryDataStore"
+InMemoryDataStore.__index = InMemoryDataStore
+
+export type InMemoryDataStore =
+	typeof(setmetatable({} :: {}, {} :: typeof({ __index = InMemoryDataStore })))
+	& DataStoreStage.DataStoreStage
+
+--[=[
+	Constructs a new in-memory data store.
+
+	@param loadName (string | number)? -- diagnostic name only (see [DataStoreStage.GetFullPath]); defaults to "InMemoryDataStore"
+	@return InMemoryDataStore
+]=]
+function InMemoryDataStore.new(loadName: (string | number)?): InMemoryDataStore
+	local self: InMemoryDataStore =
+		setmetatable(DataStoreStage.new(loadName or "InMemoryDataStore") :: any, InMemoryDataStore)
+
+	return self
+end
+
+--[=[
+	The view is always exactly what has been staged in memory, so it is never out of date: there is no
+	parent or datastore to sync from. Overriding this (the base class errors on a parentless stage) is what
+	makes every inherited read work in-memory.
+
+	@return Promise
+]=]
+function InMemoryDataStore.PromiseViewUpToDate(_self: InMemoryDataStore): Promise.Promise<()>
+	return Promise.resolved()
+end
+
+--[=[
+	A no-op that resolves: there is no backing datastore to flush to. Present so this is a drop-in root for
+	code that expects to be able to call `:Save()` on its store.
+
+	@return Promise
+]=]
+function InMemoryDataStore.Save(_self: InMemoryDataStore): Promise.Promise<()>
+	return Promise.resolved()
+end
+
+return InMemoryDataStore

package/src/Server/InMemoryDataStore.spec.lua

@@ -0,0 +1,231 @@
+--!nonstrict
+--[[
+	@class InMemoryDataStore.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local InMemoryDataStore = require("InMemoryDataStore")
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function resolve(promise, timeout: number?)
+	expect(PromiseTestUtils.awaitSettled(promise, timeout or 10)).toEqual(true)
+	local ok, value = promise:Yield()
+	expect(ok).toEqual(true)
+	return value
+end
+
+local function newInMemoryController()
+	local maid = Maid.new()
+	return {
+		makeStore = function()
+			return maid:Add(InMemoryDataStore.new())
+		end,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+local function newDataStoreController()
+	local controller = DataStoreTestUtils.setup()
+	return {
+		makeStore = function()
+			return controller.newDataStore()
+		end,
+		destroy = controller.destroy,
+	}
+end
+
+local function describeSharedBehavior(caseName: string, newController)
+	describe(caseName, function()
+		it("loads the default value when the key is empty", function()
+			local c = newController()
+			expect(resolve(c.makeStore():Load("coins", 99))).toEqual(99)
+			c.destroy()
+		end)
+
+		it("round-trips a stored value", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("coins", 5)
+			expect(resolve(store:Load("coins"))).toEqual(5)
+			c.destroy()
+		end)
+
+		it("round-trips multiple keys and loads defaults for missing ones", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("coins", 5)
+			store:Store("gems", 10)
+
+			local all = resolve(store:LoadAll())
+			expect(all.coins).toEqual(5)
+			expect(all.gems).toEqual(10)
+			expect(resolve(store:Load("missing", "default"))).toEqual("default")
+			c.destroy()
+		end)
+
+		it("deletes a key so it no longer loads", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+			store:Delete("a")
+
+			local all = resolve(store:LoadAll())
+			expect(all.a).toEqual(nil)
+			expect(all.b).toEqual(2)
+			c.destroy()
+		end)
+
+		it("overwrites the whole view", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+			store:Overwrite({ c = 3 })
+
+			local all = resolve(store:LoadAll())
+			expect(all.a).toEqual(nil)
+			expect(all.b).toEqual(nil)
+			expect(all.c).toEqual(3)
+			c.destroy()
+		end)
+
+		it("wipes to empty", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Wipe()
+			expect(resolve(store:LoadAll({}))).toEqual({})
+			c.destroy()
+		end)
+
+		it("round-trips substore values and nests them under the parent", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:GetSubStore("inventory"):Store("sword", true)
+
+			expect(resolve(store:GetSubStore("inventory"):Load("sword"))).toEqual(true)
+
+			local all = resolve(store:LoadAll())
+			expect(all.inventory.sword).toEqual(true)
+			c.destroy()
+		end)
+
+		it("lists the top-level keys", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+
+			local keys = resolve(store:PromiseKeyList())
+			table.sort(keys)
+			expect(keys).toEqual({ "a", "b" })
+			c.destroy()
+		end)
+
+		it("stores table values by deep copy, immune to later mutation of the source", function()
+			local c = newController()
+			local store = c.makeStore()
+			local source = { count = 1 }
+			store:Store("data", source)
+			source.count = 999
+
+			expect(resolve(store:Load("data")).count).toEqual(1)
+			c.destroy()
+		end)
+
+		it("observes a key: emits the initial value then updates on store", function()
+			local c = newController()
+			local store = c.makeStore()
+
+			local maid = Maid.new()
+			local seen = {}
+			maid:GiveTask(store:Observe("coins", 0):Subscribe(function(value)
+				table.insert(seen, value)
+			end))
+
+			expect(PromiseTestUtils.awaitValue(function()
+				return #seen >= 1
+			end, 5)).toEqual(true)
+			expect(seen[1]).toEqual(0)
+
+			store:Store("coins", 7)
+			expect(PromiseTestUtils.awaitValue(function()
+				return seen[#seen] == 7
+			end, 5)).toEqual(true)
+
+			maid:DoCleaning()
+			c.destroy()
+		end)
+	end)
+end
+
+describeSharedBehavior("matrix: DataStore over DataStoreMock", newDataStoreController)
+describeSharedBehavior("matrix: InMemoryDataStore", newInMemoryController)
+
+describe("matrix: cross-implementation consistency", function()
+	it("yields the same view for the same op sequence on both roots", function()
+		local dataStoreController = newDataStoreController()
+		local inMemoryController = newInMemoryController()
+
+		local function runOps(store)
+			store:Store("coins", 5)
+			store:Store("gems", 10)
+			store:GetSubStore("inventory"):Store("sword", true)
+			store:Delete("gems")
+			return resolve(store:LoadAll())
+		end
+
+		local persistedView = runOps(dataStoreController.makeStore())
+		local inMemoryView = runOps(inMemoryController.makeStore())
+
+		expect(inMemoryView).toEqual(persistedView)
+
+		dataStoreController.destroy()
+		inMemoryController.destroy()
+	end)
+end)
+
+describe("InMemoryDataStore isolation and non-persistence", function()
+	it("does not share data between separate instances", function()
+		local maid = Maid.new()
+		local first = maid:Add(InMemoryDataStore.new())
+		first:Store("coins", 5)
+
+		local second = maid:Add(InMemoryDataStore.new())
+		expect(resolve(second:Load("coins", 0))).toEqual(0)
+
+		maid:DoCleaning()
+	end)
+
+	it("resolves Save as a no-op", function()
+		local maid = Maid.new()
+		local store = maid:Add(InMemoryDataStore.new())
+		store:Store("coins", 5)
+
+		expect(resolve(store:Save())).toEqual(nil)
+		expect(resolve(store:Load("coins"))).toEqual(5)
+
+		maid:DoCleaning()
+	end)
+
+	it("resolves reads immediately with no parent to sync from", function()
+		local maid = Maid.new()
+		local store = maid:Add(InMemoryDataStore.new())
+
+		expect(resolve(store:LoadAll({}))).toEqual({})
+
+		maid:DoCleaning()
+	end)
+end)
+
+return nil

package/src/Server/Modules/DataStoreStage.spec.lua

@@ -1,9 +1,5 @@
 --!nonstrict
 --[[
-	Characterization coverage for the DataStoreStage staging layer, exercised through a real root
-	(`DataStore.new(DataStoreMock.new(), key)`) since a bare stage has no load parent. Stores here are
-	non-session-locking, so staging is deterministic.
-
 	@class DataStoreStage.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -154,12 +150,10 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 	describe("View priority", function()
 		it("should prioritize staged save data over loaded base data", function()
 			local mock = DataStoreMock.new()
-			-- Seed base data BEFORE constructing the reader so it loads through getAsync.
 			mock:SetRaw("player_1", { coins = 1, gems = 2 })
 
 			local dataStore = DataStore.new(mock, "player_1")
 
-			-- Base data loads first
 			local basePromise = dataStore:Load("coins")
 			if not PromiseTestUtils.awaitSettled(basePromise) then
 				expect("hung").toEqual("settled")
@@ -167,7 +161,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 			end
 			expect((basePromise:Wait())).toEqual(1)
 
-			-- Staged value overrides base; untouched base key stays visible
 			dataStore:Store("coins", 999)
 
 			local promise = dataStore:LoadAll()
@@ -228,7 +221,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 
 			local dataStore = DataStore.new(mock, "player_1")
 
-			-- Force base to load first
 			local basePromise = dataStore:Load("coins")
 			if not PromiseTestUtils.awaitSettled(basePromise) then
 				expect("hung").toEqual("settled")
@@ -347,8 +339,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 		it("should fire the whole-view observer with the new snapshot after a Store", function()
 			local dataStore = DataStore.new(DataStoreMock.new(), "player_1")
 
-			-- The initial emission of an empty store is nil, so count emissions (not value) to
-			-- confirm the Changed connection is established before we Store.
 			local emissions = 0
 			local captured
 			local sub = dataStore:Observe():Subscribe(function(snapshot)
@@ -404,7 +394,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 			local ok, list = promise:Yield()
 			expect(ok).toEqual(true)
 
-			-- Order is not guaranteed; compare as a set
 			local asSet = {}
 			for _, key in list do
 				asSet[key] = true
@@ -419,7 +408,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 		it("should stage the value whenever the ValueObject changes", function()
 			local dataStore = DataStore.new(DataStoreMock.new(), "player_1")
 
-			-- Ensure the stage is loaded before wiring up the value object
 			if not PromiseTestUtils.awaitSettled(dataStore:Load("level")) then
 				expect("hung").toEqual("settled")
 				return
@@ -428,7 +416,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 			local valueObject = ValueObject.new(0)
 			dataStore:StoreOnValueChange("level", valueObject)
 
-			-- Construction does not stage; a change does
 			valueObject.Value = 7
 
 			local promise = dataStore:LoadAll()
@@ -482,7 +469,6 @@ describe("DataStoreStage staging (through a DataStore root)", function()
 			local input = { count = 1 }
 			dataStore:Store("data", input)
 
-			-- Mutating the caller's table must not change the frozen staged copy
 			input.count = 999
 
 			local promise = dataStore:Load("data")

package/src/Server/PlayerDataStoreManager.RemovalCallbacks.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	How a misbehaving removing callback affects (a) whether the player's data is saved on leave, and
-	(b) whether the session lock is released. SaveAndCloseSession is what releases the lock, so when
-	it is skipped the departing session's lock lingers until it goes stale. Several of these are
-	genuine data-integrity failure modes, so pinning them documents the contract callers must honor.
-
 	@class PlayerDataStoreManager.RemovalCallbacks.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -32,7 +27,6 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 			local raw = controller.mock:GetRaw("user_1")
 			return raw ~= nil and raw.coins == 5
 		end, 10)).toEqual(true)
-		-- SaveAndCloseSession stripped the lock as it wrote.
 		expect(controller.mock:GetRaw("user_1").lock).toEqual(nil)
 
 		controller:destroy()
@@ -48,8 +42,6 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 			expect(controller.storeAndAwaitLock()).toEqual(true)
 			controller.manager:RemovePlayerDataStore(1)
 
-			-- The rejected callback short-circuits PromiseUtils.all before SaveAndCloseSession: coins are
-			-- never persisted, and the lock is never released.
 			expect(PromiseTestUtils.awaitValue(function()
 				local raw = controller.mock:GetRaw("user_1")
 				return raw ~= nil and raw.coins == 5
@@ -67,7 +59,6 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 
 			expect(controller.storeAndAwaitLock()).toEqual(true)
 
-			-- There is no pcall around removing callbacks, so a synchronous throw escapes removal entirely.
 			expect(function()
 				controller.manager:RemovePlayerDataStore(1)
 			end).toThrow("removing callback boom")
@@ -85,8 +76,6 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 			expect(controller.storeAndAwaitLock()).toEqual(true)
 			controller.manager:RemovePlayerDataStore(1)
 
-			-- SaveAndCloseSession is gated behind the yielding callback, so neither the save nor the lock
-			-- release ever happen.
 			expect(PromiseTestUtils.awaitValue(function()
 				local raw = controller.mock:GetRaw("user_1")
 				return raw ~= nil and raw.coins == 5

package/src/Server/PlayerDataStoreManager.lua

@@ -59,6 +59,7 @@ local BindToCloseService = require("BindToCloseService")
 local DataStore = require("DataStore")
 local Maid = require("Maid")
 local PendingPromiseTracker = require("PendingPromiseTracker")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local PromiseUtils = require("PromiseUtils")
 local ServiceBag = require("ServiceBag")
@@ -164,7 +165,11 @@ function PlayerDataStoreManager._flushAndDestroyAll(self: PlayerDataStoreManager
 		-- Cast past the DataStore intersection type: the solver otherwise blows up ("code too complex")
 		-- resolving :Save()/:Destroy() through it.
 		local store = datastore :: any
-		store:Save():Catch(function() end)
+		-- A failed load makes Save() reject unconditionally; skip it so teardown does not
+		-- manufacture a guaranteed rejection.
+		if not store:DidLoadFail() then
+			store:Save()
+		end
 		store:Destroy()
 		self._datastores[userId] = nil
 	end
@@ -290,13 +295,17 @@ function PlayerDataStoreManager._promiseWaitForRemoving(
 end
 
 function PlayerDataStoreManager:_toPlayerUserIdOrError(playerOrUserId: Player | PlayerUserId): PlayerUserId
-	if typeof(playerOrUserId) == "Instance" and playerOrUserId:IsA("Player") then
-		return playerOrUserId.UserId
-	elseif type(playerOrUserId) == "number" then
+	if type(playerOrUserId) == "number" then
 		return playerOrUserId :: PlayerUserId
-	else
-		error("Bad playerOrUserId")
 	end
+
+	assert(
+		typeof(playerOrUserId) == "Instance" and (playerOrUserId:IsA("Player") or PlayerMock.isMock(playerOrUserId)),
+		"Bad playerOrUserId"
+	)
+	return (
+		if PlayerMock.isMock(playerOrUserId) then PlayerMock.read(playerOrUserId, "UserId") else playerOrUserId.UserId
+	) :: PlayerUserId
 end
 
 --[=[

package/src/Server/PlayerDataStoreManager.spec.lua

@@ -1,23 +1,18 @@
 --!nonstrict
 --[[
-	Integration coverage for PlayerDataStoreManager against a mocked Roblox datastore. The manager
-	auto-enables session locking and session messaging on every DataStore it creates, so even a load
-	does an UpdateAsync round-trip through the mock. Tests use numeric userIds, never real Players.
-
 	@class PlayerDataStoreManager.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
 
 local DataStoreTestUtils = require("DataStoreTestUtils")
 local Jest = require("Jest")
+local PlayerMock = require("PlayerMock")
 local PromiseTestUtils = require("PromiseTestUtils")
 
 local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
 local it = Jest.Globals.it
 
--- Asserts the promise settled within the timeout and returns whether it is now safe to :Yield(), so
--- a hung promise fails the test instead of freezing the runner.
 local function expectSettled(promise, timeout: number?): boolean
 	local settled = PromiseTestUtils.awaitSettled(promise, timeout)
 	expect(settled).toEqual(true)
@@ -57,6 +52,44 @@ describe("PlayerDataStoreManager.GetDataStore", function()
 	end)
 end)
 
+describe("PlayerDataStoreManager PlayerMock support", function()
+	it("resolves a datastore for a PlayerMock keyed by its seeded UserId", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local player = PlayerMock.new({ UserId = 42 })
+		local dataStore = controller.manager:GetDataStore(player)
+		expect(dataStore).never.toBeNil()
+		expect((dataStore:GetKey())).toEqual("user_42")
+
+		player:Destroy()
+		controller:destroy()
+	end)
+
+	it("shares the same datastore between the mock and its numeric userId (unified state)", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local player = PlayerMock.new({ UserId = 42 })
+		local viaMock = controller.manager:GetDataStore(player)
+		local viaUserId = controller.manager:GetDataStore(42)
+		expect(viaMock).toEqual(viaUserId)
+
+		player:Destroy()
+		controller:destroy()
+	end)
+
+	it("rejects a plain Folder that is not a PlayerMock", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local folder = Instance.new("Folder")
+		expect(function()
+			controller.manager:GetDataStore(folder)
+		end).toThrow()
+
+		folder:Destroy()
+		controller:destroy()
+	end)
+end)
+
 describe("PlayerDataStoreManager.PromiseDataStore", function()
 	it("should resolve the datastore and load successfully against a healthy mock", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
@@ -89,11 +122,8 @@ describe("PlayerDataStoreManager persistence", function()
 		local dataStore = controller.manager:GetDataStore(1)
 		dataStore:Store("coins", 5)
 
-		-- Removal saves (SaveAndCloseSession) then closes the session, asynchronously.
 		controller.manager:RemovePlayerDataStore(1)
 
-		-- PromiseDataStore waits for the in-progress removal to finish before handing back a
-		-- fresh datastore for the same user.
 		local promise = controller.manager:PromiseDataStore(1)
 		if not expectSettled(promise, 10) then
 			controller:destroy()
@@ -128,7 +158,6 @@ describe("PlayerDataStoreManager.AddRemovingCallback", function()
 
 		controller.manager:GetDataStore(1)
 
-		-- Drain the removal to be sure the callback fired.
 		local promise = controller.manager:PromiseAllSaves()
 		if not expectSettled(promise, 10) then
 			controller:destroy()
@@ -172,7 +201,6 @@ describe("PlayerDataStoreManager teardown", function()
 
 		controller.manager:Destroy()
 
-		-- BaseObject.Destroy clears the metatable, so a torn-down store reads a nil metatable.
 		expect(getmetatable(dataStore)).toBeNil()
 
 		controller:destroy()
@@ -189,8 +217,6 @@ describe("PlayerDataStoreManager teardown", function()
 
 		dataStore:Store("coins", 5)
 
-		-- Destroy must fire a synchronous Save before tearing each store down, so the staged value is
-		-- already persisted the instant Destroy() returns -- asserted with no awaiting.
 		controller.manager:Destroy()
 
 		local raw = controller.mock:GetRaw("user_1")

package/src/Server/PlayerDataStoreService.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	Integration coverage for PlayerDataStoreService, the ServiceBag-driven wrapper around one
-	PlayerDataStoreManager, with the underlying datastore injected via the SetRobloxDataStore test
-	seam. The manager auto-enables session locking, so even a load does an UpdateAsync round-trip
-	through the mock. Tests use numeric userIds, never real Players.
-
 	@class PlayerDataStoreService.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -91,7 +86,6 @@ describe("PlayerDataStoreService configuration guards", function()
 	it("should throw when SetRobloxDataStore is called after the manager is built", function()
 		local controller = setup(DataStoreMock.new())
 
-		-- Building the manager (via PromiseDataStore) locks out further overrides.
 		local promise = controller.service:PromiseDataStore(1)
 		if not PromiseTestUtils.awaitSettled(promise, 10) then
 			expect("hung").toEqual("settled")
@@ -144,8 +138,6 @@ describe("PlayerDataStoreService failure handling", function()
 
 		local controller = setup(mock)
 
-		-- PromiseDataStore resolves synchronously; the session-locked load underneath is what must
-		-- settle rather than hang against a failing datastore.
 		local promise = controller.service:PromiseDataStore(1)
 		if not PromiseTestUtils.awaitSettled(promise, 10) then
 			expect("hung").toEqual("settled")
@@ -207,10 +199,8 @@ describe("PlayerDataStoreService teardown", function()
 
 		dataStore:Store("coins", 7)
 
-		-- Destroy must fire a synchronous Save before tearing the store down.
 		controller:destroy()
 
-		-- keyGenerator maps userId 1 -> "1"
 		local raw = controller.mock:GetRaw("1")
 		expect(raw).never.toBeNil()
 		expect(raw.coins).toEqual(7)

package/src/Server/PrivateServerDataStoreService.lua

@@ -64,8 +64,11 @@ function PrivateServerDataStoreService.PromiseDataStore(
 		-- On service teardown (hot reload / tests) flush and destroy the store. Save() is a best-effort
 		-- synchronous write before Destroy() cancels it.
 		self._maid:GiveTask(function()
-			-- Best-effort: swallow a rejection (e.g. the load failed) so it is not uncaught.
-			dataStore:Save():Catch(function() end)
+			-- A failed load makes Save() reject unconditionally; skip it so teardown does not
+			-- manufacture a guaranteed rejection.
+			if not dataStore:DidLoadFail() then
+				dataStore:Save()
+			end
 			dataStore:Destroy()
 		end)
 

package/src/Server/PrivateServerDataStoreService.spec.lua

@@ -1,10 +1,5 @@
 --!nonstrict
 --[[
-	Integration coverage for PrivateServerDataStoreService wired through a real ServiceBag, with the
-	underlying datastore injected via the SetRobloxDataStore test seam. It is not session-locking, so a
-	failing load rejects promptly rather than hanging. The datastore key defaults to "main" (or the
-	private-server id) unless a custom key is set via SetCustomKey before the datastore is resolved.
-
 	@class PrivateServerDataStoreService.spec.lua
 ]]
 local require = require(script.Parent.loader).load(script)
@@ -123,7 +118,6 @@ describe("PrivateServerDataStoreService persistence", function()
 		end
 		expect((savePromise:Yield())).toEqual(true)
 
-		-- Non-session-locking, so the raw persisted value is the plain data table.
 		local raw = controller.mock:GetRaw(key)
 		expect(raw).never.toBeNil()
 		expect(raw.motd).toEqual("hello")
@@ -146,7 +140,6 @@ describe("PrivateServerDataStoreService.SetRobloxDataStore", function()
 	it("should throw on a non-datastore argument", function()
 		local controller = setup()
 
-		-- isDataStore is validated before the already-resolved check, so a bad arg throws regardless.
 		expect(function()
 			controller.service:SetRobloxDataStore({})
 		end).toThrow("Bad robloxDataStore")
@@ -176,7 +169,6 @@ describe("PrivateServerDataStoreService failure handling", function()
 		local ok, dataStore = promise:Yield()
 		expect(ok).toEqual(true)
 
-		-- Non-session-locking: a failing load rejects promptly, so this settles false rather than hanging.
 		local loadPromise = dataStore:PromiseLoadSuccessful()
 		if not PromiseTestUtils.awaitSettled(loadPromise, 5) then
 			expect("hung").toEqual("settled")
@@ -232,7 +224,6 @@ describe("PrivateServerDataStoreService teardown", function()
 		local key = dataStore:GetKey()
 		dataStore:Store("region", "us")
 
-		-- Destroy must fire a synchronous Save before tearing the store down.
 		controller:destroy()
 
 		local raw = controller.mock:GetRaw(key)