S3-047: Complete economic distribution controls

Parent and ownership

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

Problem and observable result

Apply food and transport preferences through deliveries. Persist production priorities. Avoid direct settlement-stock adjustments.

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

Production consumes physically delivered inputs and staffed work. Bounded output inventories create backpressure. Controls change production and carrier decisions rather than settlement totals directly.

• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/ec_jobs/jops.htm
• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/in_menu/menu.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

• Apply food and transport preferences through deliveries.
• Persist production priorities.
• Avoid direct settlement-stock adjustments.
• 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 consumer weights during shortages.
• Round-trip settings through saves.
• 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/47
• https://github.com/stacksjs/the-settlers-iii-remake/issues/48

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 (S3-047, still open)

Transport priority and storage eligibility drive deliveries and persist in saves; no settlement stock is adjusted directly. Per-consumer distribution weights (which buildings get coal or food first) are not implemented yet.

Implementation: resources/game/engine/production.ts, workforce.ts, logistics.ts; tests in tests/unit/engine-economy.test.ts and tests/unit/engine-audit.test.ts.

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: the Goods menu exposes the transport priority chain (top, up, down, last), store or don't store, and urgent orders and priority weights for the tool smith and the weapon smith (weapons were added in 91d0a7b, as the manual's Tools and Weapons menu describes). Still missing: the manual's per-building Distribution of Goods shares (which buildings receive a good first). That needs a delivery rule change in logistics.ts and stays open here.

Completed in d4317a8 and 17656df, with the earlier production-priority work (S3-045).

• Food and transport preferences through deliveries:
  • The transport chain orders carriers' trips; construction always comes first and storage last.
  • The manual's Distribution of Goods shares (0 to 10 per good and consuming building type, default 1) decide which kind of building receives a good. Deliveries are placed one unit at a time with the type furthest below its share, and a share of zero sends none.
  • Food for the three mine types is distributed the same way as coal or iron.
  • Every change moves physical goods by carrier; no stock is adjusted directly.
• Production priorities persisted: urgent orders and weights for the tool smith and the weapon smith (weapons added in 91d0a7b), transport order, stored goods, distribution shares and the delivery counts the shares are measured against are all saved and validated.
• Visible result: the Goods menu has Inventory, Tools and weapons, Distribution and Transport sub-menus (91d0a7b, d4317a8). Invalid shares are refused with a reason.

Tests (tests/unit/engine-distribution.test.ts):

• an even split, a zero share and a 3:1 split of eight coal between two smiths during a shortage
• shares round-tripping through a save with identical continuation
• the transport chain choosing a lone carrier's first trip either way round