S3-092: Implement deterministic replay and state diagnostics

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

Replay ordered commands from seed and versions. Compare browser, native, and Bun checksums. Identify the first divergent tick.

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

• Replay ordered commands from seed and versions.
• Compare browser, native, and Bun checksums.
• Identify the first divergent tick.
• 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

• Replay long mixed scenarios across hosts.
• Deliberately alter one command and locate divergence.
• 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/394
• https://github.com/stacksjs/the-settlers-iii-remake/issues/27

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.

Reproduced the native qualification gate on the unchanged game source 4a89e4419592ba3c10c76d0e64c51c44261eec12 with the verified original Craft 0.0.396 executable and Bun 1.4.4. Both the short multi-scenario probe and the unchanged 5,000-tick staffing probe exit with RangeError: evaluation step budget exceeded. The longer Bun reference completes construction, conservation, save/restore and replay at checksum b413c661.

The original release archive matches both GitHub and its release manifest; ZIP CRCs, executable version, exact source and release gates were verified. The interpreter correctly starts a fresh step counter for each real retained host callback. No reset defect or justification for raising limits was found. No fixture window, execution budget or timeout was changed, and no package release is claimed.

The next acceptance work is the actual retained native game host through the maintained PersistentRuntime API, with real tick callbacks and the full construction/save/replay scenario. Existing Craft tests cover simple retained callbacks, buffers, GC and ownership; they do not supply that game integration. This remains open under #26 and #94. A durable failure receipt is being committed with this update.

Retained failure and artifact provenance receipt.

Fresh unchanged canonical native diagnostics are retained against app source c0cd9ddcffa8f15d3e2cde44d0b18b979497289e, engineering rules0.19.0 (ae07f5b49e7969a9a6dcb73c8610929c2ecaa09df48e7a745fbf3140ad0345f3) and Bun1.4.4.

After the ordinary released Pantry0.11.156 installer selected the corrected signed Craft native0.0.423 build revision0.0.423.1, both maintained commands failed with native exit1 and RangeError: evaluation step budget exceeded:

• bun scripts/native-engine-check.ts:9.328s, captured bundle SHA256 d3986bfbbe6640eaecca2e4090517420a6915f025b235eb8ed9dc13b27dc9434.
• bun scripts/native-engine-check.ts --staffing:12.986s, full5000-tick input, bundle SHA256 eb8a00c6a7e3d032e4b81e351f150e17ffa97ff5230a93db7d699f94380eb21a.

Both have empty stdout and identical retained861-byte stderr SHA256 cafbc0652766ecaeef09ebb044d2f923c5139a8918017ffde02bd6ca653d06a1. The existing app SDK remains0.0.396 and its public resolver selects bare craft through the normal generated Pantry launcher. The real14893984-byte Mach-O, separately hashed before execution, is byte-identical to the independently qualified upstream0.0.423 original: c96fe815e228088ce6fd04999b2db93f517d5a584a42f9e9c01bb6a0709948de. No CRAFT_BIN override or PATH overlay was used. This is a diagnostic CLI installation, not an SDK/dependency-cohort adoption claim.

The same captured bytes evaluate successfully in Bun. Short baseline checksum f596edd9, crew recovery 325b9466, ownership 9c5d8403; the full staffing result is tick5000/checksum b413c661, active storage, matching restore/replay and unchanged creation ledger. These reference results do not establish native parity. No native result or first divergent simulation tick was produced.

The original30000ms bound, complete fixtures, engine step guard and owned cleanup remain unchanged. No shortened ticks, counter reset, CLI chunking, generated source patch, WebView fallback or fixture mutation was used. Both owned runtime directories were removed and the application remains clean. Three auxiliary launchers still select the old revision because of Pantry268; neither probe uses those profiles.

