Changelog
Changelog
Every release is listed here, newest first. The format follows Keep a Changelog, and versions follow semantic versioning.
Unreleased
0.9.7 - 2026-11-06
A maintenance release. The library, its API and the on-disk format are those of 0.9.6.
Changed
- Tests and benchmarks run on LuneBlox 0.11.4, from 0.11.3. The update preserves numeric Roblox
attributes as Float64, fixes empty-model DOM cleanup, backports a conditional-spill codegen fix and
refreshes fast flags against the Roblox client. Luau remains at 0.740; the
@lunetypedef alias follows the runtime. - Documentation dependencies are refreshed to Astro 7.4.7, Starlight 0.42.9 and the pinned
postcss-selector-parseroverride 7.1.7. The optional macOS watcher uses its shipped binary; its unneeded install hook is explicitly denied in npm’s install-script policy.
0.9.6 - 2026-10-29
The API and the on-disk format are those of 0.9.5.
Fixed
- A release whose write landed but answered with an error ended the session as lost. Roblox can
store a write and still fail the call (a 502 after the commit, or an answer slower than
callTimeout). The release tries again, and its retry found the key already let go by that very try, so it reportedonEnded("lost"), though the data was stored and no other server held the key. During a data store outage every such release raised a loss a game alerts on. A release that finds the key let go by its own session (no active session, its own load count and owner) now writes nothing and ends asreleased; a key another server took meanwhile still ends aslost.
0.9.5 - 2026-10-29
The API and the on-disk format are those of 0.9.4.
Fixed
- A message sent from another server still wrote its key twice within a second or two. The sender writes the key to queue the message and tells the owner, whose save that takes it in waited the write spacing only from its own last write, long before: so it wrote right after the sender, and Roblox queued the write with its warning “DataStore request was added to queue”. The owner now counts the sender’s write as the key’s last one, and the save waits the spacing from it. A message from another server is handled a spacing later than before (about 7 s instead of 1 to 2 s).
0.9.4 - 2026-10-27
A maintenance release. The library, its API and the on-disk format are those of 0.9.3.
Changed
- Tests and benchmarks run on LuneBlox 0.11.3, from 0.11.2. The update brings compression
security fixes, reverse Roblox property migrations and optional OCALE conformance tooling. The
@lunetypedef alias follows it.
0.9.3 - 2026-10-25
A session no longer writes its key faster than Roblox takes writes to one key, and a load that waits for a key no longer writes its request again at every poll. The API is unchanged, but for one new setting.
Fixed
- A message sent to a profile open on the same server wrote its key three times in two seconds.
Roblox takes one write to a key about every 6 seconds and queues the rest, warning “DataStore request
was added to queue. If request queue fills, further requests will be dropped.” Seen in a live game:
store:messagewrote the key, the session saved a second later to take the message in, and saved again a second after that to store what its handler did. Nothing kept the session’s writes apart but the spacing by data size, which a processed message skips. Now a write that can wait (a renewal, or the save a message or a returning beat asks for) leaveswriteSpacingseconds after this server’s last write of the key: the claim, a save, or a message sent from here. Whatever asks meanwhile goes in the same write. So that message makes three writes 6 s apart, and a message waiting when the key is loaded is stored 6 s after the claim. - A load waiting for a key wrote its hand-over request at every poll, every half second while the owner hands over and for as long as a dead owner’s beat is watched: ten more writes of the key while waiting on a dead owner. A poll that finds this server’s request still standing now writes nothing; one a third server replaced writes it again, as before.
Added
writeSpacing(default 6) inconfig. It must not exceedrenew, so a renewal it holds off can never let a live owner’s lease look dead.
Changed
- These do not wait for the spacing, as a write that cannot: the release (shutdown has its deadline,
and a newcomer may be waiting),
profile:save()andstore:editon an open profile (the game asked for the write now), a purchase (its receipt is answered only once stored), and the write that stops the record vouching for a beat that no longer lands, which must land before a newcomer could judge the beat dead. Roblox queues one of them when it comes too soon; it is not dropped. - A hand-over now takes one more poll, about half a second, where a poll used to land as the claim the moment the owner let go: its write found the key changed and ran again.
Tests
- 7 new specs (
tests/unit/Spacing.luau,tests/unit/Lock.luau) and one extended (tests/unit/Store.luau), 507 in all: messages sent and processed where the key is held write it at leastwriteSpacingapart, are delivered once and stored with their effect, and two sends a second apart are taken in and stored by one write each; beside it, with a spacing of half a second the same writes come within two seconds. A save the game asks for and a release go at once; a message waiting at the load is stored a spacing after the claim; an owner whose beats hang stops vouching for them at once though it just wrote, over eight seeds, and one whose beats land writes nothing more while the spacing lasts. A standing request is not written again; one a third server replaced is. A spacing overrenewis refused, and one at it taken. - Three specs wait for the spacing now: a message to an offline key is stored a spacing after the load, the owner on another server hears of a message once the claim’s spacing has passed, and a load’s costs count the hand-over’s extra poll and the waiting load’s writes (13 down to 3).
- 7 mutants (
tests/MutantsSpacing.luau), each seen failing the suite.
0.9.2 - 2026-10-25
A toolchain release. The package’s code is 0.9.1’s: nothing in src/ changes.
Changed
- Tests run on LuneBlox 0.11.2, up from 0.11.1. It sets the fast flags of the Roblox client 0.744,
which turned
DebugCodegenOptSizeoff, so native code gets block linearisation back; Luau itself is the same. Its macOS binaries are built with Apple Clang 21, where 0.11.1’s, from Clang 17, interpreted about 30% slower than the same source allows. The benchmark tables count bytes and data store requests, not CPU time, so neither change touches them, and they are not measured again. - The documentation site is built with Astro 7.4.2 and Starlight 0.42.7, from 7.4.1 and 0.42.6. Every other tool, package and CI action was already at its latest release.
0.9.1 - 2026-10-25
A toolchain release. The package’s code is 0.9.0’s: nothing in src/ changes.
Changed
- Tests run on LuneBlox 0.11.1, up from 0.10.18. It runs the same Luau and fast flags as before;
between the two, 0.10.19 fixed
net’s certificate checks, 0.11.0 made Roblox’sEnuma global, and 0.11.1 keepsluneblox setupfrom puttingEnumandwarnin.luaurc’sglobals, where luau-lsp would type them asanyover the Roblox definitions. Every other tool and CI action was already at its latest release.
0.9.0 - 2026-10-25
Tallies: counts every server adds to, summed across the whole game and read back by every server, without one key taking every server’s writes. Nothing that existed changes.
Added
KeepBlox.tally(name, options?)opens a tally (Tally).add(key, amount)counts at once on this server and never yields;total(key)is every server’s count as last read with this server’s adds since, and never yields;read(key)reads it now;flush()writes now;watch(key, handler)reads at once and everyintervalwhile watched, and calls the handler when the total changes.- A count is spread over
shardskeys ("<key>/1"to"<key>/<shards>", default 8). Each server writes one of them, everyintervalseconds (default 60), everything added meanwhile as one batch in one UpdateAsync. A batch lands once though its call is tried again or lands late: each shard keeps the serial of each server’s last batch, forgottenrememberseconds after that server’s last write there (default a day), and a batch seen to land by a read is not written again (TallyShard,TallyCount). - A turn writes nothing while fewer than
reservestandard writes are left in the server’s budget, and reads nothing while fewer thanshards + reservereads are (default 10). A server that closes writes its batches first, withinshutdownDeadline. - A new
onErrorkind,"tally": a batch not written, a watched key not read, or a shard holding a value that is not a tally’s (left as it is, and counted by no one). - roblox-ts declarations for all of it, and the guide “Tallies”.
Tests
- 18 specs (
tests/unit/Tally.luau,tests/unit/TallyRace.luau): adds summed for every server, a server’s own at once; one write a turn whatever the number of adds; watchers told after the first read, on each change and not after they leave; the shutdown’s writes and a crash’s loss; the budget’s reserve; a batch that landed and failed, that was held past its timeout, or that a read settled, counted once; a try run after its entry was forgotten; an older answer not taken over a newer one; a foreign shard; six servers on one shard over six seeds; the shard’s format and the spread of servers. - 13 mutants (
tests/MutantsTally.luau), each failing those specs. - The standard data store fake can now hold a read’s answer
afterthe read, as it holds a write’s.
0.8.0 - 2026-10-24
Scheduled jobs: work due at a time, kept in a data store and run by whichever server sweeps first once its time has come, whether or not its player is in the game. Nothing that existed changes.
Added
KeepBlox.schedule(name, options?)opens a schedule (Schedule): one job a key,{ due, data }withduein whole Unix seconds.put,removeandupdatechange a key’s job in one UpdateAsync, each landing once though its call is tried again (as a shared update does);readgives it back.schedule:sweep(handler, options?)reads the keys due now from an ordered data store beside the jobs (<name>_due), takes each with a claim (claimseconds, default 120) so one server holds it, and runshandler(key, job), which may yield. It answers nil (done), a job to keep, or false to leave it; a game’s change made while it ran wins over its answer. A job no sweep finished forkeepseconds past its time (default a day) is dropped. A sweep stops while fewer thanreservestandard writes are left in the server’s budget (default 20), and returns what it did by key.- The index is never written blind: while a key holds a job its second is no later than the job’s
time, through any interleaving of servers. An update only lowers it; a sweep moves it only from the
second it saw, then reads the record again (
JobIndex). - A new
onErrorkind,"schedule": a job stored but not indexed, or a handler that threw. - roblox-ts declarations for all of it, and the guide “Scheduled jobs”.
Tests
- 13 specs (
tests/unit/Schedule.luau,tests/unit/ScheduleRace.luau): a job run once its time has come, kept, left or thrown, moved later, removed, dropped, refused; three servers sweeping at once run each job once; a dead server’s job is run by another once its claim expires; a game’s change wins over a handler’s answer; the budget’s reserve; a put whose call landed and failed lands once; a job put while a sweep parks its key is found. - 10 mutants (
tests/MutantsSchedule.luau), each failing those specs. - The ordered data store fake now holds a request for a fault’s
delayand serves it on what is stored by then, as the standard store’s fake does.
0.7.0 - 2026-10-21
Leaderboards that start again every period, the entry just above a value, and reads that answer from their last answer while the ordered list budget is spent. Existing boards and their stores are unchanged.
Added
- A board with a period. A board can be
{ read = function(data, period) ... end, period = { length = seconds, origin = unixTime? } }: one ordered data store a period,"<store>__<board>_<n>", wherencounts whole periods fromorigin(default 0) by the server’s wall clock. A weekly board from Monday 00:00 UTC is{ length = 604800, origin = 345600 }.readis told the period it is read for, so a game can return nil for a count it has not yet started again. The first write of a new period is made whatever the last period held. store:leaderboard(name, { period = n })reads a past (or any) period of such a board; the current one is read by default.store:leaderboardPeriod(name)gives the current period, nil for a board without one.store:leaderboardAbove(name, value, query?): the entry nearest abovevalue, the lowest one higher than it (GetSortedAsync(true, 1, floor(value) + 1)), or nil at the top. Answers are kept forcacheseconds, asleaderboard’s are, and let go once older.
Changed
- A read with the ordered list budget spent no longer calls
GetSortedAsync. It answers with the last answer to the same query, however old, and raises"the ordered list budget is spent"when there is none. Before, the call was made and Roblox queued or refused it. - Built and checked with LuneBlox 0.10.18, StyLua 2.6.0 and lefthook 2.2.2; the documentation site with Astro 7.4.1.
0.6.14 - 2026-10-21
A player who leaves while their load is in flight and joins the same server again is no longer told
"open", and gets their profile sooner than any release and new claim could give it. The API is
unchanged.
Fixed
- A quick rejoin during the load was told
"open". A load waited before claiming only for a session being released, or for an earlier load whose caller’s thread was dead. An earlier load whose player had left (itscancelanswering true) but which still stood inside a data store call (up tocallTimeout, and longer while the store answered errors) was not waited for, so the player’s new load got"open"and the game kicked them. Seen in a live game, on a server whereUpdateAsyncanswered 502s. Now every later load waits while a load for a caller who is gone is in flight.
Changed
- The earlier load hands its session to the rejoin. The first later load that waits is the earlier
load’s heir: the earlier load no longer gives up on its
cancelwhile the heir waits, goes on to open the session, and hands it over; its own caller gets"cancelled". One claim in all, nothing released and claimed again, and the rejoin answers within 0.1 s of the earlier load’s end. Before, a rejoin after a cancelled thread waited for a release, then made a claim of its own: two more data store writes, each up tocallTimeout. When the earlier load opens nothing, or the heir leaves too, the key is given back as before and the next load claims it afresh. - A second load while the first load’s player is still there gets
"open"at once, as before.
0.6.13 - 2026-10-17
A refusal stays a refusal, and a transform that throws is a failed write. Two gaps 0.6.12 left open, found by reading Ledger’s “safe datastores” notes and checked against Roblox. The API is unchanged.
Fixed
- A shared
updatecould land after the game was told it did not. Its first try waited past the call’s deadline, the retry found thatchangerefused ("error"or"refused"), and the game got that answer; then the first try ran on newer data and applied the change. A refusal found by a retry is now stored with the update’s id inMetaData.KeepBlox.refused({ id, at, { reason, message } }, the message cut to 200 characters), so the late try finds it and changes nothing; a retry that finds it answers the same refusal. A refusal on the first try writes nothing, as before. store:messagecould queue a message after it answered"full", the same way. A retry that finds the queue full stores the send’s id inGlobalUpdates[4].- A transform that throws was read as “nothing to write”. On Roblox UpdateAsync does not fail when
its transform throws or yields: it logs “Transform function error” and answers
nil, nil, writing nothing (checked live on 2026-10-16, for a string, a table anderror(x, 0), on a missing key and a stored one; MemoryStore’s UpdateAsync does fail, with “TransformCallbackFailed”). Every lock-guarded write now goes throughCall.update, which checks that its transform finished and turns one that did not into a failed write. The fakes copy the engine: the data store fake used to throw.
Compatibility
- ProfileStore and KeepBlox 0.6.12 keep
MetaData.KeepBlox.refusedandGlobalUpdates[4]and ignore them; their own retries are as safe as before.
0.6.12 - 2026-10-16
A change lands once, though its call is tried again
(#41). A data store call that fails or times out
may still have gone through (“a failed write does not always guarantee that the backend write did not
occur”), and a call the library stops waiting for keeps running in the engine and can land later. A
shared document’s update retried such a call, so data.bank += 100 could land twice, and
store:message could queue one message twice. The same late landing could also put a session’s older
save over a newer one, start a load’s session over, take back a key its load had let go, or put an
older heartbeat snapshot over a newer one. The API is unchanged; the record gains three small fields
that ProfileStore and KeepBlox 0.6.11 neither read nor drop, so they run side by side with 0.6.12.
Fixed
- A shared document’s
updatecould apply its change twice when a try failed or timed out after its write landed. Every update now takes one id for all its tries, stored inMetaData.KeepBlox.appliedby the write that makes the change; a try that finds its id changes nothing and returns the data as stored. A try that runs more thanloadTimeout + callTimeoutseconds after the update started changes nothing at all.{ ok = false, reason = "failed" }still means the change may have landed, but only once. store:messagecould queue a message twice, the same way. Every send carries one id for its tries, stored beside the queue inGlobalUpdates[3]; the message table is stored exactly as given.- A save that timed out could land after a newer one and put older data, an older receipt list and
an older message queue back until the next save. Every lock-guarded write (a session’s save, a
trade’s write, the store of a dead owner’s last beat, a give-back) now carries a stamp that only
grows on a server, kept as
MetaData.KeepBlox.fence = { loadCount, stamp }; a write whose stamp is not above the stored one for its load writes nothing. - A claim that timed out and landed after its retry started the load’s session over: it moved the
load count, and the session’s next save found itself lost. A claim that finds the key held by its
own load (the same GUID) now writes nothing and answers as that load’s claim did, recovering from
the same previous owner (noted in
MetaData.KeepBlox.fromuntil the load’s first save). One that lands after its load let the key go takes nothing, where it used to hold the key for nobody. - A heartbeat that landed late could put older snapshots over newer ones in MemoryStore. Each
store’s beat now carries a stamp (
kin the server’s entry), and a beat older than the stored one writes nothing.
Bounds
- An id list holds at most 100 ids (
Once.KEEP), and forgets each oneloadTimeout + callTimeout + 600seconds (740 s by default) after its call started, by the clock of the server that writes next. The 600 s cover servers whose clocks disagree. So a change lands once while fewer than 100 other changes of the same key land while it is still being tried. Each id costs about 50 bytes.
Compatibility
- ProfileStore keeps
MetaData.KeepBloxwhen it rewrites a key, and reads only the first two elements ofGlobalUpdates, writing the table back as it found it: messages sent by KeepBlox are delivered by ProfileStore as before, and the list of ids stays. A game can still switch back. - KeepBlox 0.6.11 keeps the new fields too, and ignores them: a 0.6.11 server neither checks ids nor fences its saves, so during a rollout its own calls are as safe as before and no safer.
Added
src/Once.luau: the ids, their bounds and the stamps.src/LockTypes.luau: the lock’s types, moved out ofsrc/Lock.luauto keep it under 300 lines.- A fault the harness lacked: a call held for
delayseconds that then runs, before its read (a request queued past its caller’s deadline, which runs late on whatever is stored by then) or after its write (it landed, and answers late). The data store and MemoryStore fakes both have it. - Specs:
tests/unit/Once.luauandtests/unit/OnceLate.luau, each fault beside a genuine failure that is retried and lands once, and beside a second change that must land too; all failed on 0.6.11 (bank 200 for 100, two messages for one, 1 coin stored over 2, a lost session, a key held for nobody, the older snapshot recovered).tests/unit/Owed.luauandtests/unit/Fencing.luaunow give each load its own GUID, as loads have, and check a claim tried again after it landed. 450 specs. - 16 mutants (
tests/MutantsOnce.luau) on the new guards; 173 in all.
0.6.11 - 2026-10-16
onError says what a problem is about. A listener used to get (key, message), and the message is
prose that often names the key (for most games a user id): a game could put neither in an analytics
row, and could not tell a failed save from a failed leaderboard write or a grant that threw without
parsing it. Now every report carries a third argument, kind, one word of a fixed list with no key or
id in it. Nothing about stored data, the lock protocol, the messages or the requests changed: 0.6.10
and 0.6.11 servers run side by side.
Added
onErrorfires(key, message, kind), on a profile store and on a shared store.kindis one of"save","refused","repair","load","migration","release","snapshot","quarantine","leaderboard","receipt","message","import"and"studio"; the store reference says what each means. Each report of the library names exactly one. A kind is added only in a release that says so here; none is renamed or removed.KeepBlox.ErrorKind, the type of that list, and the same in the roblox-ts declarations.src/Report.luau: the list, and the type of the function every report goes through. That function takes the kind as a required argument, so a report that leaves it out, or names a word not on the list, fails the type gate.- Specs: every report a spec already makes is now checked with its kind (the listeners record
<key>: <message> [<kind>]), andtests/unit/ErrorKinds.luaumakes the ones no spec made (a quarantined value, a grant that throws, a message refused, not sent or whose handler throws, a board not written, a failed read of the old store), each beside the same call when nothing goes wrong, and a listener of two arguments beside one of three.tests/unit/Typings.luauholds the roblox-ts list to the Luau one. 431 specs. - 29 mutants (
tests/MutantsKinds.luau), one a report, each swapping its kind for another; 157 in all. tests/consumer: a listener of three arguments under both solvers, and a kind of the wrong type refused under both.
Compatibility
- A listener of two arguments keeps working, in Luau (either type solver) and in roblox-ts: the third argument is extra. The messages are as they were.
0.6.10 - 2026-10-10
The loose ends of giving a key back. A dead owner’s last heartbeat is no longer lost when the load
that took its key could not store it, and a key a live server holds with no session is no longer
handed to nobody. Stored data, the lock protocol, the messages and what a load nobody stops spends
are as in 0.6.9, and the two run side by side. The one addition to the record is a note under
MetaData.KeepBlox.owed, which ProfileStore and an older KeepBlox neither read nor clear.
Fixed
- A key given back lost its dead owner’s last heartbeat when this server could not store it (#36): the beat held edits against a compressed record and this server has no codec, the data store took no write of it, or MemoryStore gave no answer about it. The key was freed, and a free key has no previous owner to recover from. Now the write that frees the key leaves a note of that owner in the record, and the next load recovers from it as if it had taken the key from the dead server itself. The note counts only while the key’s load count is the one it was left at, so a session that played since (on any library) is never written over by an older beat; a restore of the key drops it.
- The same for the session of a load nobody holds (its caller was cancelled, or the store was closing): its release leaves the note when the load could not store the beat.
- A load that failed after its beat could not be stored (a migration that fails, a schema the data does not fit) gave the key back without trying the beat again. Now the undoing tries it once more, against the data as claimed.
- A key a live server held with no session was handed to nobody for as long as that server lived
(#37): its beat moves, so no newcomer judges it
dead, and it dropped the hand-over request for a key it had no session for. Now such a request
frees the key, if the record still names this server at the load count the request names and the
store is not loading the key: one
UpdateAsync, reported (“a key held with no session was freed for the server asking for it”), and only on that path. A request for a session the store released itself costs nothing, as before. - Letting go of a key a load may have taken unanswered was one silent try (#37). Now it is tried
again with the load’s backoff, for
loadTimeoutof its own, never at a budget that leaves saves less than their reserve, and a key that could not be let go of is reported. - A
cancelthat throws before the claim landed ended the load where it stood (#37): its hand-over listener stayed subscribed, and a claim that had gone unanswered was not let go of. Now a throw ends the load as an answer oftruedoes, wherever the load stood, and then the error goes on to the caller as before. - A release that throws in a load nobody holds left the session listed with nobody to release it before shutdown (#37). Now it is reported and tried again with the backoff until it lands.
Compatibility
- With 0.6.9 and older, and with ProfileStore: the note is one more field under
MetaData.KeepBlox, written only by a give-back that owes a beat. A server that does not know it loads the key as it always did (the beat is then lost, as before 0.6.10), and leaves the note where it is: its load moved the count, so the note is void, and the next 0.6.10 claim clears it. - A hand-over request that names no load count (an older KeepBlox wrote those) never frees a key.
0.6.9 - 2026-10-10
What a load took it now either keeps, with everything it read, or gives back whole. A load that gives up, fails or throws no longer drops play that only a dead owner’s last heartbeat held, and no longer leaves its key held by a server that has no session for it. Nothing about stored data, the lock payload, the keys, the messages or the number of requests changed for a load nobody stops: 0.6.8 and 0.6.9 servers run side by side, and each reads what the other stored.
Fixed
- A load that gave up as its takeover of a dead owner’s key landed lost that owner’s last
heartbeat (#33): the play since its last data store
write, up to
renewseconds. The load gives up there when itscancelturns true (the player left again) or its server begins to close while that one claim is on its way. The key was freed as it was claimed, and the next load found a free key with nobody to recover from. Now the beat is stored first (the same write a load that goes on makes), then the key is freed. - A load whose claim had landed when the shutdown began answered
ok, and the shutdown, which had listed its sessions before, never released that one (#34): the key stayed held until the next server found this one dead. Now the load releases the session itself, with a final save of all it read, and the shutdown waits for that as it waits for the others. - A load that threw past its claim left the key held (#34), and on a server that lived on it was
handed to nobody: a newcomer sees a live owner and waits. Now the key is given back before the error
goes on, with a dead owner’s last beat stored first. The same for a
cancelfunction that throws as the claim lands. - A give-back the data store refused was one silent try. Now each refusal is reported (“a key its load gave up was not given back: …”) and the write is tried again with the load’s backoff, until the load’s own deadline.
- A dead owner’s whole last beat is stored without reading the record it replaces, so a server that cannot decompress that record no longer throws on it: the load answers with the beat’s data.
Changed
- A load that finds its store closing once its session is made answers
"closing", notok. A load whose claim landed after the shutdown began always answered"closing"; the one whose claim landed just before it now does too. No game ever held the profile it used to get, so noonSavingoronEndedof it is heard. - A load that gives up as its takeover lands spends one MemoryStore read more (the dead owner’s
beat), and one data store write more when that beat is newer than the record. A load that
throws inside that recovery spends them again. No other path spends a request it did not: a load
nobody stops, a give-up on a key that was free or handed over, and a give-back the store takes at
once cost exactly what they did (
tests/unit/LoadGivesBack.luauholds the numbers, read from 0.6.8’s sources). - A give-back that is refused keeps its load from answering until it lands or
loadTimeoutis over, and a shutdown waits for it withinshutdownDeadline. Before, the load answered after one try. - Speed is unchanged: a load and a release on the simulator read 417 and 416 microseconds before and
after (medians of seven alternated runs, one of them noisy on both sides), and
scripts/run-bench.shreads the same (it does not go through a load). - The tools the repository checks itself with are the newest releases: LuneBlox 0.10.16, which runs
the specs and the benchmarks, lefthook 2.2.1 and
actions/setup-node7.1.0. The documentation site is built with Astro 7.3.8, Starlight 0.42.6 and starlight-links-validator 0.27.0, and withpostcss-selector-parser7.1.6, which fixes a selector that could cost quadratic time to parse; the parser runs when the site is built and was never part of the library.
Added
src/Enter.luau: the half of a load past its claim, moved out ofOpen.luau, which now undoes whatever fails or throws there.- Specs through the real paths (
tests/unit/LoadGivesUp.luau,LoadGivesBack.luau,LoadThrows.luau): the load’scancelturned true, and its store closed, at every step the world takes while it runs, in five scenes (a new key, a live hand-over, a dead owner with newer play in its last beat, an imported key, an unfinished trade), each followed by another server that must get the key in time and read exactly what was played; a throw at every seam call past the claim in the same scenes; the requests of each give-back, one by one. 401 specs. - 18 mutants (
tests/MutantsGiveBack.luau), 101 in all.
Not fixed
- A last beat this server cannot store is still lost when the key is given back
(#36): a beat of edits against a compressed record
on a server with no codec (reported through
store.onError), or a data store that refuses the beat’s write for the whole load, as for a load that goes on. Keeping it needs a change to what other servers read, which is its own decision. - There is no backstop for a key a live server holds with no session, should one still be left
(a give-back refused for all of
loadTimeout); a claim that went unanswered is disowned in one silent try; acancelthat throws before the claim lands still ends the load where it stood (#37).
0.6.8 - 2026-10-10
A game may now cancel a thread that is inside store:load or profile:release(): both run in a thread
the library owns, and the caller only waits. Nothing about stored data, the lock payload, the keys,
the messages or the number of requests changed for a caller nobody cancels: 0.6.7 and 0.6.8 servers
run side by side, and each reads what the other stored.
Fixed
- A thread cancelled inside
store:loadno longer leaves its key marked as opening (#31). Before, every later load of that key on that server answered"open"until the server ended, and a claim that had already landed left the key held with no session behind it. Now the load runs to its end without its caller. A session it opens, which nobody is left to hold, is released at once with a final save of everything the load read (a dead owner’s last beat, a settled trade, migrated data), and the key comes free. - A thread cancelled inside
profile:release()no longer stops the retries of the final write (#31). Before, a write that failed after the cancel was not tried again until something else called the release, so the session stayed half ended and the key held. Now it is retried with the same backoff as when the caller waits, and the key comes free with nobody callingreleaseagain. - A load that throws no longer leaves its key marked as opening either (a compressed profile on a server that cannot decompress, for one). The claim it had made is still not given back: see #34.
Changed
- A
store:loadof a key whose earlier load was cut short by a cancelled thread waits for that load to be undone, then claims the key afresh, as it already did for a release still in flight. The wait is the load’s own: it ends oncancel, on shutdown and atloadTimeout. A second load of a key while the first is in flight with its caller still there gets"open"at once, as before. - A cancelled thread does not make a load give up: it runs on as if its caller were there (up to
loadTimeoutwhen the key is held elsewhere), and what it opens is released. To stop a load early, passcancel, as before. - Shutdown waits for a load in flight, whoever started it, as well as for the open sessions,
within the same
shutdownDeadline. Such a load answers"closing"at its next look and gives back what it took; before,store:close()and the server’s close could return while that give-back was still on its way. With no load in flight the close takes the time it took. - A load or a release that throws after its caller was cancelled is reported through
store.onError(“a load failed after its caller was cancelled: …”, “a release failed after …”). With its caller still there the error reaches that caller exactly as before. - Each load and each release costs one more thread: about 2.2 microseconds on LuneBlox for a call that
parks once (1.39 to 3.55, best of seven, three runs), about 1.4 for one that returns at once. A whole
load and release on the simulator read 496 and 493 microseconds before and after (medians of five
alternated runs, two of them noisy; best runs 460 and 475). Either is one data store request at the
least.
scripts/run-bench.sh(the frame cost of a save) does not go through these paths and reads the same before and after.
Added
src/Apart.luau(a call run in a thread of its own, its caller only waiting) andsrc/Settle.luau(the wait before a key is loaded again, moved out ofOpen.luauand widened).- Specs through the real paths (
tests/unit/CancelledLoad.luau,CancelledLoadPaths.luau,CancelledRelease.luau,Apart.luau): the caller of a load cancelled at every step the world takes while the load runs, for a new key, a key handed over by a live server, a key taken from a dead one with newer play in its last beat, an imported key and a key with an unfinished trade; after each cancel the key is loaded again at once, or left alone for half a minute, or the server is shut down, and each time the key is not left held, the next load gets a session with exact coins and nothing is reported. The caller of a release cancelled at every step with its write failing once, and with its write lost in flight; the same backoff with a caller and without; a load and a release that throw, heard by the caller or by the store; shutdown with a cancelled load or release in flight; and loads and releases nobody cancels, whose answers, order and request counts are pinned. Thirteen mutants (tests/MutantsApart.luau).
Known, not fixed
- A load that gives up through
cancelor shutdown at the moment its takeover claim lands gives the key back without the dead owner’s last beat (#33). Older than this release, and not reachable through a cancelled thread: that load runs on and stores the beat. - A load whose claim had landed when shutdown began still answers with a profile, and the shutdown does not release it; a load that throws after its claim leaves the key held (#34). Both older than this release.
Checked on Roblox, and not
- That a cancelled thread reads as dead was run in Roblox Studio (the test place, edit mode,
2026-10-10): a thread parked in
coroutine.yield()or intask.waitreads"dead"aftertask.cancel, and aftercoroutine.close; a caller seen from the thread it spawned reads"normal". 0.6.7 had this from LuneBlox only. The fix rests on it in two places: to pass a dead caller over instead of waking it, and to know that the session a load opened has nobody to hold it. - The library itself was not run in a Roblox server for this release: the specs run on LuneBlox.
0.6.7 - 2026-10-09
A game may now cancel a thread that is inside profile:save(): every write runs in a thread the
library owns, and the caller only waits for it. Nothing about stored data, the lock protocol, the
keys, the messages or the number of requests changed: 0.6.6 and 0.6.7 servers run side by side, and
each reads what the other stored.
Fixed
- A thread cancelled while its write is in flight no longer takes the session’s write lane with it (#29). Before, the lane stayed taken for good: every later save, every renewal and the release queued behind it in silence, and the key came free only when its lease was judged dead. Now the write ends as it would have (it lands, fails or times out), the lane passes on, and shutdown waits for it as for any other write.
- A thread cancelled while it owns a queued manual save no longer leaves later
profile:save()calls waiting forever (#29). The shared save runs in its turn, the callers that joined it get their answer, and the next manual save gets a write of its own. Studio.guard’s one-time access check uses the same lane, so a cancelled first caller no longer leaves every later call of the store waiting on a check that never ends. (Proven by the lane’s specs; the guard has no cancel spec of its own.)
Changed
- A save or release whose caller was cancelled while it waited in the lane is now written in its turn. In 0.6.6 it was skipped. The request is the one the caller asked for, not an extra one; what is stored is the profile’s data at that moment, as for any save.
- A write that throws after its caller was cancelled is reported through
store.onError(“a write failed after its caller was cancelled: …”). A write that throws with its caller still there reaches that caller exactly as before, and one that only fails (save failed: ...) is reported as before either way. - Each write costs one more thread: about 1.1 microseconds on LuneBlox for a call that never yields
(0.31 to 1.45), about 1.7 for one that parks once (1.72 to 3.43), medians of five alternated runs. A
write is a data store request and about 370 microseconds of checking for a 10 KB profile, once every
renewseconds a profile;scripts/run-bench.sh(the frame cost of a save) does not go through the lane and reads the same before and after.
Added
- Specs through the real paths (
tests/unit/Cancelled.luau,CancelledErrors.luau, and the lane’s own intests/unit/Serial.luau): a manual save cancelled in mid-write, and one cancelled while queued, each followed by a manual save, a renewal and a release that store exact values; a lost request whose caller was cancelled, ended by the call’s deadline; shutdown with such a write in flight, which returns only after it and the final save have landed, in order; a write that fails and one that throws, heard by the caller, by those who joined and by the store; and callers nobody cancels, whose answers, order and request count are pinned. Eleven mutants (tests/MutantsLane.luau).
Not checked on Roblox
- That
task.cancelleaves a thread parked incoroutine.yield()dead (coroutine.statusreads"dead", and the thread never runs again) is measured on LuneBlox 0.10.13, which runs the same Luau, and is what Roblox documents fortask.cancel. It was not run in a Roblox server. The fix does not rest on it for the lane: the write no longer runs in the cancelled thread at all. It rests on it only to pass a dead caller over instead of waking it. - The cancel specs run in the simulator, not in
tests/live.
Not done
- Two other calls still do their work in the caller’s own thread
(#31). A thread cancelled inside
store:loadleaves the key marked as opening on that server, so later loads of it answer"open". A thread cancelled insideprofile:release()gets its final write in flight landed, but if that write fails nobody retries until the release is called again or the server shuts down. Do not cancel a thread that is insidestore:loadorprofile:release.
0.6.6 - 2026-10-09
Fixes for a cancelled caller and a failed hand-over subscription, and one walk of the data less at every beat. Nothing about stored data or the lock protocol changed: 0.6.5 and 0.6.6 servers run side by side, and each reads what the other stored.
Fixed
- A session’s write lane no longer sticks when the game cancels a thread that was queued in it (a
task.cancelon a thread whoseprofile:savewas waiting for a write in flight to finish). The dead caller is skipped; before, every later save and the release queued behind it forever, silently. A caller that joined a manual save and was cancelled meanwhile is passed over too, so the others still get their answer. - A hand-over subscription that fails is retried with a backoff (from 1 s, doubling up to 30 s) until
the session ends. Before, the session lived on without its listener, and a hand-over surfaced only
at the owner’s next write: up to
renewseconds late instead of about a second. Signal.disconnectnow drops the listener: a long-lived signal (a store’sonError) no longer keeps every connection ever made, and a fire copies only the listeners still connected. A seconddisconnectdoes nothing.
Changed
- A heartbeat snapshot and the packing of a profile no longer walk the data a second time: the check before a write now reports itself whether the data holds a buffer, which compression cannot carry.
- The harness’s
Scheduler.cancelnow closes the thread, astask.canceldoes, so a cancelled thread reads as dead in the simulation too. - The harness’s clock fails the run when its
spawnis handed a dead thread. LuneBlox’s owntask.spawnpasses over one in silence; the harness takes the stricter reading.
Added
scripts/check-version.sh: every place a release names the version (both packages, the README, the documentation, the changelog) must agree withwally.toml. It runs in pre-push and in CI.- Mutation adequacy runs weekly in CI (
.github/workflows/mutate.yml), not only by hand. - A pushed tag drafts the GitHub release (
.github/workflows/release.yml): the tag is checked against the tree’s version, the model is built and attached, and the notes start from the changelog entry. - Specs for the signal (order, disconnect, a disconnect during a fire, destroy, and that a disconnected listener is let go) and for a cancelled caller that had joined a manual save, each with its mutant.
Not done
- Only a cancelled caller that was queued is handled. A thread cancelled while it holds the lane
(parked inside its write) still leaves the lane taken for good, and a cancelled thread that owned a
queued manual save leaves later manual
profile:savecalls waiting forever (renewals and the release still land). Both were so in 0.6.5 and are tracked in #29. Until then, do not cancel a thread that is insideprofile:saveorprofile:release.
0.6.5 - 2026-10-05
One field for games that pay for the time a player was away. Nothing about stored data or the lock protocol changed: 0.6.4 and 0.6.5 servers run side by side.
Added
profile.lastSavedAt: when the record was last written before this session took it, in Unix seconds. It is theLastUpdatethe load found in the record, which is the earlier session’s last save, and its release when that session ended cleanly. The load itself writesLastUpdate, so the stored record could no longer say; the claim now reads the value before it writes over it. It is 0 for a profile that had never been stored, for a record that holds no number there, and for data taken from another library, whose record is made by the load. It does not move while the session saves. A mock store reports it as a real one does, andstudio = "copy"reports the live profile’s. The roblox-ts declarations gain it too.
Not done
lastSavedAtis the time of the last write, whatever made it. A load that took the key and gave it back (cancelled, timed out while settling a trade, data no migration could read) wrote the record, and so did a claim whose answer was lost and which the same load then made again: the next value is that moment, not the last play. After a server died, it is the dead session’s last stored save, though the load may recover newer play from its MemoryStore snapshot.- The ProfileStore wrapper has no such field: ProfileStore’s profile has none to map it to.
0.6.4 - 2026-10-05
What 0.6.3 left open in Studio, and typed profile data. Nothing about stored data or the lock protocol changed: 0.6.3 and 0.6.4 servers run side by side, and a live server behaves as it did.
Fixed
- A shared store opens in Studio in a place that cannot reach live data.
KeepBlox.sharedthrew in a place file that was never published (“You must publish this place to the web to access DataStore.”), and with API access off its calls failed. It now does what a store does since 0.6.3: in an unpublished place it opens in memory, and without API access its firstread,updateorwatchmakes one read-only call (GetAsyncof__KeepBlox_access_check) and moves to memory when that is refused. Watchers hear the updates made in memory. On a live server the error is raised as before, and so is any other error in Studio. studio = "copy"no longer hides a live profile it could not read. The profile started from the template without a word, so a play test looked at a new player and took it for the real one. It still starts from the template, since a play test must not be blocked, andstore.onErrorfires once for the key, with the key and “The live profile could not be read for the copy (the engine’s error): this play test starts from the template”.
Added
SharedStore.onError, a signal of(key, message)as a store’s is. It reports that Studio keeps the documents in memory: once, with the key"", on the first call, with the same two messages a store uses. It reports nothing else yet: a failedreadorupdatesays why in its result. The roblox-ts declarations gain it too.- Typed profile data.
KeepBlox.Store<T>,KeepBlox.Profile<T>andKeepBlox.LoadResult<T>take the shape of the data, andTdefaults toany, so every annotation written without it means what it did. A game names its shape once,const store: KeepBlox.Store<PlayerData> = KeepBlox.store(...), andprofile.Data,profile.LastSavedData,onSaved,store:profiles()and the datastore:editandstore:tradehand over arePlayerDataunder both type solvers. The consumer type check holds a typed store beside the plain one, and two misuses of it that must fail.
Changed
- With
studio = "copy", a key the play test already holds in memory is not read from the live store again. Memory won before as well; the read was wasted. - In Studio, a shared store’s first call makes one extra read, of the key
__KeepBlox_access_check. Live servers do not make it.
Not done
KeepBlox.storedoes not work the data’s type out fromtemplate: the shape is the annotation’s. Inferring it would type every existing store by its template literal, whereitems = {}says nothing of what the game later puts in it, and code that type-checks today would stop.SharedStore,ReceiptOptions,store:readVersionand the results ofstore:editstay untyped (any).- The Studio fallbacks are proven against the fakes, with the engine’s messages as 0.6.3 recorded them. The shared store’s was not run in Studio for this release.
0.6.3 - 2026-10-05
Found while putting 0.6.2 into a live game. Nothing about stored data or the lock protocol changed: 0.6.2 and 0.6.3 servers run side by side.
Fixed
- A store opens in Studio in a place file that was never published.
KeepBlox.storethrew there, withstudio = "live"(the default) and with"copy": Roblox refuses the data store itself (“You must publish this place to the web to access DataStore.”), before the read-only access check could run. The store now opens in memory, andstore.onErrorfires once on the first load, with the key""and “This place is not published: profiles are kept in memory, and nothing is saved”. On a live server the error is raised as before, and so is any other error in Studio. KeepBlox.processReceiptis typed: it takesReceiptOptionsand returns(receipt: Receipt) -> Enum.ProductPurchaseDecision. It took and returnedany, so a mistake in the options was found only when a purchase arrived.
Added
- The module exports the types a game needs to annotate its own code:
StoreOptions,LoadOptions,LoadFailure,EndReason,ReceiptOptions,Receipt,ReceiptDecision,SharedOptionsandConfigOverrides. Options built apart from the call no longer need a cast toany. The roblox-ts declarations gainReceiptDecision,SharedOptions,ConfigandConfigOverrides. - The consumer type check (
tests/consumer/Game.luau) holds the documented load,if not result.ok then ... return endfollowed byresult.profile, under both solvers, with the result annotated and not.
Changed
- A store’s
configoption is typed by its settings (ConfigOverrides), not as{ [string]: number }. A misspelt setting is a type error under the new solver; the old solver cannot make that check, and the assert when the store opens stays for it. A table of settings held in a variable needs the annotationKeepBlox.ConfigOverrides: one typed{ [string]: number }, or under the new solver not typed at all, is no longer accepted. Nothing changes at run time. - The README and the documentation say where the library runs: in one live public game (Grabby Pit) since early October 2026.
0.6.2 - 2026-10-04
The library’s code is the same as in 0.6.1: src/ did not change. A game on 0.6.1 gains nothing by
updating.
Changed
- Every tool is on its latest stable release: LuneBlox 0.10.13, rojo 7.7.1, selene 0.32.0, lefthook 2.1.16, Starlight 0.42.5. The suite (305 specs), the frame budgets and the ProfileStore baseline pass on them, and the published numbers are measured again on LuneBlox 0.10.13: a 1 MB save’s longest frame is 4.2 ms (it was 4.1 ms, within noise).
- CI actions are pinned to exact tags, not to moving major tags.
- The type gate reads the Roblox API definitions of the luau-lsp release it is pinned to (1.70.1), not
of whatever luau-lsp’s
mainheld on the day they were downloaded.
Added
- The KeepBlox icon, on the documentation site and in the README.
0.6.1 - 2026-10-02
Fixed
Both found by the live load test (GP_TEST, 2026-10-02) run on 0.6.0, and both older than it.
- A key being taken over from a crashed server could open twice on the server taking it over. The load
reads the dead owner’s snapshot from MemoryStore after its claim, and the key was no longer marked as
opening by then, so a second
loadof the key meanwhile (a player rejoining) was not refused asopen: it claimed the key again. The server then held two live sessions of one profile, the second with the stored data, and the first one’s unsaved play was lost. The key now stays marked until its session is listed. - The dead owner’s snapshot is stored however often the data store refuses the write, until the load’s deadline. It was tried once: on a spent budget that one write failed, the stored data was used, and the play since it was last stored was lost (two minutes, in the test) instead of about one beat.
0.6.0 - 2026-10-02
Fixed
- A long list changed in a few places far apart keeps its crash snapshot. Past about 64 items between
the first and the last change, the whole stretch was replaced in one edit: an inventory of 200 items
with two taken out near its ends made 22 KB of edits, far over
snapshotBytes, so a crash lost up torenewFallback. Such stretches are now searched by how many items differ (Myers’ O(ND)), and the same change is 89 bytes. A stretch that differs in more than 32 places is still replaced whole.
Changed
- While a server’s data store calls fail, its loads no longer each retry at their own backoff: after
its backoff a load waits its turn, one of them tries the store about once a second, and the first
that is answered lets the rest go at once. Retries fired at a store that is down only fail, and they
spent the budget the loads needed once it was back. In the simulator, after a minute’s outage on
servers with one player’s budget, the last of 30 loads lands 4 s after the store is back, not 18 s;
with a full budget, 1.1 s after, not 2.5 s; and an outage costs 16-75% fewer requests. A lone failing
load, a key that fails among keys that work, and a server with no failing calls behave as before.
When the store flickers every 3 s, the slowest loads take up to a second longer (p99 3.6 s, was 3.2).
bench/Retry.luaumeasures it. - The diff of a long list no longer builds a table of every pair it will not use: 700 items with two taken out take 0.6 ms, not 3.9 ms.
- A number that is not an integer encodes 6-18% faster; the text is unchanged.
0.5.0 - 2026-09-30
Fixed
- A profile over
snapshotBytes(1000 bytes) is covered by the heartbeat snapshots too, so a crash loses about one beat of it, not up torenewFallback(30 s). Its snapshot holds only its edits since it was last stored, with a fingerprint of that data; the server taking over applies them only to the record they were made against, and otherwise keeps the stored data. Lists are aligned, so a thing taken out of the middle of fifty is one edit. Measured on a game’s profile shape (about 230 bytes of JSON per thing), the whole data passes 1000 bytes with the first few things and no compression brings fifty under the MemoryStore quota of about 1 KB per player; the edits between two writes do fit.
Changed
- A hand-over to a live owner takes 2.9 s in the benchmark, not 3.2: a newcomer that looked at the owner’s beat less than a second ago while waiting reuses that verdict right after trying the data store, instead of one more MemoryStore call before its next wait.
- Each beat walks every open profile stored under 128 KB (it used to stop at
4 * snapshotBytes), over as many frames as it needs. - A server entry in
KB_serversgainsx, the edit snapshots. KeepBlox before 0.5 does not read it, so during a rollout an older server taking over a large profile keeps the stored data, as before.
Added
bench/Heartbeat.luau: every story atheartbeat4 and 2. At 2 s a crashed owner is taken over in 5.0 s instead of 9.1, losing 2 steps instead of 4, with no violation, for 87 MemoryStore units a player-hour instead of 45.
0.4.1 - 2026-09-30
Fixed
- A game checked with Luau’s old type solver sees the whole public API. The properties of
Profile(key,loadCount,createdAt,onSaving,onSaved,onEnded),Store(name,onError) andSharedStore(name) were written with thereadmodifier, which the old solver drops: using them failed with “Key not found”. Found integrating KeepBlox into a game still on the old solver.
Added
KeepBlox.Migration, the type of one migration. On the old solver, annotate a list that mixes steps and{ up, down }pairs with it ({ KeepBlox.Migration }): that solver takes a list literal’s element type from its first element.tests/consumer/: a game’s use of the public API, type-checked under both solvers, and misuse that must fail on exactly the marked lines under each (scripts/type-check.sh, in CI and before a commit).
0.4.0 - 2026-09-30
Fixed
- A heartbeat snapshot fires
onSavingfirst, as every save does. A game whose play lives outsideDataand writes it inonSavinghad heartbeats carrying the data as last written, which matched the stored copy, so a crash lost the play since the last renewal (up torenew, 300 s) instead of about one beat. Found integrating KeepBlox into a game.
Changed
onSavingfires everyheartbeatseconds (4 by default) for each profile a heartbeat snapshot covers, not only before data store writes. Keep its listeners cheap.
0.3.1 - 2026-09-30
Fixed
- The pesde package holds the whole library. pesde reads
includesas globs, so"src"matched the folder and nothing in it: the 0.1.0-0.3.0 pesde packages held onlysrc/init.luau, and a game that installed one failed at its firstrequire. The Wally packages were whole.
Added
scripts/check-package.sh, in CI and before a push: each tracked file undersrc/must be in the pesde archive (pesde publish --dry-run) and in Wally’s file list.
0.3.0 - 2026-09-30
The first live check, in Studio against real DataStore, MessagingService and MemoryStore (2026-09-30),
in a private test experience: 113 of 113 checks. Loads, hand-overs, a three-server race, crash
takeovers, shutdown, messages (each handled once), receipts, versions and restore, migrations with
writeVersion rollback, trades, zstd compression and mixed ProfileStore servers both ways all held.
Measured live: hand-over from a live owner 4.2-4.6 s (simulator 3.2 s), crash takeover 11.6-12.9 s
(simulator 9.1 s) with at most one beat of play lost, shutdown of 5 profiles 1.35 s. Live calls take
0.3-0.6 s each; that is the difference.
A live load test (300 profiles on one player’s budget, 10 virtual servers, a player moving every second, two crashes) saw no double owner: hand-overs carried the data exactly, a crash lost at most one step, and what was stored was each key’s last owner’s. Load tests must run in a separate, empty experience: one run from a live game’s Studio throttled that game, because data store limits are shared by the whole experience.
Fixed
- A load answers within
loadTimeoutin all, as documented. Each of its steps counted the timeout afresh: a player back on a server still releasing them, then waiting on another owner, could wait twice as long, and one load in the live stress test ran past 300 s. - Under overload, saves get the budget first. Loads polled a spent data store budget, so the owners’ final saves were throttled and hand-overs stalled (a metastable loop, seen live with 300 profiles on one player’s budget). A load now waits for the server’s budget, and its later tries leave a reserve to saves. In the overload spec, 683-692 loads land instead of 383-396, and none runs past its deadline.
- A shutdown whose releases cannot land (a spent budget, a failing data store) no longer loses the play since the last beat. Three seconds before the deadline, the data of every release still pending goes into one last MemoryStore beat (profiles up to 24 KB), and the next server stores it first.
restoreof a version that no longer exists, or of an id that is not one, answers"noVersion". Before, a version overwritten later in its hour answered"notAProfile", and a mistyped id threw out ofrestore.readVersionanswers nil for both.
Added
tests/live: the live check, rerunnable from the repository.luneblox run tests/live/Serveserves it to Studio,Load.luaubuilds it,Start.luauruns the functional check (113 checks) or the load test. It runs only in the test experience named inroblox.env.example, andCleanup.luauremoves its data.- The benchmarks compare a game with no library too: GetAsync on join, SetAsync on leave and every 60 s, as the Roblox guides teach. Over 20 seeds it breaks 63 acknowledged saves, a crash loses 51 steps of play, and a stale server keeps writing for 900 s.
Changed
- Benchmarks re-measured on the live budget model. KeepBlox’s figures are unchanged; DataStore2’s slowest open is 8.8 s (it was 0.6 s under the old one-minute budget); a 1 MB save’s longest frame is 4.1 ms.
- The test fakes follow what the live check measured, and every spec that depended on the old guesses
was seen failing first:
- a data store keeps NaN and infinities; it keeps a table with
[1]as its array part and drops every other key without an error; it turns number keys of a dictionary into integer text; - a remove adds its tombstone as a version of its own; a version id that is not well formed is error 25, and a well-formed one the key does not have reads nil;
- a string message may have 1024 bytes and any other message 940 bytes of JSON;
Senthas milliseconds; - ordered ties come in a fixed order that is not by key;
- a new server starts with a burst (600 reads and writes with one player) and its budget is not
capped; the experience-level limits (300 + 40 per user reads and 300 + 20 per user writes a
minute) are shared by every server, and a request over them fails as it does live
(
StandardReadExperienceThrottled).
- a data store keeps NaN and infinities; it keeps a table with
- The differential fuzzing of the save check now asks for more: Validate accepts exactly what the store keeps without loss. The two departures by choice: NaN and infinities, which the store keeps, are left out; and an array with holes is refused even when the store would keep it, since whether it does depends on how the table was built.
0.2.0 - 2026-09-30
Fixed
- A hand-over request left in a server’s MemoryStore entry no longer ends a later session of the same key. A player hopping from A to B and back to A within one beat lost their new session on A. Requests now name the owner’s load count.
- A load that gave up (cancelled, closing, timeout) after a claim whose answer was lost no longer leaves its live server holding the key. Before, no other server could load the player while that server lived.
restorebrings back the restored version’s schema version, so the migrations since then run on it. Before, a renamed field came back as its default.- A live owner whose MemoryStore beats hang is no longer taken for dead by a quiet edit or a newcomer. The owner withdraws its beat from its records first, and a takeover on the beat’s word lands only while the record still vouches for it.
- The size estimate counts an empty table as 2 bytes, not 1.
- A trade right after a migrating load stores the schema version with the migrated data. Before, the record kept the old version, and the next load ran the migrations again on migrated data.
- Data that contains itself no longer breaks every save: the copy a save takes recursed forever on a cycle, before the check could refuse it.
Changed
- One bad value no longer costs the play around it. A value a data store cannot hold (a string that is
not UTF-8, NaN, a function, a cycle) is repaired in what is stored, and each repair is reported once
with its path. Before, every save of the session was refused until the game removed the value. Only
a table’s shape and the size limit still refuse the write. In the
poisonbenchmark this loses 0 steps, where it lost 204. - Faster hand-overs: while a live owner hands over, the key is tried every half second. A dead owner’s beat is looked at again the moment it could be judged dead. Slowest open in the benchmark: hand-over 4.5 s to 3.2 s, three servers at once 8.2 s to 4.4 s, after a crash 10.0 s to 9.1 s.
restorereturnspurchasesSince, the purchases granted after the restored version. The restored data no longer holds them and they stay granted, so the game must make them good; before, they were lost silently. The record notes the restore inMetaData.KeepBlox.restored.- The snapshot a save takes is copied about 3x faster (one engine clone per table): the one step of a save that cannot be spread over frames. The check’s text is also joined a chunk at a time inside the sliced walk, not all at once at its end. A 1 MB profile’s longest frame stretch fell from 9.1 ms to 4.3 ms.
Added
tests/Mutate.luau: mutation adequacy of the suite. 37 mutants, each a slip in code that keeps a guarantee, must each fail the suite.- Differential fuzzing of the save check against the store’s encoding.
- Releases you can roll back. A migration may be
{ up, down }, and a store’swriteVersionstores data at an older version: saves, trades, new profiles and MemoryStore snapshots alike. The release before it then reads everything, so a rollback locks no player out.KeepBlox.migrateDowntests the down steps on fixtures. - The Wally and pesde packages,
xopoiii/keepblox(0.1.0 is published on both).
0.1.0 - 2026-09-29
Added
- Repository scaffolding:
- the pinned toolchain;
- the lefthook and CI gates (strict mode, 300-line cap, English only, selene, StyLua, luau-lsp);
- the test runner on LuneBlox.
Services, the seam through which the library reaches every Roblox service.- Test harness fakes:
- a seeded virtual scheduler;
- per-server clocks with skew and drift;
- DataStore and MessagingService fakes.
- The simulation harness:
- an engine environment that runs unmodified Roblox modules on virtual servers;
- a ledger that checks the data invariants on every committed write;
- nine named scenarios, run over many seeds.
- The vendored ProfileStore v1.0.3 as the baseline, with its measured weak spots in
tests/reference/BASELINE.md. - The core library (
src/):- session locking in ProfileStore’s format, with a lease-based takeover of dead owners;
- validation with the path of the bad value;
- a freeze of a session’s data when the session is lost;
- load failures as typed results;
- parallel release on shutdown;
- an in-memory mode for Studio and scratch play tests.
- Benchmarks with budgets for the frame cost of saving (
bench/). - ProfileStore compatibility:
- mixed ProfileStore and KeepBlox servers keep every invariant in the harness (
tests/sim/Mixed.luau); Compat/ProfileStoreoffers ProfileStore’s API, so the migration is onerequire.
- mixed ProfileStore and KeepBlox servers keep every invariant in the harness (
- Offline messages (
store:message,profile:onMessage), handled exactly once; a full queue refuses instead of dropping. - Purchases (
KeepBlox.processReceipt): granted once, and reported granted only once stored. - Versions:
store:versions,store:readVersion, andstore:restore, which refuses while a key is in use. - A schema for the data (
KeepBlox.schema): types, defaults, bounds and nesting, with path errors on refused saves. - Numbered migrations with a stored schema version. A load refuses data from a newer version, a failing
migration, or data that does not fit the schema; it lets the key go and writes nothing.
KeepBlox.migratetests a migration against fixtures. - A server heartbeat in MemoryStore: a dead server’s keys are taken within about 10 s, a live owner
hears a hand-over request without MessagingService, and each beat carries snapshots of changed
profiles, so a crash loses about one 4 s beat of play. Profiles too large for a snapshot are written
every 30 s (
renewFallback); the data store is written every 300 s otherwise (renew). - Offline and admin edits (
store:edit,LoadOptions.quiet) that never kick a player. - Trades (
store:trade) that land in both profiles or in neither, whatever dies when. - Shared documents (
KeepBlox.shared) updated atomically from any server, withwatch. - Leaderboards (
leaderboards,store:leaderboard) mirrored to ordered data stores. - Importers (
KeepBlox.importers) for DocumentService, Lapis, DataKeep, DataStore2 and Suphi’s DataStore Module. - Optional compression for large profiles (
compress), Studio modes (studio = "memory" | "copy"),store:close()for tests, and roblox-ts declarations (types/index.d.ts). - Benchmarks against ProfileStore, ProfileService, DocumentService, Lapis, DataStore2 and Suphi’s
DataStore Module (
bench/Report.luau,bench/Benchmarks.md), and a documentation site (docs/).
Fixed
- A new profile ran every migration on the template.
- A quick rejoin into the same server failed with “open” while this server was still releasing.
- A save loop queued one write per call; manual saves now join the one waiting.
