docs/logistics-design.md

Logistics overhaul — brainstorm & phased design

Goal (from the request): make storage finite so collection and production buildings can fill up and stall, and make workers haul goods between them, so logistics stays a live, mindful process that keeps workers relevant to the end of the game. Plus energy efficiency by Reactor proximity with placement cues.

Status: the energy half is done and merged (see below). The *finite-storage

• haulage* half is a core-economy reshape and is designed here for a dedicated, phased implementation — this doc is the plan of record.

---

1. What's already shipped — energy grid efficiency

Energy is a per-tick flow, not a hauled good, so its "logistics" is a placement decision — no workers needed. Implemented in engine/industry.js:

• POWER_TIERS — distance-to-nearest-Reactor bands: on-grid ×1.0 → near ×1.3 → far ×1.7 → isolated ×2.3 (draw multiplier).
• powerEfficiency(state, owner, x, y) — the tier for a spot.
• powerDraw scales every consumer (factory, rig, charging Gate) by its tier, so a remote building bleeds capacity to transmission loss and throttles the whole grid; clustering around a Reactor lets the same Reactors run more of it.

Visual cues mirror the Spaceport's jump radius (render.js): a selected Reactor shows concentric efficiency zones; a build ghost for a power consumer shows the nearest Reactor's zones, a connector, and the tier it would land in ("Far · draw ×1.7"); a selected factory/rig gains a colour-keyed "Grid: … · draws ×N" line (hud.js). Pure distance math — deterministic, DOM-free, no new stored state.

---

2. Finite storage + haulage — the hard half

2.1 The core tension (why this is a real reshape, not a patch)

Today there is ONE global stockpile per side: player.resources (a commodity→float map). Everything reads/writes it:

System	Uses player.resources for
gather.js	workers bank hauls here
industry.js	factories draw inputs here, bank outputs here
rig.js	banks dug raws here
market.js	buy/sell price + settle against it
production.js	canAfford / payCost for units, buildings, upgrades
wonder.js	the Gate's feed is drawn from here
ai.js	every AI economic decision reads it
hud.js	the resource topbar shows it

"Finite per-building storage" means goods no longer live in one global pool — they live in building buffers and only become spendable once hauled to a Command Center. That touches every row above. It must be phased, determinism-first, or it breaks the byte-identical replay law and the AI at once.

2.2 Scope insight — who builds what

The AI builds none of the industry chain (no smelter/assembler/chipfab/ machineworks/reactor/plasmarig/…/torpedoworks). So production-side storage + haulage is player-only and self-contained. The collection-side (Command Center + Refinery/Foundry/Arsenal drop-offs) IS used by the AI, so finite collection storage cascades to AI worker logic — the riskier half.

2.3 Forgotten aspects surfaced by the brainstorm