Consolidated receipt /tmp/settlers-native-423-normal-install/native-engine-423-failure-provenance.json, SHA256 2fe30a8ff3867a9101892c57a8661177cacfb67f686f34bbb5399107b7f5f667, seals original outputs/bundles, exact source and launcher/native identities, independent Bun references and publication receipts. Existing persistent native hosting/frame integration remains the owning frontier. #94 and #26 stay open; no native presentation, lifecycle or Gold fidelity acceptance is claimed.

The unchanged canonical native checks also fail on the normally selected, independently qualified Craft 0.0.424 full CLI. Both commands were run once against clean app source c0cd9ddcffa8f15d3e2cde44d0b18b979497289e with Bun 1.4.4:

• bun scripts/native-engine-check.ts: exit1, 8.629s.
• bun scripts/native-engine-check.ts --staffing: exit1, 13.462s, with the original complete 5,000-tick input.

Both native executions throw RangeError: evaluation step budget exceeded. The exact bundles and complete error bytes match the retained 423 failures. Fresh independent Bun references still complete with short checksums f596edd9 / 325b9466 / 9c5d8403 and staffing tick5000/checksum b413c661, including matching restore/replay. Native parity remains unproved.

The normal Pantry launcher selected the original public 424 ARM64 binary, SHA256 07e932f2f9da0ef873a8a684d995872c5370af537a160d3d332f725d7e0dc1ae; original release archive CRC/member bytes, signature and version were verified. No CRAFT_BIN or PATH override was used. This does not claim application SDK-cohort adoption.

The exact 424 core CLI manifest still pins zig-js afb30ec2620d701269477c987d9344b792d0ce96. The 424 regexp-cache pin update applies only to the separate macOS screen toolchain. This CLI result therefore does not test that screen-engine change.

Retained receipt /tmp/settlers-native-424-dwepoydi/native-engine-424-failure-provenance.json, SHA256 1e12f1eb2ca5bda85ec555f13e974284bcc53c02d64997db46d2c464611a1238, seals the actual runs, artifacts, source/pin/resolver identities and original 423 comparison. The original single evaluation, 500M-step guard and 30s bound remain unchanged. No workload splitting, guard reset, shortened input, fallback or source change was used.

Next diagnosis is a bounded source-owner attribution experiment reusing zig-js461 at the exact CLI pin. It has not run: the managed source-workspace validator currently prevents creating the required isolated engine workspace, and no fallback checkout or unknown-owner worktree was used. No engine cause has yet been established. #94 and #26 remain open; this is not native rendering, frame/lifecycle or Gold fidelity acceptance.

The isolated source workspace is now available. The next diagnostic stopped at the local native compiler-memory guard, before any JavaScript evaluation.

At the exact Craft CLI engine pin afb30ec2620d701269477c987d9344b792d0ce96, a non-default diagnostic adapter reuses the existing statement hook and owner attribution snapshots from zig-js #461. It preserves Craft's default Context.create(init.gpa), ReleaseSafe target aarch64-macos.15.0, original bundle bytes, one evaluation, 500M-step limit and 30-second runtime limit. It changes no engine source or package pin.

After correcting one adapter binding for the original compiler's function-metadata API, the guarded build exited125 at a sampled tree footprint of3,079MiB against the unchanged3,072MiB ceiling. A separately reviewed report-only scalar projection also exited125, at3,094MiB after106.12seconds. The projection preserves snapshot collection and evaluation order; these threshold observations do not establish which compiler work consumed the memory or whether the projection improved it.

Neither build produced an installed diagnostic executable. Neither the short nor full5,000-tick staffing bundle was evaluated by the adapter. Owned compiler descendants were confirmed gone, and this local compile sequence is stopped. No guard increase, alternate compiler, input splitting, shortened scenario or unchanged retry was used.

The original Craft424 failures and independent Bun results above remain unchanged. No engine-runtime hotspot, step-accounting defect, first divergent simulation tick or native parity has been established. #94 and #26 remain open.

