S3-035: Implement residences and workforce allocation

Parent and ownership

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

Problem and observable result

Create population through verified residence behavior. Apply carrier, builder, and digger controls. Account for every available and employed settler.

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

Ordered commands advance an integer-tick world. Goods have locations and reservations, people have identities and jobs, and a player view renders only actual simulation state.

• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/ec_basic/basics.htm
• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/ec_build/building.htm

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

• Create population through verified residence behavior.
• Apply carrier, builder, and digger controls.
• Account for every available and employed settler.
• 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

• Change ratios before population arrival.
• Verify assignments under tool shortages.
• 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/33
• https://github.com/stacksjs/the-settlers-iii-remake/issues/34

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.

Implemented in afea78e as Chris, without coauthors. A paused residence now retains its remaining arrival interval and creates no settlers until resumed. Repeated controls are idempotent. Engineering profile 0.16.0 remains frozen with its original digest; new games use 0.17.0, preserving older saves and replays.

The public-command regression failed before correction: after pausing at tick 40, births rose from 1 to 3 by tick 440. All 489 unit tests / 85,789 assertions now pass, along with lint (zero problems), app/tools/STX types and production build. Seven dedicated cases cover the clock, duplicate commands, mid-pause save/replay, ownership/type rejection, demolition and legacy behavior.

A real Chrome playthrough built and staffed construction for a small residence from normal supplies. The visible population stayed 39 for 21 game seconds while its inspector reported Work paused, then rose to 40 after Resume work. All 18 browser steps passed without console, network or collection errors. The final raster was inspected privately. The new scenario runs in CI and retains non-media diagnostics.

Retained source and local execution receipt. Hosted CI and the normal protected deployment workflow are running; their completion will be recorded separately. #37 remains open for original Gold residence values and controls.

Exact-source CI 41392644687 passed on afea78e3e0a6d3da88ce906bd1e57ee97fb12eb0, including 489 unit tests and all 23 production browser suites. The same source deployed successfully in production run 41392680742, with public smoke checks passing and rollback skipped.

Independently downloaded original diagnostic artifact 13118304850: GitHub SHA-256 8996fd0fb4c5f13163930118309cdbf1fcff4fc15e1f7cf49663be5fbbe11f71, 47,749 bytes and all ZIP CRCs match. All 1033 browser steps succeeded across all 23 suites, including nested viewport reports; recorded browser process exits were zero and no available console/request/collection error arrays contained entries. The new residence scenario confirms 39 settlers retained for 21 game seconds while work is paused, then 40 after resume, using normal construction supplies and controls. Original-media rasters remain private.

The narrow authored-pause correction is complete. Parent #37 remains open for verified original Gold residence values and controls. Published 0.16.0 save/replay behavior remains frozen; new 0.17.0 games use the correction.

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 original tutorial opening no longer stalls in leveling because of unreachable diggers.

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

Progress: residences and workforce (still open)

Residences add settlers one at a time as recorded births; the carrier ratio keeps a share of the population as carriers when staffing; builder and digger limits are player settings; the audit accounts for every settler. Resident counts and intervals are placeholders, so the issue stays open pending verified residence behavior.

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 in 6dfe659: the large residence (15 planks, 24 stone, manual table) is in rules 0.8.0 alongside the small and medium residences. Its resident count and arrival interval are placeholders under buildings.large-residence.residents (U, S3-035), so this issue stays open for verified residence behaviour.