1. The AI must not deadlock. If drop-offs can fill, the AI's gather loop must reroute or it starves. Simplest safe rule: the AI's Command Center keeps an effectively huge cap (tier-scaled), so the AI never softlocks while the player opts into tighter forward logistics. Alternatively, exempt the AI entirely in phase 1 and only make the player's buildings finite.
2. What is "spendable"? Decide up front: are build/unit/upgrade costs and the market paid from (a) the global pool as today, fed by haulage into the CC, or (b) summed across all buildings? Recommendation: (a) — the CC pool is the treasury; buffers are in-transit inventory. Keeps canAfford/market/AI intact.
3. Determinism. Any "nearest full/needy building" or worker task-assignment must be order-independent and tie-broken deterministically (by id/hash, never by Map iteration + wall clock). Reuse gather.js's nearestDropoff pattern + hashStr.
4. Save/load. New store / input buffers on buildings must be coerced in persist.js cleanEntity (COM-valid keys, ≥0, clamped to cap) exactly like freight and the rig's digProgress.
5. Auto vs manual haulage. Workers should auto-haul (RTS players won't micro every crate), but the player should be able to prioritise a building. Phase 1: fully automatic, nearest-worker/nearest-target, so it "just works".
6. Idle-worker sourcing. Haulage needs a labour pool. Reuse idle workers (no gather order); if none, production simply stalls — which is the intended pressure, not a bug. Surface it ("output full — assign a hauler").
7. Deadlock & starvation UX. A stalled factory (output full / input starved) already has a status line; extend it with the reason and a one-click "haul now".
8. Balance / caps. Buffer sizes set the rhythm. Too big → no logistics pressure; too small → constant micro. Start generous (minutes of runtime per buffer) and tune. CC cap scales with a storeTier (Capital upgrade → bigger treasury).
9. Market side-effect. If output must be hauled before it's sellable, a player with full rig buffers but no haulers can't sell — intended, but must read clearly in the HUD, not as "the market is broken".
10. Freighters. Interplanetary freight already exists (unit.freight); keep it orthogonal — freighters move goods between worlds, workers move goods within a world. Don't conflate. Superseded by Phase D below, which deliberately DOES connect the two: workers can now physically load/unload a landed freighter's hold (the ship becomes a mobile collection point within a world), and a researched freighter can join the within-world haul/service chain itself. The panel-driven load/unload (this section) and the interplanetary jump (unit.freight, moved between worlds) are untouched — Phase D adds a THIRD, physical path onto the same hold, it doesn't replace the first two.

2.4 Phased plan (each phase is its own merge, suite-green + determinism-verified)

Phase A — Output buffer + worker-haulage foundation on the Plasma Rig. ✅ DONE.

• Added building.store (commodity→qty) + def.storeCap, with pure helpers storeTotal/storeRoom/storeCapOf (entities.js).
• updatePlasmaRig banks each dig into store (topping off the final dig to exactly storeCap, overflow spills) and stalls the moment the buffer is full — an unlimited source, no longer an unlimited sink.
• New worker task haul (engine/haul.js): an idle player worker auto-assigns to the nearest own producer whose buffer is ≥34% full (≤2 haulers each, tie-broken by id), walks there, loads a cargo, carries it to the nearest drop-off, and banks it into the treasury 1:1 (no gather multiplier — the goods were already extracted). A per-tick hauler tally (countHaulers) is frozen before assignment for determinism.
• render.js: a gold/red output-buffer gauge under a producer's hull.
• hud.js: rig panel shows "Output NN/CAP (N%)" + a "buffer full → needs a hauler" stall reason.
• persist.js: coerce store (COM-valid, ≥0, clamped to cap); strip the transient haulers tally on serialize (like a unit's _gi).
• Player-only & AI-safe: the auto-haul call is gated to owner === "player", and no skirmish building has a buffer, so the AI and the byte-identical skirmish replay are untouched. Tests: test/haul.test.js (+ rewritten test/rig.test.js).
• Why the Rig first: it's a leaf producer of raw goods — its output doesn't feed another factory, so gating it doesn't half-break the two-hop chain. This proves the whole haulage subsystem (store, task, auto-assign, render, persist, determinism) on the safest surface before it touches the coupled factory chain.

Phase B — Factory output + INPUT buffers = a real supply network. ✅ DONE.

• Factories now get a default output buffer AND a local input larder (both cap 80, via storeCapOf/inputCapOf — any building with a recipe). updateProduction draws inputs from the local larder, banks output to the local store, and stalls when either the larder is empty or the output buffer is full — so a factory only runs while it's been supplied and has room.
• Haulage gained a supply leg (engine/haul.js): an idle player worker picks the nearest own factory that's low on an input the treasury can provide, carries a cargo from the treasury (the CC/warehouse) into the factory's larder. Output is drained by the Phase A haul path, which now covers factories automatically. Idle workers try haul first (clear backlogs / refill the treasury) then supply (feed the starving).
• The chain is now a real network routed through the treasury: raws → CC → supply → smelter → metals → haul → CC → supply → assembler → alloys → haul → CC. Verified end-to-end in the live sim + browser (alloys reach the treasury purely via worker logistics).
• persist.js coerces the input buffer and strips the transient suppliers tally; hud.js factory panel shows the larder + output buffer and a "needs it carried in" starve reason; the map store bar (Phase A) now covers factories too.
• Rewrote the industry.js + strategic.js chain tests to the buffered model; added supply tests to test/haul.test.js. Player-only & AI-safe as in Phase A.

Balance note (both phases): default caps are generous (80 / rig 120). Tune later — smaller = more logistics pressure, larger = less micro.

Phase C — Finite COLLECTION storage. ⤺ REVERTED — Refinery/Foundry/Arsenal are no longer drop-offs. The forward-collection capability described below shipped, then was later removed: the Refinery/Foundry/Arsenal no longer carry dropOff/storeCap, isGatherDropOff now resolves to the Command Center alone, and the AI's forward-Refinery placement logic (aiEconomy.js) was deleted along with it. Every gather/haul trip is a straight run to a Command Center again. Left below for the historical record of what Phase C built and why.

• The forward drop-offs (Refinery/Foundry/Arsenal — the pure dropOff buildings, via the new isGatherDropOff) get a finite storeCap intake buffer. A PLAYER gatherer banks its haul into that buffer (capped); a full one is skipped by nearestGatherDrop so the gatherer reroutes to the next collection point (the Command Center never fills). Phase A haulage clears the buffer to the CC automatically. Factories are excluded from gather drop-offs (their store is refined OUTPUT, not a raw-intake bin).
• The Command Center is the treasury/warehouse — effectively unbounded ("very large storage"): haulage delivers there and supply picks up there (nearestCommandCenter), so goods flow through the CC, never sideways between drop-offs.
• AI-safe by construction: the finite-intake path is gated to owner === "player". An AI drop-off banks straight to the treasury as before, and the AI builds no producers so its workers never haul/supply — so the AI economy and the byte-identical determinism/determinism-roster replays are untouched (verified: full suite green).
• render.js store bar (Phase A) covers forward drop-offs; hud.js shows a selected drop-off's intake buffer + "FULL: gatherers reroute" state. Tests in test/gather.test.js (finite intake + reroute) and test/haul.test.js (AI drop-off stays bufferless).

Known pre-existing issue (surfaced, not caused, by Phase C): two+ workers rapidly cycling a drop-off planted very close to a node can separation-deadlock in the toNode walk (confirmed identical on the pre-Phase-C code). It's a movement/separation bug, out of scope here; a real placement keeps the drop-off far enough from the node to avoid it.

Phase D — Freighters join the local logistics chain. ✅ DONE (player-only, Odyssey-only). Revisits item 10 above: a landed freighter (hauler/heavyhauler/bulkfreighter) is now a physical object on the world map, not just a menu-driven hold, in two ways:

• Workers can load/unload it — FERRY (engine/haul.js updateFerry). Right-click a friendly freighter with workers selected (engine/commands.js issueFerryFreighter, input.js) to assign them to it, the same idiom as issueServiceBuilding. A ferry worker keeps carrying the nearest own producer's backlog straight onto the freighter's freight hold — the freighter becomes its own collection point, no detour through the Command Center — and once there's nothing left to load, draws some of the hold back out and banks it at the treasury instead. Any freighter qualifies, no research needed: this is a worker loading a crate onto a ship, not the ship acting on its own. Shares nearestBacklogProducer with assignHaul (parameterised: a fresh auto-haul still waits for a ≥34%-full buffer; a worker already dedicated to a freighter takes any backlog) and the same per-producer haulers cap, so it can't out-compete regular haulage for labour.
• A freighter can BE the logistics chain — AI-LOGISTICS (FREIGHTER_AI_TECH). A new Datacenter tech, freighterai (requires aicores, costs AI Cores to research), unlocks a per-freighter toggle (unit.aiLogistics, HUD button, engine/commands.js issueSetAILogistics). Toggled on, a freighter offers itself to the SAME assignHaul/assignService idle-worker logic every tick (engine/sim.js) — it grabs a haul or service job exactly like a worker would, but at its own trip capacity: with no cargoCap of its own, tripCapacity() falls back to the ship's whole cargoHold (250/650/1600 vs. a worker's 10), so one autonomous run clears a backlog a worker would need many trips for. Running this way isn't free: every tick an autonomous job is active it burns AI Cores from the treasury (payAIUpkeep, rate scaled by the ship's own cargoHold — a bigger hold costs more to run unmanned). Out of AI Cores, it just pauses in place for the tick (order and cargo untouched) rather than stranding anything; toggling AI-logistics off stands it down immediately. A freighter with no AI Cores in stock also never claims a fresh job in the first place, so it doesn't sit there hogging one of a producer's ≤2 hauler slots while unable to move.
• Both paths reuse the SAME loadFrom/cargo machinery workers already use (generalised to take a plain commodity→qty store instead of a building, so it works against either a building's store or a freighter's freight) — no parallel implementation to keep in sync. freightUsed/freightRoom moved from engine/galaxy.js to engine/entities.js (re-exported from galaxy.js for every existing caller) so engine/haul.js can read a freighter's room without an import cycle (galaxy.js → sim.js → haul.js).
• Player-only and Odyssey-only by construction (freighters are odysseyOnly, the tech is gated behind the Datacenter/aicores, and the sim only ever offers this to owner === "player") — the AI never builds a freighter, so the skirmish AI and its byte-identical replay are untouched. Tests in test/ferry.test.js.