Final retained build receipt: guarded-build-v3-failure-receipt.json, SHA256 e303f4289ab26f981ea8961b3b8d957df3c0f5b1b9e77af267bc5f1c1270c51e. It retains the earlier failed attempts, exact source/compiler/input identities, unchanged guards and cleanup. This is diagnostic-build evidence, not native game, graphics, lifecycle or Gold fidelity acceptance.

Progress: deterministic replay and diagnostics (still open)

record() captures accepted commands and the state checksum after every tick from a start save; verify() re-executes from a restored runtime and reports the first divergent tick or a rejected command. Tests alter one command and corrupt one checksum and get the exact tick back; long mixed scenarios replay identically across save and restore. Checksums use canonical key order and little-endian layers, so they do not depend on object construction order or host byte order.

Remaining: compare browser, native and Bun checksums for the same replay (needs the native host from S3-013/S3-023), and cheaper incremental checksums for large maps (new issue).

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.

Progress: replays now record and verify with the incremental chunked checksum from #106 (275dc1a). The first-divergent-tick report and the existing divergence tests are unchanged. Per-tick checksum cost on a 1024×1024 map dropped from about 90 ms to about 0.4 ms, so long replays are practical. Still open: comparing browser, native and Bun checksums for the same replay (needs the native host from S3-013/S3-023).

Preserved older rules and replay behavior while publishing engineering routing policy 0.9.0 in 6583568. Profile 0.8.0 is archived at unchanged digest 79d6f868c4b56d86fb54a65e739116bce25242d9d9e39225a1f871f53268de21; all eight catalog digests are pinned. Legacy restored specialists retain their former routing. Replay verification now accepts the published profile catalog, and the immutable format1 replay fixture remains unchanged and verifies at its original checksum 6b98801a. The receipt records these checks. The existing five-tick shared fixture also matches Bun 1.4.4, Chrome and the qualified original Craft 0.0.341 executable at c331a944, including restore and replay. That narrow fixture does not execute the new specialist route cases and does not prove native presentation or full-game parity.

Exact main CI 40193838620 passed. Local acceptance passed 262 unit tests and 22,612 assertions, lint, app/tools/STX types, production build and all 332 browser steps. Downloaded original diagnostics artifact 12599132458 matches GitHub SHA-256 7bd49fa9eca20e6c0b56ddbebf0464725b2bd5cc8991369677f74166fc253fe5, 17,625 bytes, all ZIP CRCs and all 332 browser steps with no recorded console, request or collection errors. The archive contains no media rasters.

This is engineering recovery evidence, not an original Gold executable observation. The issue remains open for its remaining acceptance criteria.

The landscape catalog correction in #219 retains deterministic terrain identities through actual commands, save/restore and replay. The checksum hot loop now performs the same little-endian UTF-16 FNV byte operations directly; frozen traces and an independently calculated Unicode fixture retain their prior values. No checksum format, replay deadline or rules identity was relaxed. Broader replay/network diagnostics remain open.

Validation: full CI, 413 unit tests and all 16 browser suites. The original diagnostic artifact checksum and ZIP integrity were independently verified.

The unchanged 5,000-tick reachable-staffing fixture still fails in the original macOS arm64 Craft 0.0.368 CLI, exiting with uncaught error. Its release archive, API digest, manifest, tag commit and ZIP CRCs were verified before execution. The existing 30-second timeout and fixture were retained. No native dependency update or cross-host parity pass is claimed from this result.

Reproduction uses the maintained SDK resolver with the verified CLI selected through CRAFT_BIN:

bun scripts/native-engine-check.ts --staffing --browser

The fixture runs the existing construction, accounting, save/restore and replay scenario. Its Bun reference completes before the native failure; browser comparison is correctly not accepted afterward. The failure text does not establish its underlying cause. Native execution remains unqualified while browser work continues.

The independently reproduced loss of exception messages is tracked in Craft #422. Correcting that owning CLI diagnostic will make the long failure actionable without changing its limits.