Inter-Colony Energy Assistance MVP

This milestone adds one narrow autonomous energy-assistance route between existing visible owned colonies. It does not claim rooms, use terminals, trade, or perform general resource balancing.

Authority And Admission

The recipient owns the compact record at Memory.rooms[recipient].interColonyEnergyAssistance. A room first requests support when its persisted Storage reserve falls below the minimum operating reserve plus a 500-energy admission margin. This admits a colony that is close to exhausting its protected operating reserve without waiting for a deeper deficit. Spawn energy noise alone is not an admission signal, and the MVP requires completed owned Storage at both ends.

After admission, the request remains latched until reserve reaches a recovery threshold above the minimum operating reserve. The margin is 20% of the gap from minimum to target reserve, clamped to 500–2,000 energy. This hysteresis prevents repeated admission changes around the entry threshold. One grant is bounded by the recovery deficit, donor budget, and 10,000 energy. Once the grant is transferred, the request waits for recovery before it can rearm.

A donor must be visible and owned, adjacent by linear room distance, have primary Storage, cover its current essential local harvester and ordinary hauler demand, remain out of economy emergency and engaged/critical defense, and hold EconomyManager surplus-spending permission. Its available assistance budget is exactly reservePolicy.surplusEnergy, so the transfer cannot consume the target reserve or the configured 5,000-energy surplus margin. A grant must be at least 500 energy. The MVP permits at most one active recipient per donor and one donor per recipient.

Transport

An active grant adds exactly one ordinary hauler slot above existing local, remote, industry, and storage-link demand. The additive slot and assignment identity prevent assistance from consuming essential local hauling capacity. The spawned hauler receives explicit interColonyEnergyAssistance memory; no new role is introduced.

The hauler withdraws only the remaining authorized amount from donor Storage, crosses to the recipient with the shared room-transition workflow, and calls the existing recipient hauler-delivery selector. Spawn, extension, tower, Storage, controller-buffer, and overflow priorities therefore remain under the recipient's ordinary economy policy. The hauler returns for another bounded load until authorization is exhausted or the request ends.

If ownership, request identity, donor reserve authority, workforce safety, or room validity disappears, new withdrawals stop. The hauler returns carried energy to the donor through normal delivery priorities and then clears its assignment. Stale creep names are replaced only after the old assignment has cleared.

CPU And Observability

The coordinator runs once per tick after all owned RoomManagers. It reuses the tick-local room contexts and persisted economy assessments, performs no room searches or pathfinding, and records cost under Memory.stats.cpu.profile.sections.interColonyAssistance. Movement pathfinding occurs only in the assigned creep's ordinary execution.

Use:

debug.colonies()
debug.colony("E49N14")
debug.creep("<assigned hauler name>")

The room detail includes state, deficit, recovery target, donor, current donor budget, authorized/transferred energy, assigned creep, and the current reason. Numeric gauges are documented in STATS.md.

Verification

npm run verify:inter-colony-assistance
npm run build
npm run check

For the motivating live pilot, inspect debug.colony("E49N14") and confirm the selected donor is E48N14 when E49N14 Storage is below 5,500 energy, then inspect the named creep through one withdrawal, cross-room delivery, and return. Confirm E48N14 remains above its surplus threshold and that E49N14 exits only after reaching its reported 7,000-energy recovery reserve. Deployment remains an explicit operator action.