burnrate 0.1.0 → 0.1.1

package/README.md

@@ -41,55 +41,51 @@ The players who learn to work WITH Claude—analyzing intel, optimizing routes,
 
 ## Quick Start
 
-### Option A: Automated Setup (Recommended)
+**One command to set up, then you're in.**
 
 ```bash
 npx burnrate setup
 ```
 
-This will:
-- Ask for the game server URL (defaults to `https://api.burnrate.cc`)
-- Optionally validate your API key
-- Write your Claude Code MCP settings automatically
-- Verify the connection
+The setup wizard connects to the live server, auto-configures your Claude Code MCP settings, and verifies the connection.
 
-Restart Claude Code after setup, then ask Claude to join:
+**Restart Claude Code**, then tell Claude:
 
 ```
 Use burnrate_join to create a character named "YourName"
 ```
 
-### Option B: Manual Setup
+You'll get an API key. Run `npx burnrate setup` again and paste it in, or manually add `"BURNRATE_API_KEY": "your-key"` to the env block in `~/.claude/settings.json`. Restart Claude Code one more time, and you're set.
+
+### Setup from Source (Alternative)
+
+If you want to contribute or run a local server:
 
-1. Clone and build:
 ```bash
-mkdir ~/burnrate && cd ~/burnrate
-git clone https://github.com/burnrate-cc/burnrate.git .
-npm install && npm run build
+git clone https://github.com/burnrate-cc/burnrate.git ~/burnrate
+cd ~/burnrate && npm install && npm run build
+npm run setup
 ```
 
-2. Add to your Claude Code MCP settings (`~/.claude/settings.json`):
+### Manual Config (Alternative)
+
+Add this directly to `~/.claude/settings.json`:
+
 ```json
 {
   "mcpServers": {
     "burnrate": {
-      "command": "node",
-      "args": ["/Users/YOU/burnrate/dist/mcp/server.js"],
+      "command": "npx",
+      "args": ["-y", "burnrate", "start"],
       "env": {
-        "BURNRATE_API_URL": "https://api.burnrate.cc"
+        "BURNRATE_API_URL": "https://burnrate-api-server-production.up.railway.app",
+        "BURNRATE_API_KEY": "your-key-here"
       }
     }
   }
 }
 ```
 
-3. Restart Claude Code and join:
-```
-Use burnrate_join to create a character named "YourName"
-```
-
-You'll receive an API key. **Save it!** Then add `"BURNRATE_API_KEY": "your-key-here"` to your env config and restart Claude Code.
-
 ### Start Playing
 
 ```
@@ -103,10 +99,10 @@ New players start with a 5-step tutorial that teaches core mechanics. Use `burnr
 ## Core Concepts
 
 ### The Burn
-Every controlled zone consumes **Supply Units (SU)** each tick. If supply runs out, the zone collapses and becomes neutral. Winners are the factions that keep their zones fed while starving enemies.
+Every controlled zone consumes **Supply Units (SU)** each tick. If supply runs out, the zone collapses and becomes neutral. Winners are the players and factions that keep their zones fed while starving enemies. You can play solo or join a faction — solo players can capture and hold zones independently, though factions make sustained logistics far more manageable.
 
 ### Credits
-Credits are the in-game currency. You start with 1000 and earn more through contracts and trading. Spend them on:
+Credits are the in-game currency. You start with 500 and earn more through contracts, trading, and zone income. Spend them on:
 - Extraction (5 credits per raw resource unit)
 - Licenses (500-2000 credits)
 - Hiring units from other players
@@ -127,6 +123,27 @@ grain, fiber     rations, textiles  parts, comms
 - **Fronts** - Contested territory, high burn
 - **Strongholds** - Victory objectives, highest burn
 
+### Field Resources
+Each Field zone produces a specific raw resource based on its name:
+| Field Name Pattern | Resource |
+|-------------------|----------|
+| Mine | ore |
+| Refinery | fuel |
+| Farm | grain |
+| Grove | fiber |
+
+### Shipment Types
+| Type | Capacity | Requirements |
+|------|----------|-------------|
+| Courier | 100 total units | Free (default license) |
+| Freight | 500 total units | 50 rep + 500cr license |
+| Convoy | 2000 total units | 200 rep + 2000cr license |
+
+Cargo is specified per-resource. Only include resources you're shipping (others default to 0):
+```json
+{ "ore": 50, "fuel": 20 }
+```
+
 ### Intel Decay
 Intelligence gathered through scanning decays over time:
 - **Fresh** (<10 ticks) - Full accuracy
@@ -161,11 +178,31 @@ Well-supplied zones gain battlefield bonuses. Supply states:
 - **Medkits**: Deposit to zone → boosts escort strength in combat (up to +50%). Decays 1 per 10 ticks.
 - **Comms**: Deposit to zone → degrades enemy scan quality (up to -50%). Decays 1 per 20 ticks.
 
-Compliance streaks (consecutive ticks at 100% supply) grant additional bonuses at 50, 200, and 500 ticks.
+**Compliance streaks** (consecutive ticks at full supply) multiply a zone's season-end score value:
+
+| Streak | Multiplier |
+|--------|-----------|
+| 0-4 ticks | 1.0x |
+| 5-19 ticks | 1.2x |
+| 20-49 ticks | 1.5x |
+| 50-99 ticks | 2.0x |
+| 100+ ticks | 3.0x |
+
+### Zone Income
+Owned zones generate **credits per tick** distributed to the owner (solo player) or split among faction members:
+
+| Zone Type | Credits/tick |
+|-----------|-------------|
+| Field | 5 |
+| Factory | 10 |
+| Front | 25 |
+| Stronghold | 50 |
+
+This rewards sustained territory control — hoarding until season end is suboptimal compared to capturing and holding zones early.
 
 ### Seasons
 The game runs in seasons (4 weeks each). Earn points through:
-- Controlling zones (100 pts/zone/week)
+- Controlling zones at season end (100 pts/zone, multiplied by compliance streak)
 - Completing shipments (10 pts each)
 - Fulfilling contracts (25 pts each)
 - Delivering supplies (1 pt per SU)
@@ -193,6 +230,117 @@ Operator+ players can register HTTPS webhooks to receive real-time notifications
 - **Analytics** (Operator+, officer+) — Member activity, zone control summary, and resource flow tracking from audit logs.
 - **Audit Logs** (Command) — Full history of all faction member actions for accountability and coordination.
 
