S3-091: Make checkpoints survive lifecycle and storage failures

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/14 Source owner: stacksjs/the-settlers-iii-remake. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Order queued and concurrent saves. Report success only after completion. Recover from abort, quota, disposal, and interrupted writes.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Versioned save envelopes and seeded command logs preserve complete simulation state. Online matches run authoritatively in Bun and emit visibility-filtered updates to authenticated clients.

• https://github.com/stacksjs/the-settlers-iii-remake/blob/884406e97f912d18a50a33734b535a27dd25531d/resources/game/controller.ts
• https://github.com/stacksjs/stacks/tree/c8e9b2755edeead39ecf6aa540014a7642ff7149/storage/framework/core/realtime

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

• Order queued and concurrent saves.
• Report success only after completion.
• Recover from abort, quota, disposal, and interrupted writes.
• The visible result agrees with the underlying simulation or platform state, including failure paths.
• Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

• Race save with teardown and backgrounding.
• Inject delayed and failed storage operations.
• Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
• Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
• Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

• https://github.com/craft-native/craft/issues/396
• https://github.com/stacksjs/the-settlers-iii-remake/issues/92

Upstream release and adoption

Application behavior belongs here. If a reproduction identifies a framework defect, repair and release its owning source first, update Stacks where affected, then install the verified packages here.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

• Implementation commits and relevant upstream issue links.
• Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
• Published package versions, downstream lockfile identity, and release receipts when affected.
• Remaining limitations stated explicitly. Partial work does not close this issue.

Progress: lifecycle-safe checkpoints (still open for native hosts)

f3b71ce adds resources/game/checkpoint.ts: two slots plus a head. A save writes the slot the head does not name, reads it back, and only then moves the head. Saves run in order; requests made during a write collapse into one write of the newest state; success is reported only after the head is stored. Loading prefers the head's verified slot, then the newest intact confirmed slot, then the earlier single-key save. Closing the game writes a final checkpoint before storage is released. Tests inject delayed, refused, quota and torn writes and race saves with disposal (tests/unit/checkpoint.test.ts).

This runs on Craft's browser Storage today. Native backgrounding and storage evidence depend on the Craft checkpoint contract (S3-017).

Evidence base for this update (all on main, authored as Chris):

• 3ca4847 deterministic session, rules profile, routing, goods, carriers, construction, production, territory, visibility, saves and replays
• da2a104 reference building geometry and the delivery livelock fix
• b2efc1f the browser game on the engine, expanded original-media import
• 7b1cc36 worlds from decoded original maps
• a495e7a, 0a3ff46, 0e7889e, e5c1a53, f3b71ce, ed1dc8f controls, missions, render scene, save migration, checkpoints, audit and statistics

Checks: ./buddy lint (0 problems), bun run typecheck (app, tools, stx), ./buddy test --unit (106 tests, 0 failures), bun run assets:verify, bun run content:verify, and the production browser scenario. CI passed on 0e7889e and 9e2ba7c (which contains f3b71ce), including the production Chrome check.

Rule values are the roman-engineering 0.2.0 profile (resources/game/engine/rules.ts). Every value names its evidence class: manual candidates (M) from the pinned manual, reference-remake geometry (E), or placeholders (U) that name their owning issue. qualificationGaps() lists them and the profile cannot qualify a release. Adopting observed original values remains with S3-002/S3-007; nothing here is an original-executable observation.

Checkpoint ordering follow-up, verified on main at 1c878716:

• The earlier two-slot coordinator has been superseded by atomic session compare-and-set. Competing documents cannot both acknowledge the same checkpoint, and a stale session cannot overwrite newer progress.
• Reads and writes now share one ordered queue. A delayed load cannot rewind the base of an acknowledged save; saves coalesce only between load boundaries. Disposing rejects queued reads without starting storage work.
• All 24 checkpoint cases passed, including the retained failing reproduction. The full application suite passed 242 tests. A real two-document browser test uses the unchanged installed Craft provider, native Web Locks and localStorage through generation 5, then restores in a new document.
• Lint, app/tools/template types, production build, the 58-step production browser campaign and original control-frame checks passed. Both exact-source CI and main CI passed.

The committed receipt retains test and browser evidence. The installed foundation remains Stacks 0.75.294, STX 0.2.686 and Craft 0.0.330. Native game lifecycle acceptance remains outstanding, so this issue stays open. Browser playability is the current priority, followed by mobile and desktop.