S3-071: Make AI recover from economic deadlocks

Parent and ownership

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

Problem and observable result

Detect food, tool, population, and delivery shortages. Recover through legal actions. Recognize genuinely unrecoverable states.

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

AI submits the same commands as players and observes an allowed player view. Difficulty is explicit and seeded. AI must not create resources or use concealed enemy information.

• https://github.com/paulwedeck/settlers-remake/tree/6ad8c4230a4aa4cd21840f8cb59a38344e41c3e0/jsettlers.logic

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

• Detect food, tool, population, and delivery shortages.
• Recover through legal actions.
• Recognize genuinely unrecoverable states.
• 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

• Remove a critical AI supply route.
• Exhaust resources and inspect recovery choices.
• 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/stacksjs/the-settlers-iii-remake/issues/49
• https://github.com/stacksjs/the-settlers-iii-remake/issues/72

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.

Verified completion, 2026-10-23

Implemented by 515d6a1, with the complete reproducible S3-071 acceptance receipt. The receipt retains fixture seeds/hashes, actual food/tool/population/delivery recovery, impossible bootstrap results, cancellation and save/replay checks, resource conservation and owner-only visibility. No grants, concealed enemy knowledge or invented balance values were introduced.

The complete owning suite passed 200 tests with zero failures (20,782 assertions); the focused AI suite passed 23 tests/501 assertions. Lint and application/tools/stx types passed. The subsequent verified framework adoption preserves the AI source and has successful main CI on ec3f897. This closes the engineering AI slice only; original-game balance observations and native capability claims remain separately scoped.

The source-first web AI corrections through #202 are now qualified on main at b0d1df3. Exact CI 40242723177 succeeded; its original artifact 12618051922 matches SHA256 a5a9df03b47549820dcac09d0c7defcfb69649b48b63a0da9c82cd415fc9e4fc, with every CRC/all 385 steps/no error collections verified.

All four sampled ordinary two-policy matches now finish: seeds 1/5/2/3 at ticks 31801/73581/184761/139741. Complete traces have no failed commands and clean conservation. The charcoal correction uses the existing real recipe and demand; it changes no rules, starting stock, physics, speeds or battle deadlines. The source and rejected-candidate evidence are retained in the receipt. The qualified framework cohort remains Stacks 0.75.311 / STX 0.2.691 / Craft 0.0.341 / Pantry 0.11.127 / Bun 1.4.4.

This advances the browser engineering prototype. Keeping this broader issue open. A human-input skirmish victory, all-seed behavior, broader configuration, native presentation and original Gold Edition agreement remain unproven. Work continues on #203 after normal browser input exposed a woodcutter suggestion with no reachable trees despite other known usable sites. Seed 1 has no initially known granite, so its quarry fallback needs an honest warning rather than an invented productive-site claim.

Browser qualification advanced with #203, now closed after cc702ac8 and exact main CI40244633903. All318unit tests and385browser steps pass. The original19651byte artifact12618617732 matches SHA256 46b79dfa1daa049459610a92c9ee7f6836cdb17b8d32b434a3d224fd0d23bdfe, all CRCs/steps/error collections verified.

Keyboard construction now prefers known reachable harvest sites, retaining legal fallback and an honest absent-resource warning. Native input confirms the suggestion and actual log production. Receipt. Simulation rules/AI/locks are unchanged from the qualified charcoal publication; its four completed sampled AI matches remain source-pinned evidence, not a new all-seed claim.

The next actual human-playability frontier is #204, with an ordinary four-site reproduction of all hammers stranded in idle construction crew. Lowering the cap leaves the tools unavailable for a geologist. The pinned reference has periodic surplus jobless-crew conversion and actual tool drops; a versioned source correction must preserve old saves and real accounting. The manual match ended in defeat after this shortage. No human victory, full sustainable game, native UI or original Gold parity has been proved. Keeping this broader issue open.

Staffing controls can now return idle construction workers and their tools to carrying. Ground drops also preserve ownership when another player's pile is nearby. These fixes are covered by #204 and #205.

329 unit tests and 385 browser steps passed, including save/reload. CI and validation details.

The player test got tools and storage working, but lost the rival match. Testing the original tutorial map then exposed a separate staffing stall: unreachable trained workers kept blocking reachable carriers. That is tracked in #206.

The staffing fix also passed four ordinary AI matches without command refusals or accounting errors.

Implementation, passing CI and validation details. Crew limits, goods accounting and older save rules are preserved.

More maps and longer economies still need coverage.

Progress (still open)

The economic AI (c34b7a6) already recovers from several deadlocks through ordinary commands: full doorsteps (it marks materials and tools for storage once it has a storage area), resources outside its border (it builds guard towers toward explored resources, or in a fixed rotation of directions to find them), and missing deposits (it re-sends idle geologists to unsurveyed mountains). Still to do: shortage-driven recovery for missing tools and weapons (tool smith priorities, urgent orders), food shortages at mines, exhausted working areas (moving work areas or rebuilding), and tests that induce each deadlock and prove recovery without grants.

Fixed a reproducible timber-recovery failure in e33c9bf. In ordinary rival seed 2, the AI demolished its last exhausted woodcutter at tick 6640 while a nearby forester still had three construction work units left. That removed its production site just before replanting could restore supply.

The recovery now preserves that hut while a non-suspended owned forester with an overlapping working area finishes. It uses the published workflow radii and actual working areas. A distant forester no longer counts as replenishment. No resources, tools or completed buildings are injected.

The receipt retains the original failure, public-session regression, mid-recovery restore with matching checksum, work-area command checks and a 72,000-tick run. The longer run retains its active woodcutter and stock of 16 logs and 8 planks with no conservation errors. This is engineering AI recovery behavior, not a Gold executable observation or difficulty-parity claim.

Local checks passed 256 unit tests and 22,575 assertions, lint, app/tools/STX types, production build and the 19-step rival browser/checkpoint scenario. Exact main CI 40191970245 passed every required step. Original artifact 12598313452 matches GitHub SHA-256 a41415a1fff513db4cebe3aaa6efed00ba66d3d0a0d20a93e21575a3c589d945, 17,633 bytes, all ZIP CRCs and all 332 browser steps across nine suites with no recorded console, request or collection errors. Original-media rasters remain local.

Keep #73 open. This fixes one timber failure; delivery, expansion, mineral access and military growth still need acceptance. A retained follow-up reproduction at seed 2, tick 36000 has an idle, unbusy geologist reporting unreachable, no current survey signs and no AI orders. That needs its own source regression and a proven recovery, rather than assuming the whole AI economy is finished. The browser scenarios do not establish a complete rival battle.

Fixed the retained surveyor deadlock in 6583568. The automatic duty loop had chosen a tile inside a coal mine; after routing failed, the AI ignored the idle, unbusy geologist because it only accepted the duty-complete diagnostic. The specialist loop now skips unreachable automatic targets in engineering profile 0.9.0, and AI reassignment reuses idle failed geologists while excluding known footprints and observed blocking objects. A public fixture confirms the same specialist id resumes surveying, without equipping a second specialist or injecting resources. The receipt includes the original seed-2 trace, red/green regressions and a 72,000-tick run that retains survey signs and produces 16 coal. Iron, weapons, delivery capacity and army growth remain unfinished. The next public-observation frontier has 25 known neutral mountain tiles outside the border, no current iron signs and no mineral-expansion order. This also advances #76 without completing a rival battle.

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.