---

Phase E — Command Center zone affinity + a worker REPAIR job. ✅ DONE. Revisits a gap the original four phases didn't cover: on a multi-base empire, every "nearest" job-pick above (nearestBacklogProducer, assignService's factory scan, assignFerry's freighter scan) searched the WHOLE empire from the idle worker's current position with no notion of "which base do I belong to." Once a busy base's own ≤2-per-target caps (MAX_HAULERS/ MAX_SERVERS) filled up, its surplus idle labour got "poached" by whichever OTHER base's job happened to be nearest in that flat global search — a routine long, arbitrary cross-map commute, not just an occasional loan. The same gap existed in the auto-repair Mender's roam target pick (engine/sim.js autoRepairRoam), which also scanned globally by worn-first/distance with no zone awareness.

• Zone affinity (engine/gather.js zoneFirst). A building/unit's "zone" is simply whichever of its owner's Command Centers sits nearest to it — computed on demand, never stored/cached, so founding or losing a CC instantly redraws every boundary with nothing to invalidate. zoneFirst runs a caller-supplied scan TWICE: first restricted to the searcher's own zone, and only if that comes back empty, once more with no restriction — today's plain global search, now a last resort instead of the routine case. A one-CC game (nearly every skirmish, and Odyssey before a player expands) has exactly one zone, so behaviour there is byte-identical to before this existed — verified by a dedicated test alongside the cross-zone ones. nearestBacklogProducer/assignService/assignFerry (engine/haul.js) and the Mender's autoRepairRoam (engine/sim.js, via the new pickRepairTarget below) all adopt it.
• A worker REPAIR job (engine/repair.js). Buildings could only be healed passively by a Mender in range, or by an autoRepair Mender roaming to the worst-off one — nothing stationed labour there when no Mender was around, even though Odyssey structures wear down on their own (updateDecay). A generalist worker can now be assigned a repair order — auto (idle workers offer themselves the same zone-first way haul/service already do, after ferry/haul/service in priority) or manual (right-click a damaged own building with workers selected, issueRepairBuilding — any completed building qualifies, not just a logistics-buffered one). It walks to the building and patches it at a flat WORKER_REPAIR_RATE (free, like a Mender's heal — time, not resources), capped at MAX_REPAIRERS per building so labour spreads out, same shape as the haul/service caps. Buildings only — a Mender already covers wounded mobile units, and a stationary "post a request to the nearest CC" model fits a fixed structure, not a unit that might have moved by the time labour arrives; that's a deliberate v1 scope line, not an oversight. pickRepairTarget (zone-first, worst-hp-fraction-first, the shared NEEDS_REPAIR/HEALED hysteresis thresholds) is exported so the Mender's own roam target-pick reuses the exact same selection logic instead of a second copy.
• AI-safe and deterministic by the same construction as Phases A-D: zone affinity and the repair job are pure functions of state (id-tiebroken, no wall clock), and the Odyssey AI's own worker logistics (engine/aiWorkers.js assignAiLogistics, endless-only) picks up both the zone affinity and the new repair job for free by calling the same engine/haul.js/engine/repair.js functions the player's workers use — its skirmish behaviour is untouched (assignAiLogistics is never invoked outside Odyssey). Tests: test/zones.test.js (cross-base zone preference for haul/service/ferry, plus the single-CC byte-identical case) and test/repairJob.test.js (auto/manual assignment, the repair cap, and zone preference).

Phase F — home-base override + repairing mobile units too. ✅ DONE. Closes the two items Phase E deliberately left for later.

• A player-assigned home base (unit.homeCC, engine/commands.js issueSetHomeBase). Zone-first (Phase E) still GUESSED a unit's home zone from raw nearest-CC distance — usually right, but the player had no way to override it. Right-clicking a completed own Command Center with eligible units selected (worker, Mender, or a freighter — anything that ever consults a zone) now pins unit.homeCC to it; engine/gather.js zoneFirst takes an optional homeId and, when it resolves to a live owned CC, uses it INSTEAD of the distance guess — the player decides which base's territory a unit's jobs stay loyal to, not just proximity (directly answering "the player would be in charge of where sufficient resources are, per area"). It's passive: setting it never interrupts whatever order the unit is already running, only what its NEXT idle job search prefers. A stale override (its CC destroyed, or never valid) is ignored, falling straight back to the distance guess — self-healing, nothing to clean up. Threaded through every zone-first call site: nearestBacklogProducer/assignService/assignFerry/updateFerry's replan (haul.js), pickRepairTarget (repair.js, so both the worker repair job AND the Mender's own autoRepairRoam honor it). HUD: a selected unit with a home base shows a "🏠 Home base assigned" note and a Clear button; a selected Command Center shows how many units call it home.
• Refinement — an explicit assignment is a HARD boundary, not just a tie-break. The first cut of zoneFirst fell back to a global search whenever the (overridden or guessed) home zone came up empty, no matter which way home was picked. That's right for the DEFAULT distance guess (a mere heuristic — widen the search rather than sit idle) but wrong once the player has deliberately assigned a base: a hauler pinned to Command Center A should keep cycling through WHATEVER other jobs A's own zone has to offer, and simply wait when it has none — never reach into Command Center B's territory on its own. zoneFirst now tracks whether home came from a valid override or the distance guess, and only widens to the whole empire in the latter case; a pinned unit with an empty zone gets null (no job, stays idle) until the player reassigns it to a different CC (right-click it — issueSetHomeBase overwrites the old assignment) or clears it outright (the HUD's "Clear home base" button, or setting homeCC = null — "assign to nothing"). This is also exactly why a building-level manual assignment (issueServiceBuilding/issueRepair/issueFerryFreighter, order.manual) was left untouched: it was ALREADY a hard, single-target lock (the worker loops on that one building/freighter forever once done, never auto-reassigned) — the contrast is intentional. A CC assignment is a territory (flexible among whatever's inside it); a building assignment is a target (one specific thing, no substitutes). Tests: test/zones.test.js (a pinned empty zone stays idle rather than poaching; reassigning to a different CC immediately redraws the boundary; clearing the override restores the old lenient default).
• A worker can now repair a wounded mobile UNIT, not just a building. pickRepairTarget already supported includeUnits; assignRepair now leaves it at the default (true) instead of forcing buildings-only, so a worker's auto-assigned or manually-issued (issueRepair, renamed from issueRepairBuilding — now takes either a building or unit id) repair job can chase and patch a hurt Ranger/Bastion/etc. the same way it patches a turret — walking toward the target's LIVE position each tick, the same idiom the Mender's own roam already uses for a moving target. The order's buildingId field became a generic targetId (resolved via state.js getEntity, building OR unit) to match. A worker still never repairs itself (exclude: unit). This doesn't replace the Mender — a Mender still heals passively/for free in an AoE and can roam on its own — it just means a damaged unit isn't stranded with nothing to do about it when no Mender is nearby.
• Tests: test/zones.test.js (a home-base override wins over both raw proximity and the usual nearest-CC guess; a stale override falls back gracefully), test/repairJob.test.js (a wounded unit is now a valid auto-assigned AND chased-and-healed target; a worker never targets itself), and test/commands.test.js (issueSetHomeBase's role gating and its passivity; issueRepair's gating). Same AI-safety/determinism shape as every phase above — no wall clock, no unseeded randomness, skirmish AI untouched.

Outcome

All six phases shipped (Phase C was later reverted — see above: the Refinery/Foundry/Arsenal are no longer drop-offs, and all collection now runs straight to the Command Center). Storage is finite end-to-end — production output (rig + factories) and factory inputs — and workers move every good between them (gather → CC → supply → factory → haul → CC). A landed freighter now sits IN that chain too — a physical collection point workers can ferry to directly, or (once teched) a large-capacity autonomous hauler in its own right, paid for in AI Cores while it runs. Logistics is a standing demand on labour (and, for an automated fleet, on AI Cores) to the end of the game, with the Command Center as the one bottomless warehouse. On a multi-base empire, every job (haul, service, ferry, repair) is discovered zone-first — and the player can pin a unit's home base outright, overriding the distance guess — so labour stays loyal to its own base instead of routinely commuting across the map. A worker can now actively repair a damaged building OR a wounded mobile unit, not just a passing Mender. Energy stays a placement decision (grid efficiency), no workers. Everything player-only (or, for zone affinity and repair, ALSO extended to the Odyssey AI's own logistics workers, by construction never the skirmish AI) and deterministic; the AI and skirmish replays are byte-identical.

2.5 Recommended order & risk

Phase A (low risk, player-only, self-contained, immediately satisfying) → Phase B (medium, builds the supply network) → Phase C (higher, touches the AI & market, needs the most careful determinism pass). Ship and play-test each before the next; do not attempt all three in one pass.