S3-070: Build an economic AI using player commands

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

Gather and construct through legal commands. Staff and supply real production. Detect any conjured workers or goods.

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

• Gather and construct through legal commands.
• Staff and supply real production.
• Detect any conjured workers or goods.
• 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

• Run AI from normal starting stock.
• Inspect commands and conservation invariants.
• 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/52

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.

Completed: economic AI using player commands

c34b7a6 adds resources/game/engine/ai.ts.

• Gather and construct through legal commands: the computer player observes only its player's view, explored terrain and objects, its own settings and the public rules, and learns deposits only from its geologists' signs. It acts only by enqueuing ordinary build, specialists and settings commands, which the session validates like a person's.
• Staff and supply real production: it builds a declared policy in order (timber and stone, sawmill and forester, residences, water and fishing, the bread chain, surveyed mines, smelting and tools), places harvesting buildings with their resource inside the working radius, stores materials once a storage area exists, and the engine's normal staffing and logistics run everything it builds.
• Detect conjured workers or goods: the AI cannot touch simulation state. tests/unit/engine-ai.test.ts runs it from normal start stock for 20,000 ticks with audit() clean every 100 ticks, every settler beyond the start accounted for as a recorded birth, and every order accepted.

Also tested: a restored game with a fresh AI instance decides identically (decisions derive from the observation alone), and the observation exposes nothing unexplored and no deposit layer. The browser offers a computer rival on a wider generated landscape. Difficulty is the declared policy and cadence; this is an engineering AI, not the original algorithm. Found and fixed on the way: saves made while a geologist was on duty were refused (cfb0d1b).

Source ground permissions in #219 exposed two ordinary planning gaps. Extractors can now target a reachable known resource using a normal work-area command, and a city without a legal producer site can expand using ordinary towers while keeping its quarry reserve. Resource observations still come through player sight. The complete normal browser gate passed; this does not establish all-map economic recovery.

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