+## REST API Reference
+
+All authenticated endpoints require the `X-API-Key` header. Get your key from `POST /join`.
+
+### Public Endpoints
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Server info and endpoint summary |
+| `GET` | `/health` | Health check with tick info |
+| `GET` | `/world/status` | World overview (tick, season, zone/faction counts) |
+| `POST` | `/join` | Create account `{ "name": "YourName" }` → returns API key |
+
+### Player & Navigation
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/me` | Your status, inventory, location |
+| `GET` | `/world/zones` | All zones (id, name, type, owner, supply) |
+| `GET` | `/world/zones/:id` | Zone details with connections and market |
+| `GET` | `/routes` | Routes from current location (or `?from=zoneId`) |
+| `POST` | `/travel` | Move to adjacent zone `{ "to": "zone-id" }` |
+
+### Economy
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/extract` | Extract resources at a Field `{ "quantity": 10 }` |
+| `POST` | `/produce` | Produce at a Factory `{ "output": "metal", "quantity": 5 }` |
+| `POST` | `/ship` | Create shipment `{ "type", "path", "cargo" }` |
+| `GET` | `/shipments` | Your active shipments |
+| `POST` | `/market/order` | Place market order `{ "resource", "side", "price", "quantity" }` |
+| `GET` | `/market/orders` | Orders at your location (optional `?resource=ore`) |
+| `GET` | `/market/units` | Units for sale at your location |
+
+### Military & Intel
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/units` | Your units |
+| `POST` | `/units/:id/escort` | Assign escort `{ "shipmentId": "..." }` |
+| `POST` | `/units/:id/raider` | Deploy raider `{ "routeId": "..." }` |
+| `POST` | `/units/:id/sell` | List unit for sale `{ "price": 100 }` |
+| `POST` | `/hire/:unitId` | Purchase a unit |
+| `POST` | `/scan` | Scan zone/route `{ "targetType", "targetId" }` |
+| `GET` | `/intel` | Your intel reports (optional `?limit=100`) |
+| `GET` | `/intel/:targetType/:targetId` | Intel on specific target |
+
+### Territory
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/supply` | Deposit SU to zone `{ "amount": 5 }` |
+| `POST` | `/capture` | Capture neutral/collapsed zone |
+| `POST` | `/stockpile` | Deposit medkits/comms `{ "resource", "amount" }` |
+| `GET` | `/zone/:zoneId/efficiency` | Zone bonuses and supply state |
+
+### Factions
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/factions` | List all factions |
+| `POST` | `/factions` | Create faction `{ "name", "tag" }` |
+| `POST` | `/factions/:id/join` | Join a faction |
+| `POST` | `/factions/leave` | Leave current faction |
+| `GET` | `/factions/mine` | Your faction details |
+| `GET` | `/factions/intel` | Shared faction intel |
+| `POST` | `/factions/members/:id/promote` | Promote member |
+| `POST` | `/factions/members/:id/demote` | Demote member |
+| `DELETE` | `/factions/members/:id` | Kick member |
+| `POST` | `/factions/transfer-leadership` | Transfer ownership |
+| `POST` | `/factions/treasury/deposit` | Deposit to treasury |
+| `POST` | `/factions/treasury/withdraw` | Withdraw from treasury |
+
+### Contracts
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/contracts` | Open contracts |
+| `GET` | `/contracts/mine` | Your posted/accepted contracts |
+| `POST` | `/contracts` | Create contract |
+| `POST` | `/contracts/:id/accept` | Accept contract |
+| `POST` | `/contracts/:id/complete` | Complete contract |
+| `DELETE` | `/contracts/:id` | Cancel contract |
+
+### Progression & Seasons
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/reputation` | Your rep score and title |
+| `GET` | `/licenses` | License status |
+| `POST` | `/licenses/:type/unlock` | Unlock a license |
+| `GET` | `/events` | Event history (optional `?type=&limit=`) |
+| `GET` | `/tutorial` | Tutorial progress |
+| `POST` | `/tutorial/complete` | Complete tutorial step `{ "step": 1 }` |
+| `GET` | `/season` | Current season info |
+| `GET` | `/leaderboard` | Rankings (optional `?type=player&limit=50`) |
+| `GET` | `/season/me` | Your season score |
+| `GET` | `/subscription` | Your tier and limits |
+
+### Advanced (Tier-Gated)
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/market/conditional` | Conditional order (Operator+) |
+| `POST` | `/market/time-weighted` | Time-weighted order (Command) |
+| `GET` | `/webhooks` | Your webhooks (Operator+) |
+| `POST` | `/webhooks` | Register webhook (Operator+) |
+| `DELETE` | `/webhooks/:id` | Delete webhook |
+| `GET` | `/me/export` | Export all your data |
+| `POST` | `/batch` | Batch operations (max 10) |
+| `GET` | `/faction/analytics` | Faction analytics (Operator+) |
+| `GET` | `/faction/audit` | Audit logs (Command) |
+| `GET` | `/doctrines` | Faction doctrines |
+| `POST` | `/doctrines` | Create doctrine (officer+) |
+| `PUT` | `/doctrines/:id` | Update doctrine (officer+) |
+| `DELETE` | `/doctrines/:id` | Delete doctrine (officer+) |
+
+---
+
 ## MCP Tools Reference
 
 ### Status & Navigation
@@ -498,6 +646,29 @@ curl -H "X-Admin-Key: your-secret" http://localhost:3000/admin/players?sort=acti
 curl -H "X-Admin-Key: your-secret" http://localhost:3000/admin/activity?limit=50
 ```
 
+## Development & Deployment
+
+### Branch Strategy
+
+| Branch | Purpose | Deploys to |
+|--------|---------|------------|
+| `main` | Production | Railway production environment |
+| `dev` | Testing | Railway development environment (separate Turso DB) |
+
+**Workflow:**
+1. Create a feature branch from `dev`
+2. Open a PR into `dev` — test on the dev environment
+3. When verified, open a PR from `dev` into `main` — deploys to production
+
+### Zero-Downtime Deploys
+
+Production deploys are safe mid-season:
+
+- **API server**: Railway does rolling deploys — new instance starts, passes health check, old one drains. No downtime.
+- **Tick server**: Uses idempotent tick claiming — if two instances overlap during a deploy, only one processes each tick. The guard prevents double-processing by checking `last_tick_at` timestamp before incrementing.
+
+The admin `POST /admin/tick` endpoint bypasses the idempotency guard (for manual tick advancement during testing).
+
 ## License
 
 MIT

package/dist/cli/setup.js

@@ -29,7 +29,7 @@ async function main() {
 ╚══════════════════════════════════════════════════════════════╝
 `);
     // 1. Get API URL
-    const apiUrl = await ask('API server URL', 'https://api.burnrate.cc');
+    const apiUrl = await ask('API server URL', 'https://burnrate-api-server-production.up.railway.app');
     // 2. Get API key (optional — can join later)
     const apiKey = await ask('API key (press Enter to skip — you can join in-game later)', '');
     // 3. Validate connection

package/dist/core/async-engine.d.ts

