Puzzle design research
How BeanNest Versions and Bounds Browser-Game Progress
BeanNest's accepted shared-runtime decision separates progress transport from game-specific state semantics. The shared layer defines how a bounded snapshot is identified and moved; each game still owns its snapshot schema, migration rules, canonical reconstruction, and integrity checks. Bit Balance provides a public metadata example of that contract.
What this guide helps you decide
What does BeanNest's shared progress transport contract guarantee, and which progress decisions remain owned by each game?
This research explains the accepted shared progress transport contract and uses published Bit Balance metadata as one concrete game example. It does not claim cross-device synchronization, cloud backup, account behavior, universal migration behavior, or data durability across browser and operating-system events.
Try it on the anchor product: BeanNest Games /games/.
The shared runtime owns transport, not game state
The accepted runtime decision assigns progress message validation, identity, bounded JSON storage helpers, standalone storage, and sandbox-parent transport to the shared runtime. Snapshot schema, migration, canonical-state reconstruction, and integrity checks remain game-owned.
Every parent exchange carries exact progress identity
The compatibility rules require parent progress requests and responses to carry the exact game slug, progress version, and request ID. A response that belongs to a different identity is not the same progress exchange.
The common snapshot ceiling is 64 KiB
The shared runtime decision sets a common snapshot ceiling of 64 KiB. The bound is a transport and storage contract; it does not say that every game stores the same fields or uses the same schema version.
Standalone and embedded play use two transport shapes
The shared contract supports standalone storage and a sandbox-parent transport for embedded play. The embedded path requires an acknowledged parent save before success is authoritative, while direct standalone save keeps its compatibility behavior.
Bit Balance is one published example
Bit Balance public metadata declares the shared runtime SDK, progress version 1, and a maximum progress size of 65536 characters. That proves the published contract for Bit Balance; it is not evidence that every game has the same schema version or state shape.
Migration and reconstruction stay game-owned
The shared decision explicitly leaves snapshot schema, migration, canonical reconstruction, storage-key version lists, and integrity checks to each game. A transport version therefore identifies an exchange boundary without proving how a particular game's older state will be migrated.
What these sources do not establish
Neither cited source establishes cross-device synchronization, cloud backup, account requirements, or durability across browser and operating-system events. Those questions need their own product evidence and are intentionally outside this guide.
First-party evidence and provenance
How we checked this
We reviewed the accepted shared game-runtime decision and published Bit Balance metadata. We separated shared transport guarantees from game-owned schema and migration behavior and did not infer account, cloud, cross-device, or durability behavior that the cited sources do not establish.
- Method
- We reviewed this repository's evidence contract and the published game metadata, then traced the shipping behaviour to confirm the mechanism described here. We deliberately did not read or publish a hidden solution state.
- Environment
- Repository source review of the current main branch. No live traffic, account data, or player-identifying information was read.
- Captured
- Reviewed by
- BeanNest Studio
Repository evidence artifacts:
docs/decisions/0022-shared-game-runtime-contract.mdgames/bit-balance/game.json