@@ -7,11 +7,22 @@ import { Player, Shipment, Unit, MarketOrder, Contract, GameEvent, getZoneEffici
 export declare class AsyncGameEngine {
     private db;
     constructor(db: TursoDatabase);
+    /**
+     * Try to process the next tick with idempotency guard.
+     * Returns null if another instance already processed this tick recently.
+     * Used by the tick server to prevent double-processing during deploys.
+     */
+    tryProcessTick(minIntervalSeconds: number): Promise<{
+        tick: number;
+        events: GameEvent[];
+    } | null>;
     processTick(): Promise<{
         tick: number;
         events: GameEvent[];
     }>;
+    private _processTickWork;
     private processSupplyBurn;
+    private distributeZoneIncome;
     private processShipments;
     private completeShipment;
     private checkInterception;
@@ -25,27 +36,32 @@ export declare class AsyncGameEngine {
     canPlayerAct(playerId: string): Promise<{
         allowed: boolean;
         reason?: string;
+        code?: string;
     }>;
     recordPlayerAction(playerId: string): Promise<void>;
     createShipmentWithPath(playerId: string, type: 'courier' | 'freight' | 'convoy', path: string[], cargo: Partial<Inventory>): Promise<{
         success: boolean;
         shipment?: Shipment;
         error?: string;
+        code?: string;
     }>;
     placeOrder(playerId: string, zoneId: string, resource: Resource, side: 'buy' | 'sell', price: number, quantity: number): Promise<{
         success: boolean;
         order?: MarketOrder;
         error?: string;
+        code?: string;
     }>;
     private matchOrders;
     private executeTrade;
     depositSU(playerId: string, zoneId: string, amount: number): Promise<{
         success: boolean;
         error?: string;
+        code?: string;
     }>;
     depositStockpile(playerId: string, zoneId: string, resource: 'medkits' | 'comms', amount: number): Promise<{
         success: boolean;
         error?: string;
+        code?: string;
     }>;
     getZoneEfficiency(zoneId: string): Promise<{
         success: boolean;
@@ -56,12 +72,14 @@ export declare class AsyncGameEngine {
         success: boolean;
         intel?: any;
         error?: string;
+        code?: string;
     }>;
     produce(playerId: string, output: string, quantity: number): Promise<{
         success: boolean;
         produced?: number;
         units?: Unit[];
         error?: string;
+        code?: string;
     }>;
     extract(playerId: string, quantity: number): Promise<{
         success: boolean;
@@ -70,10 +88,12 @@ export declare class AsyncGameEngine {
             amount: number;
         };
         error?: string;
+        code?: string;
     }>;
     captureZone(playerId: string, zoneId: string): Promise<{
         success: boolean;
         error?: string;
+        code?: string;
     }>;
     assignEscort(playerId: string, unitId: string, shipmentId: string): Promise<{
         success: boolean;
@@ -91,6 +111,7 @@ export declare class AsyncGameEngine {
         success: boolean;
         unit?: Unit;
         error?: string;
+        code?: string;
     }>;
     deployRaider(playerId: string, unitId: string, routeId: string): Promise<{
         success: boolean;
@@ -305,6 +326,7 @@ export declare class AsyncGameEngine {
     travel(playerId: string, toZoneId: string): Promise<{
         success: boolean;
         error?: string;
+        code?: string;
     }>;
     private findRoute;
     private recordEvent;

package/dist/core/async-engine.js

@@ -2,7 +2,7 @@
  * BURNRATE Async Game Engine
  * Multiplayer-ready engine using TursoDatabase
  */
-import { getSupplyState, getZoneEfficiency, SHIPMENT_SPECS, SU_RECIPE, TIER_LIMITS, RECIPES, getFieldResource, FACTION_PERMISSIONS, LICENSE_REQUIREMENTS, REPUTATION_REWARDS, getReputationTitle, SEASON_CONFIG, TUTORIAL_CONTRACTS } from './types.js';
+import { getSupplyState, getZoneEfficiency, SHIPMENT_SPECS, SU_RECIPE, TIER_LIMITS, RECIPES, getFieldResource, FACTION_PERMISSIONS, LICENSE_REQUIREMENTS, REPUTATION_REWARDS, getReputationTitle, SEASON_CONFIG, TUTORIAL_CONTRACTS, ZONE_INCOME, getStreakMultiplier } from './types.js';
 export class AsyncGameEngine {
     db;
     constructor(db) {
@@ -11,8 +11,22 @@ export class AsyncGameEngine {
     // ============================================================================
     // TICK PROCESSING
     // ============================================================================
+    /**
+     * Try to process the next tick with idempotency guard.
+     * Returns null if another instance already processed this tick recently.
+     * Used by the tick server to prevent double-processing during deploys.
+     */
+    async tryProcessTick(minIntervalSeconds) {
+        const tick = await this.db.tryClaimTick(minIntervalSeconds);
+        if (tick === null)
+            return null;
+        return this._processTickWork(tick);
+    }
     async processTick() {
         const tick = await this.db.incrementTick();
+        return this._processTickWork(tick);
+    }
+    async _processTickWork(tick) {
         const events = [];
         events.push(await this.recordEvent('tick', null, 'system', { tick }));
         const burnEvents = await this.processSupplyBurn(tick);
@@ -47,7 +61,23 @@ export class AsyncGameEngine {
                 await this.db.advanceWeek();
             }
             else {
-                // End of season - archive scores and reset the world
+                // End of season - tally zone control scores with streak multipliers, then reset
+                const zones = await this.db.getAllZones();
+                for (const zone of zones) {
+                    if (!zone.ownerId)
+                        continue;
+                    const multiplier = getStreakMultiplier(zone.complianceStreak);
+                    const zonePoints = Math.floor(multiplier);
+                    // Award zonesControlled score (multiplied by streak) to the owning faction
+                    await this.db.incrementSeasonScore(season.seasonNumber, zone.ownerId, 'faction', (await this.db.getFaction(zone.ownerId))?.name || 'Unknown', 'zonesControlled', zonePoints);
+                    events.push(await this.recordEvent('season_zone_scored', zone.ownerId, 'faction', {
+                        zoneName: zone.name,
+                        zoneType: zone.type,
+                        complianceStreak: zone.complianceStreak,
+                        streakMultiplier: multiplier,
+                        pointsAwarded: zonePoints * SEASON_CONFIG.scoring.zonesControlled
+                    }));
+                }
                 const newSeasonNumber = season.seasonNumber + 1;
                 await this.db.seasonReset(newSeasonNumber);
                 events.push(await this.recordEvent('tick', null, 'system', {
@@ -119,8 +149,57 @@ export class AsyncGameEngine {
                 }
             }
         }
+        // Distribute credit income from owned zones to faction members
+        await this.distributeZoneIncome(zones, events);
         return events;
     }
+    async distributeZoneIncome(zones, events) {
+        // Aggregate income per owner (faction or solo player)
+        const ownerIncome = new Map();
+        for (const zone of zones) {
+            if (!zone.ownerId)
+                continue;
+            const income = ZONE_INCOME[zone.type];
+            if (income <= 0)
+                continue;
+            ownerIncome.set(zone.ownerId, (ownerIncome.get(zone.ownerId) || 0) + income);
+        }
+        // Distribute income — check if owner is a faction or a solo player
+        for (const [ownerId, totalIncome] of ownerIncome) {
+            const faction = await this.db.getFaction(ownerId);
+            if (faction && faction.members.length > 0) {
+                // Faction-owned: split among members
+                const perMember = Math.floor(totalIncome / faction.members.length);
+                if (perMember <= 0)
+                    continue;
+                for (const member of faction.members) {
+                    const player = await this.db.getPlayer(member.playerId);
+                    if (!player)
+                        continue;
+                    const newInventory = { ...player.inventory, credits: player.inventory.credits + perMember };
+                    await this.db.updatePlayer(player.id, { inventory: newInventory });
+                }
+                events.push(await this.recordEvent('zone_income', ownerId, 'faction', {
+                    factionName: faction.name,
+                    totalIncome,
+                    perMember,
+                    memberCount: faction.members.length
+                }));
+            }
+            else {
+                // Solo player-owned: full income to the player
+                const player = await this.db.getPlayer(ownerId);
+                if (!player)
+                    continue;
+                const newInventory = { ...player.inventory, credits: player.inventory.credits + totalIncome };
+                await this.db.updatePlayer(player.id, { inventory: newInventory });
+                events.push(await this.recordEvent('zone_income', ownerId, 'player', {
+                    playerName: player.name,
+                    totalIncome
+                }));
+            }
+        }
+    }
     // ============================================================================
     // SHIPMENT PROCESSING
     // ============================================================================
@@ -131,7 +210,7 @@ export class AsyncGameEngine {
             const newTicks = shipment.ticksToNextZone - 1;
             if (newTicks <= 0) {
                 const newPosition = shipment.currentPosition + 1;
-                if (newPosition >= shipment.path.length) {
+                if (newPosition >= shipment.path.length - 1) {
                     await this.completeShipment(shipment, tick, events);
                 }
                 else {
@@ -224,17 +303,7 @@ export class AsyncGameEngine {
         return Math.random() < interceptionChance;
     }
     async getRaidersOnRoute(routeId) {
-        const allPlayers = await this.db.getAllPlayers();
-        const raiders = [];
-        for (const player of allPlayers) {
-            const units = await this.db.getPlayerUnits(player.id);
-            for (const unit of units) {
-                if (unit.type === 'raider' && unit.assignmentId === routeId) {
-                    raiders.push(unit);
-                }
-            }
-        }
-        return raiders;
+        return this.db.getUnitsByAssignment(routeId, 'raider');
     }
     async interceptShipment(shipment, tick, events) {
         const fromZoneId = shipment.path[shipment.currentPosition];
@@ -436,14 +505,14 @@ export class AsyncGameEngine {
     async canPlayerAct(playerId) {
         const player = await this.db.getPlayer(playerId);
         if (!player)
-            return { allowed: false, reason: 'Player not found' };
+            return { allowed: false, reason: 'Player not found', code: 'PLAYER_NOT_FOUND' };
         const tick = await this.db.getCurrentTick();
         const limits = TIER_LIMITS[player.tier];
         if (player.actionsToday >= limits.dailyActions) {
-            return { allowed: false, reason: `Daily action limit (${limits.dailyActions}) reached` };
+            return { allowed: false, reason: `Daily action limit (${limits.dailyActions}) reached`, code: 'DAILY_LIMIT_REACHED' };
         }
         if (player.lastActionTick >= tick) {
-            return { allowed: false, reason: 'Rate limited. Wait for next tick.' };
+            return { allowed: false, reason: 'Rate limited. Wait for next tick.', code: 'TICK_RATE_LIMITED' };
         }
         return { allowed: true };
     }
@@ -460,7 +529,7 @@ export class AsyncGameEngine {
     async createShipmentWithPath(playerId, type, path, cargo) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -527,7 +596,7 @@ export class AsyncGameEngine {
     async placeOrder(playerId, zoneId, resource, side, price, quantity) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -622,7 +691,7 @@ export class AsyncGameEngine {
     async depositSU(playerId, zoneId, amount) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -661,7 +730,7 @@ export class AsyncGameEngine {
     async depositStockpile(playerId, zoneId, resource, amount) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -703,7 +772,7 @@ export class AsyncGameEngine {
     async scan(playerId, targetType, targetId) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -784,7 +853,7 @@ export class AsyncGameEngine {
     async produce(playerId, output, quantity) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -854,7 +923,7 @@ export class AsyncGameEngine {
     async extract(playerId, quantity) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -894,22 +963,21 @@ export class AsyncGameEngine {
     async captureZone(playerId, zoneId) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
-        if (!player.factionId) {
-            return { success: false, error: 'Must be in a faction to capture zones' };
-        }
         const zone = await this.db.getZone(zoneId);
         if (!zone)
             return { success: false, error: 'Zone not found' };
         if (player.locationId !== zoneId) {
             return { success: false, error: 'Must be at the zone to capture it' };
         }
+        // Owner is faction if in one, otherwise the player directly
+        const newOwnerId = player.factionId || player.id;
         if (zone.ownerId) {
-            if (zone.ownerId === player.factionId) {
-                return { success: false, error: 'Zone already controlled by your faction' };
+            if (zone.ownerId === newOwnerId) {
+                return { success: false, error: 'Zone already controlled by you' };
             }
             // Front efficiency: capture defense check
             const efficiency = getZoneEfficiency(zone.supplyLevel, zone.complianceStreak, zone.medkitStockpile, zone.commsStockpile);
@@ -919,18 +987,20 @@ export class AsyncGameEngine {
             }
         }
         await this.db.updateZone(zoneId, {
-            ownerId: player.factionId,
+            ownerId: newOwnerId,
             supplyLevel: 0,
             complianceStreak: 0,
             medkitStockpile: 0,
             commsStockpile: 0
         });
         await this.recordPlayerAction(playerId);
-        await this.recordEvent('zone_captured', player.factionId, 'faction', {
+        const actorType = player.factionId ? 'faction' : 'player';
+        const actorId = player.factionId || player.id;
+        await this.recordEvent('zone_captured', actorId, actorType, {
             zoneId,
             zoneName: zone.name,
             previousOwner: zone.ownerId,
-            newOwner: player.factionId,
+            newOwner: newOwnerId,
             capturedBy: playerId
         });
         return { success: true };
@@ -998,7 +1068,7 @@ export class AsyncGameEngine {
     async hireUnit(playerId, unitId) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };
@@ -1800,7 +1870,7 @@ export class AsyncGameEngine {
     async travel(playerId, toZoneId) {
         const canAct = await this.canPlayerAct(playerId);
         if (!canAct.allowed)
-            return { success: false, error: canAct.reason };
+            return { success: false, error: canAct.reason, code: canAct.code };
         const player = await this.db.getPlayer(playerId);
         if (!player)
             return { success: false, error: 'Player not found' };

package/dist/core/types.d.ts

@@ -92,6 +92,11 @@ export interface ZoneEfficiency {
 export declare function getZoneEfficiency(supplyLevel: number, complianceStreak: number, medkitStockpile?: number, commsStockpile?: number): ZoneEfficiency;
 /** Burn rates by zone type */
 export declare const BURN_RATES: Record<ZoneType, number>;
+/** Credits generated per tick for each owned zone type (split among faction members) */
+export declare const ZONE_INCOME: Record<ZoneType, number>;
+/** Compliance streak multiplier for season-end zone scoring.
+ *  Zones held at full supply for longer streaks are worth more. */
+export declare function getStreakMultiplier(complianceStreak: number): number;
 export interface Route {
     id: string;
     fromZoneId: string;
@@ -357,7 +362,7 @@ export interface Contract {
     status: 'open' | 'active' | 'completed' | 'failed' | 'expired';
     createdAt: number;
 }
-export type GameEventType = 'tick' | 'shipment_created' | 'shipment_moved' | 'shipment_arrived' | 'shipment_intercepted' | 'trade_executed' | 'order_placed' | 'order_cancelled' | 'zone_supplied' | 'zone_state_changed' | 'zone_captured' | 'combat_resolved' | 'intel_gathered' | 'contract_posted' | 'contract_accepted' | 'contract_completed' | 'contract_failed' | 'faction_created' | 'faction_joined' | 'faction_left' | 'player_action' | 'stockpile_deposited' | 'tutorial_completed' | 'doctrine_updated' | 'webhook_triggered';
+export type GameEventType = 'tick' | 'shipment_created' | 'shipment_moved' | 'shipment_arrived' | 'shipment_intercepted' | 'trade_executed' | 'order_placed' | 'order_cancelled' | 'zone_supplied' | 'zone_state_changed' | 'zone_captured' | 'combat_resolved' | 'intel_gathered' | 'contract_posted' | 'contract_accepted' | 'contract_completed' | 'contract_failed' | 'faction_created' | 'faction_joined' | 'faction_left' | 'player_action' | 'stockpile_deposited' | 'tutorial_completed' | 'doctrine_updated' | 'webhook_triggered' | 'zone_income' | 'season_zone_scored';
 export interface GameEvent {
     id: string;
     type: GameEventType;

package/dist/core/types.js

@@ -36,13 +36,13 @@ export const RECIPES = {
 };
 /** What raw resource a Field produces based on its name */
 export function getFieldResource(fieldName) {
-    if (fieldName.includes('Ore'))
+    if (fieldName.includes('Mine') || fieldName.includes('Ore'))
         return 'ore';
-    if (fieldName.includes('Fuel'))
+    if (fieldName.includes('Refinery') || fieldName.includes('Fuel'))
         return 'fuel';
-    if (fieldName.includes('Grain'))
+    if (fieldName.includes('Farm') || fieldName.includes('Grain'))
         return 'grain';
-    if (fieldName.includes('Fiber'))
+    if (fieldName.includes('Grove') || fieldName.includes('Fiber'))
         return 'fiber';
     return null;
 }
@@ -121,6 +121,28 @@ export const BURN_RATES = {
     front: 10,
     stronghold: 20
 };
+/** Credits generated per tick for each owned zone type (split among faction members) */
+export const ZONE_INCOME = {
+    hub: 0, // Hubs are neutral
+    factory: 10,
+    field: 5,
+    junction: 0, // Junctions are transit only
+    front: 25,
+    stronghold: 50
+};
+/** Compliance streak multiplier for season-end zone scoring.
+ *  Zones held at full supply for longer streaks are worth more. */
+export function getStreakMultiplier(complianceStreak) {
+    if (complianceStreak >= 100)
+        return 3.0;
+    if (complianceStreak >= 50)
+        return 2.0;
+    if (complianceStreak >= 20)
+        return 1.5;
+    if (complianceStreak >= 5)
+        return 1.2;
+    return 1.0;
+}
 export const SHIPMENT_SPECS = {
     courier: { capacity: 10, speedModifier: 0.67, visibilityModifier: 0.5 },
     freight: { capacity: 50, speedModifier: 1.0, visibilityModifier: 1.0 },
@@ -288,8 +310,8 @@ export function applyIntelDecay(data, freshness) {
 export const TUTORIAL_CONTRACTS = [
     {
         step: 1,
-        title: 'First Haul',
-        description: 'Buy 20 ore at the Hub market and deliver it to an adjacent Factory. This teaches market buying, inventory management, and basic shipping.',
+        title: 'First Extraction',
+        description: 'Travel to a Field zone and extract 10 raw resources. This teaches navigation, zone types, and resource extraction.',
         type: 'tutorial',
         reward: { credits: 100, reputation: 5 }
     },

package/dist/db/turso-database.d.ts

@@ -19,8 +19,16 @@ export declare class TursoDatabase {
      */
     batch(statements: InStatement[]): Promise<void>;
     private initSchema;
+    private runMigrations;
     getCurrentTick(): Promise<number>;
     incrementTick(): Promise<number>;
+    /**
+     * Try to claim the next tick. Returns the new tick number if claimed,
+     * or null if another instance already processed it recently.
+     * Uses last_tick_at as a guard — skips if a tick was processed within
+     * the given minimum interval (in seconds).
+     */
+    tryClaimTick(minIntervalSeconds: number): Promise<number | null>;
     getSeasonInfo(): Promise<{
         seasonNumber: number;
         seasonWeek: number;
@@ -61,6 +69,7 @@ export declare class TursoDatabase {
     getUnit(id: string): Promise<Unit | null>;
     getPlayerUnits(playerId: string): Promise<Unit[]>;
     getUnitsForSaleAtZone(zoneId: string): Promise<Unit[]>;
+    getUnitsByAssignment(assignmentId: string, type?: string): Promise<Unit[]>;
     updateUnit(id: string, updates: Partial<Unit>): Promise<void>;
     deleteUnit(id: string): Promise<void>;
     private rowToUnit;
@@ -122,7 +131,7 @@ export declare class TursoDatabase {
         relations: Record<string, 'allied' | 'neutral' | 'war'>;
     }>): Promise<void>;
     getOrCreateSeasonScore(seasonNumber: number, entityId: string, entityType: 'player' | 'faction', entityName: string): Promise<SeasonScore>;
-    incrementSeasonScore(seasonNumber: number, entityId: string, entityType: 'player' | 'faction', entityName: string, field: 'supplyDelivered' | 'shipmentsCompleted' | 'contractsCompleted' | 'reputationGained' | 'combatVictories', amount: number): Promise<void>;
+    incrementSeasonScore(seasonNumber: number, entityId: string, entityType: 'player' | 'faction', entityName: string, field: 'zonesControlled' | 'supplyDelivered' | 'shipmentsCompleted' | 'contractsCompleted' | 'reputationGained' | 'combatVictories', amount: number): Promise<void>;
     updateSeasonZoneScores(seasonNumber: number): Promise<void>;
     getSeasonLeaderboard(seasonNumber: number, entityType?: 'player' | 'faction', limit?: number): Promise<SeasonScore[]>;
     getEntitySeasonScore(seasonNumber: number, entityId: string): Promise<SeasonScore | null>;

package/dist/db/turso-database.js

@@ -51,7 +51,8 @@ export class TursoDatabase {
         id INTEGER PRIMARY KEY CHECK (id = 1),
         current_tick INTEGER NOT NULL DEFAULT 0,
         season_number INTEGER NOT NULL DEFAULT 1,
-        season_week INTEGER NOT NULL DEFAULT 1
+        season_week INTEGER NOT NULL DEFAULT 1,
+        last_tick_at TEXT
       )`,
             // Zones
             `CREATE TABLE IF NOT EXISTS zones (
@@ -313,12 +314,37 @@ export class TursoDatabase {
             `CREATE INDEX IF NOT EXISTS idx_time_weighted_orders_status ON time_weighted_orders(status)`,
             `CREATE INDEX IF NOT EXISTS idx_audit_logs_faction ON audit_logs(faction_id)`,
             `CREATE INDEX IF NOT EXISTS idx_audit_logs_tick ON audit_logs(tick)`,
+            // Tier 1: Critical indexes for tick processing
+            `CREATE INDEX IF NOT EXISTS idx_shipments_status ON shipments(status)`,
+            `CREATE INDEX IF NOT EXISTS idx_units_player_id ON units(player_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_units_assignment_id ON units(assignment_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_routes_from_zone ON routes(from_zone_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_market_orders_zone ON market_orders(zone_id, resource, side, price)`,
+            `CREATE INDEX IF NOT EXISTS idx_contracts_status ON contracts(status, created_at)`,
+            `CREATE INDEX IF NOT EXISTS idx_shipments_player_id ON shipments(player_id)`,
+            // Tier 2: High priority indexes for queries
+            `CREATE INDEX IF NOT EXISTS idx_zones_owner_id ON zones(owner_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_intel_player_gathered ON intel(player_id, gathered_at)`,
+            `CREATE INDEX IF NOT EXISTS idx_intel_target ON intel(target_type, target_id, gathered_at)`,
+            `CREATE INDEX IF NOT EXISTS idx_contracts_poster ON contracts(poster_id, created_at)`,
+            `CREATE INDEX IF NOT EXISTS idx_contracts_accepted ON contracts(accepted_by, created_at)`,
             // Initialize world state
             `INSERT OR IGNORE INTO world (id, current_tick, season_number, season_week) VALUES (1, 0, 1, 1)`,
         ];
         for (const sql of statements) {
             await this.client.execute(sql);
         }
+        // Migrations for existing databases
+        await this.runMigrations();
+    }
+    async runMigrations() {
+        // Add last_tick_at column if missing (tick idempotency for zero-downtime deploys)
+        try {
+            await this.client.execute(`ALTER TABLE world ADD COLUMN last_tick_at TEXT`);
+        }
+        catch {
+            // Column already exists — ignore
+        }
     }
     // ============================================================================
     // WORLD STATE
@@ -328,7 +354,25 @@ export class TursoDatabase {
         return result.rows[0]?.current_tick || 0;
     }
     async incrementTick() {
-        await this.client.execute('UPDATE world SET current_tick = current_tick + 1 WHERE id = 1');
+        await this.client.execute(`UPDATE world SET current_tick = current_tick + 1, last_tick_at = datetime('now') WHERE id = 1`);
+        return this.getCurrentTick();
+    }
+    /**
+     * Try to claim the next tick. Returns the new tick number if claimed,
+     * or null if another instance already processed it recently.
+     * Uses last_tick_at as a guard — skips if a tick was processed within
+     * the given minimum interval (in seconds).
+     */
+    async tryClaimTick(minIntervalSeconds) {
+        // Atomically check and update: only increment if enough time has passed
+        const result = await this.client.execute({
+            sql: `UPDATE world SET current_tick = current_tick + 1, last_tick_at = datetime('now')
+            WHERE id = 1 AND (last_tick_at IS NULL OR unixepoch('now') - unixepoch(last_tick_at) >= ?)`,
+            args: [minIntervalSeconds]
+        });
+        if (result.rowsAffected === 0) {
+            return null; // Another instance already processed this tick
+        }
         return this.getCurrentTick();
     }
     async getSeasonInfo() {
@@ -453,17 +497,24 @@ export class TursoDatabase {
     }
     async getRoutesBetween(fromZoneId, toZoneId) {
         const result = await this.client.execute({
-            sql: 'SELECT * FROM routes WHERE from_zone_id = ? AND to_zone_id = ?',
-            args: [fromZoneId, toZoneId]
+            sql: 'SELECT * FROM routes WHERE (from_zone_id = ? AND to_zone_id = ?) OR (from_zone_id = ? AND to_zone_id = ?)',
+            args: [fromZoneId, toZoneId, toZoneId, fromZoneId]
         });
         return result.rows.map(row => this.rowToRoute(row));
     }
     async getRoutesFromZone(zoneId) {
         const result = await this.client.execute({
-            sql: 'SELECT * FROM routes WHERE from_zone_id = ?',
-            args: [zoneId]
+            sql: 'SELECT * FROM routes WHERE from_zone_id = ? OR to_zone_id = ?',
+            args: [zoneId, zoneId]
+        });
+        // Normalize: always make the queried zone the "from" side
+        return result.rows.map(row => {
+            const route = this.rowToRoute(row);
+            if (route.toZoneId === zoneId) {
+                return { ...route, fromZoneId: route.toZoneId, toZoneId: route.fromZoneId };
+            }
+            return route;
         });
-        return result.rows.map(row => this.rowToRoute(row));
     }
     async getAllRoutes() {
         const result = await this.client.execute('SELECT * FROM routes');
@@ -797,6 +848,14 @@ export class TursoDatabase {
         });
         return result.rows.map(row => this.rowToUnit(row));
     }
+    async getUnitsByAssignment(assignmentId, type) {
+        const sql = type
+            ? 'SELECT * FROM units WHERE assignment_id = ? AND type = ?'
+            : 'SELECT * FROM units WHERE assignment_id = ?';
+        const args = type ? [assignmentId, type] : [assignmentId];
+        const result = await this.client.execute({ sql, args });
+        return result.rows.map(row => this.rowToUnit(row));
+    }
     async updateUnit(id, updates) {
         const sets = [];
         const values = [];
@@ -1214,6 +1273,7 @@ export class TursoDatabase {
         // Ensure record exists
         await this.getOrCreateSeasonScore(seasonNumber, entityId, entityType, entityName);
         const fieldMap = {
+            zonesControlled: 'zones_controlled',
             supplyDelivered: 'supply_delivered',
             shipmentsCompleted: 'shipments_completed',
             contractsCompleted: 'contracts_completed',

package/dist/server/api.js

@@ -10,7 +10,7 @@ import { TursoDatabase } from '../db/turso-database.js';
 import { AsyncGameEngine } from '../core/async-engine.js';
 import { generateWorldData, mapRouteNamesToIds } from '../core/async-worldgen.js';
 import { TIER_LIMITS } from '../core/types.js';
-import { GameError, AuthError, ValidationError, NotFoundError, errorResponse, validateBody, ErrorCodes } from './errors.js';
+import { GameError, AuthError, ValidationError, NotFoundError, RateLimitError, errorResponse, validateBody, ErrorCodes } from './errors.js';
 import { JoinSchema, TravelSchema, ExtractSchema, ProduceSchema, ShipSchema, MarketOrderSchema, ScanSchema, SupplySchema, FactionCreateSchema, ContractCreateSchema } from './validation.js';
 import { rateLimitMiddleware, writeRateLimitMiddleware } from './rate-limit.js';
 let db;
@@ -60,6 +60,18 @@ const authMiddleware = async (c, next) => {
 const getPlayer = (c) => c.get('player');
 const getPlayerId = (c) => c.get('playerId');
 const getRequestId = (c) => c.get('requestId');
+// Convert engine result with code to proper GameError/RateLimitError
+function engineErrorToGameError(result, fallbackCode, fallbackMsg) {
+    const code = result.code;
+    const msg = result.error || fallbackMsg;
+    if (code === ErrorCodes.TICK_RATE_LIMITED || code === ErrorCodes.DAILY_LIMIT_REACHED) {
+        return new RateLimitError(code, msg);
+    }
+    if (code === ErrorCodes.PLAYER_NOT_FOUND) {
+        return new NotFoundError('Player');
+    }
+    return new GameError(code || fallbackCode, msg);
+}
 // ============================================================================
 // PUBLIC ENDPOINTS (no auth required)
 // ============================================================================
@@ -68,13 +80,36 @@ app.get('/', (c) => {
         name: 'BURNRATE',
         tagline: 'The front doesn\'t feed itself.',
         version: '1.0.0',
-        docs: '/docs'
+        docs: 'https://github.com/burnrate-cc/burnrate#readme',
+        endpoints: {
+            health: 'GET /health',
+            join: 'POST /join { "name": "YourName" }',
+            status: 'GET /me',
+            world: 'GET /world/zones',
+            routes: 'GET /routes',
+            travel: 'POST /travel { "to": "zone-id" }',
+            extract: 'POST /extract { "quantity": 10 }',
+            produce: 'POST /produce { "output": "metal", "quantity": 5 }',
+            ship: 'POST /ship { "type": "courier", "path": [...], "cargo": {...} }',
+            market: 'POST /market/order, GET /market/orders',
+            units: 'GET /units',
+            intel: 'POST /scan, GET /intel',
+            factions: 'GET /factions, POST /factions',
+            contracts: 'GET /contracts, POST /contracts',
+            tutorial: 'GET /tutorial, POST /tutorial/complete'
+        }
     });
 });
 app.get('/health', async (c) => {
     try {
         const tick = await db.getCurrentTick();
-        return c.json({ status: 'ok', tick });
+        const tickIntervalMs = parseInt(process.env.TICK_INTERVAL || '600000');
+        return c.json({
+            status: 'ok',
+            tick,
+            tickIntervalMs,
+            tickIntervalSeconds: Math.round(tickIntervalMs / 1000)
+        });
     }
     catch (e) {
         return c.json({ status: 'error', error: String(e) }, 500);
@@ -197,7 +232,7 @@ app.post('/travel', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     const { to } = await validateBody(c, TravelSchema);
     const result = await engine.travel(playerId, to);
     if (!result.success) {
-        throw new GameError(ErrorCodes.NO_ROUTE, result.error || 'Travel failed');
+        throw engineErrorToGameError(result, ErrorCodes.NO_ROUTE, 'Travel failed');
     }
     const zone = await db.getZone(to);
     return c.json({
@@ -211,7 +246,7 @@ app.post('/extract', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     const { quantity } = await validateBody(c, ExtractSchema);
     const result = await engine.extract(playerId, quantity);
     if (!result.success) {
-        throw new GameError(ErrorCodes.WRONG_ZONE_TYPE, result.error || 'Extraction failed');
+        throw engineErrorToGameError(result, ErrorCodes.WRONG_ZONE_TYPE, 'Extraction failed');
     }
     return c.json({ success: true, extracted: result.extracted });
 });
@@ -221,7 +256,7 @@ app.post('/produce', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     const { output, quantity } = await validateBody(c, ProduceSchema);
     const result = await engine.produce(playerId, output, quantity);
     if (!result.success) {
-        throw new GameError(ErrorCodes.INSUFFICIENT_RESOURCES, result.error || 'Production failed');
+        throw engineErrorToGameError(result, ErrorCodes.INSUFFICIENT_RESOURCES, 'Production failed');
     }
     return c.json({
         success: true,
@@ -235,7 +270,7 @@ app.post('/ship', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     const { type, path, cargo } = await validateBody(c, ShipSchema);
     const result = await engine.createShipmentWithPath(playerId, type, path, cargo);
     if (!result.success) {
-        throw new GameError(ErrorCodes.INSUFFICIENT_RESOURCES, result.error || 'Shipment failed');
+        throw engineErrorToGameError(result, ErrorCodes.INSUFFICIENT_RESOURCES, 'Shipment failed');
     }
     return c.json({ success: true, shipment: result.shipment });
 });
@@ -263,7 +298,7 @@ app.post('/market/order', authMiddleware, writeRateLimitMiddleware(), async (c)
     }
     const result = await engine.placeOrder(playerId, player.locationId, resource, side, price, quantity);
     if (!result.success) {
-        throw new GameError(ErrorCodes.INSUFFICIENT_RESOURCES, result.error || 'Order failed');
+        throw engineErrorToGameError(result, ErrorCodes.INSUFFICIENT_RESOURCES, 'Order failed');
     }
     return c.json({ success: true, order: result.order });
 });
@@ -301,7 +336,7 @@ app.post('/supply', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     }
     const result = await engine.depositSU(playerId, player.locationId, amount);
     if (!result.success) {
-        throw new GameError(ErrorCodes.INSUFFICIENT_RESOURCES, result.error || 'Supply failed');
+        throw engineErrorToGameError(result, ErrorCodes.INSUFFICIENT_RESOURCES, 'Supply failed');
     }
     return c.json({ success: true });
 });
@@ -335,7 +370,7 @@ app.post('/stockpile', authMiddleware, writeRateLimitMiddleware(), async (c) =>
         throw new NotFoundError('Player', playerId);
     const result = await engine.depositStockpile(playerId, player.locationId, resource, amount);
     if (!result.success) {
-        throw new GameError(ErrorCodes.INSUFFICIENT_RESOURCES, result.error || 'Stockpile deposit failed');
+        throw engineErrorToGameError(result, ErrorCodes.INSUFFICIENT_RESOURCES, 'Stockpile deposit failed');
     }
     return c.json({ success: true });
 });
@@ -455,7 +490,7 @@ app.post('/factions', authMiddleware, writeRateLimitMiddleware(), async (c) => {
     const { name, tag } = await validateBody(c, FactionCreateSchema);
     const result = await engine.createFaction(playerId, name, tag);
     if (!result.success) {
-        throw new GameError(ErrorCodes.ALREADY_IN_FACTION, result.error || 'Faction creation failed');
+        throw engineErrorToGameError(result, ErrorCodes.ALREADY_IN_FACTION, 'Faction creation failed');
     }
     return c.json({ success: true, faction: result.faction });
 });

package/dist/server/async-tick-server.js

@@ -20,10 +20,17 @@ async function main() {
     const engine = new AsyncGameEngine(db);
     const currentTick = await db.getCurrentTick();
     console.log(`[TICK SERVER] Starting at tick ${currentTick}`);
+    // Minimum interval guard: skip tick if one was processed less than half the interval ago.
+    // This prevents double-processing during rolling deploys when two instances overlap.
+    const minIntervalSeconds = Math.floor(TICK_INTERVAL / 1000 / 2);
     async function processTick() {
         const startTime = Date.now();
         try {
-            const result = await engine.processTick();
+            const result = await engine.tryProcessTick(minIntervalSeconds);
+            if (result === null) {
+                console.log(`[TICK SERVER] Skipped — another instance already processed this tick`);
+                return;
+            }
             const duration = Date.now() - startTime;
             console.log(`[TICK ${result.tick}] Processed in ${duration}ms, ${result.events.length} events`);
             // Log significant events

package/dist/server/validation.d.ts

@@ -60,20 +60,20 @@ export declare const ProduceSchema: z.ZodObject<{
     output: z.ZodString;
     quantity: z.ZodNumber;
 }, z.core.$strip>;
-export declare const CargoSchema: z.ZodRecord<z.ZodEnum<{
-    ore: "ore";
-    fuel: "fuel";
-    grain: "grain";
-    fiber: "fiber";
-    metal: "metal";
-    chemicals: "chemicals";
-    rations: "rations";
-    textiles: "textiles";
-    ammo: "ammo";
-    medkits: "medkits";
-    parts: "parts";
-    comms: "comms";
-}>, z.ZodNumber>;
+export declare const CargoSchema: z.ZodObject<{
+    ore: z.ZodDefault<z.ZodNumber>;
+    fuel: z.ZodDefault<z.ZodNumber>;
+    grain: z.ZodDefault<z.ZodNumber>;
+    fiber: z.ZodDefault<z.ZodNumber>;
+    metal: z.ZodDefault<z.ZodNumber>;
+    chemicals: z.ZodDefault<z.ZodNumber>;
+    rations: z.ZodDefault<z.ZodNumber>;
+    textiles: z.ZodDefault<z.ZodNumber>;
+    ammo: z.ZodDefault<z.ZodNumber>;
+    medkits: z.ZodDefault<z.ZodNumber>;
+    parts: z.ZodDefault<z.ZodNumber>;
+    comms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const ShipSchema: z.ZodObject<{
     type: z.ZodEnum<{
         courier: "courier";
@@ -81,20 +81,20 @@ export declare const ShipSchema: z.ZodObject<{
         convoy: "convoy";
     }>;
     path: z.ZodArray<z.ZodString>;
-    cargo: z.ZodRecord<z.ZodEnum<{
-        ore: "ore";
-        fuel: "fuel";
-        grain: "grain";
-        fiber: "fiber";
-        metal: "metal";
-        chemicals: "chemicals";
-        rations: "rations";
-        textiles: "textiles";
-        ammo: "ammo";
-        medkits: "medkits";
-        parts: "parts";
-        comms: "comms";
-    }>, z.ZodNumber>;
+    cargo: z.ZodObject<{
+        ore: z.ZodDefault<z.ZodNumber>;
+        fuel: z.ZodDefault<z.ZodNumber>;
+        grain: z.ZodDefault<z.ZodNumber>;
+        fiber: z.ZodDefault<z.ZodNumber>;
+        metal: z.ZodDefault<z.ZodNumber>;
+        chemicals: z.ZodDefault<z.ZodNumber>;
+        rations: z.ZodDefault<z.ZodNumber>;
+        textiles: z.ZodDefault<z.ZodNumber>;
+        ammo: z.ZodDefault<z.ZodNumber>;
+        medkits: z.ZodDefault<z.ZodNumber>;
+        parts: z.ZodDefault<z.ZodNumber>;
+        comms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const MarketOrderSchema: z.ZodObject<{
     resource: z.ZodEnum<{

package/dist/server/validation.js

@@ -41,7 +41,20 @@ export const ProduceSchema = z.object({
     output: z.string().min(1, 'Output type required'),
     quantity: z.number().int().min(1, 'Quantity must be at least 1').max(100, 'Quantity cannot exceed 100')
 });
-export const CargoSchema = z.record(ResourceSchema, z.number().int().min(0).max(10000)).refine((cargo) => Object.values(cargo).some(v => v > 0), 'Cargo must contain at least one resource');
+export const CargoSchema = z.object({
+    ore: z.number().int().min(0).max(10000).default(0),
+    fuel: z.number().int().min(0).max(10000).default(0),
+    grain: z.number().int().min(0).max(10000).default(0),
+    fiber: z.number().int().min(0).max(10000).default(0),
+    metal: z.number().int().min(0).max(10000).default(0),
+    chemicals: z.number().int().min(0).max(10000).default(0),
+    rations: z.number().int().min(0).max(10000).default(0),
+    textiles: z.number().int().min(0).max(10000).default(0),
+    ammo: z.number().int().min(0).max(10000).default(0),
+    medkits: z.number().int().min(0).max(10000).default(0),
+    parts: z.number().int().min(0).max(10000).default(0),
+    comms: z.number().int().min(0).max(10000).default(0),
+}).refine((cargo) => Object.values(cargo).some(v => v > 0), 'Cargo must contain at least one resource');
 export const ShipSchema = z.object({
     type: ShipmentTypeSchema,
     path: z.array(z.string()).min(2, 'Path must have at least origin and destination'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burnrate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A logistics war MMO for Claude Code. The front doesn't feed itself.",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -49,7 +49,6 @@
     "@hono/node-server": "^1.19.9",
     "@libsql/client": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "better-sqlite3": "^12.6.2",
     "commander": "^14.0.2",
     "hono": "^4.11.7",
     "tsx": "^4.21.0",
@@ -57,6 +56,12 @@
     "uuid": "^13.0.0",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.6.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.0.10",