polaris-task-force/src/lib/AGENTS.md

AGENTS.md — Shared Business Logic

Parent: ../../AGENTS.md — Payload config, server actions pattern, env vars.

Overview

23 files across 8 domain subdirectories. Contains pure business logic and Payload-dependent service modules. Server actions in route directories delegate here; these modules hold the actual domain rules.

Structure

lib/
  utils.ts              # cn() class merger (Tailwind)
  storageRules.ts       # Storage validation (prohibited → whitelist → per-item cap)
  shipping.ts           # Fuel cost, transit time, vehicle effective speed
  distance.ts           # Haversine distance calculation
  logistics.ts          # Shared logistics helpers
  versionInfo.ts        # Build version display

  attendance/           # Mission attendance service (single write path)
  banking/              # Transaction engine, account creation, formatting
  locker/               # Grid logic, placement validation, loadouts
  market/               # Buy/sell, NPC negotiation, dialogue, vendor resolution
  notifications/        # User notification helper + muteable types
  realtime/             # In-process SSE bus (single-instance only)
  tickets/              # Ticket vocabulary, Lexical helpers, staff resolution

Dependency graph

Server actions ──┬── storageRules.ts
                 ├── lib/banking/index.ts ──┬── format.ts
                 │                          └── ui.ts
                 ├── lib/market/index.ts ──┬── negotiations.ts
                 │                         ├── npcs.ts
                 │                         ├── npcDialogue.ts (pure, client-safe)
                 │                         └── chatBubbles.ts (pure, client-safe)
                 ├── lib/locker/index.ts ── search.ts
                 ├── lib/attendance/index.ts
                 ├── lib/notifications/index.ts
                 └── lib/tickets/

game-tick script ── shipping.ts, distance.ts, storageRules.ts
market-tick script ── lib/market/index.ts (autoPrice, autoQuantity, npc vendor logic)

Pure vs Payload-dependent

• Pure modules (no Payload import, safe for client + server): npcDialogue.ts, chatBubbles.ts, ticketMeta.ts, distance.ts, storageRules.ts (logic only)
• Payload-dependent (import @payload-config, server-only): everything else

Key modules

storageRules.ts

Enforcement order: prohibited → whitelist → per-item cap. Functions: checkStorageDeposit, isResourceProhibited, isResourceWhitelisted, getResourceStorageCap, storageViolationMessage. Used in structure actions, shipment creation, and arrival processing.

banking/index.ts

applyTransaction() — single source of truth for balance math. Validates accounts, creates transaction + ledger entries, updates balances. ensurePersonalAccount() — dedup find-or-create. getMainCurrencyId() — resolves Game Rules main currency.

market/index.ts

buyListing() — validates, debits buyer, credits locker, marks sold. Supports partial buys via quantity parameter. creditLockerQuantity() — merges stackables or fills empty grid spots; throws if no space.

market/negotiations.ts

NPC vendor pricing engine: stance starts at asking price, only moves down. Offers ≥ stance accepted; within 2% with 85% chance; well-below draw concession (30% of gap). Patience meter increments per round, closes at cap.

realtime/bus.ts

Module-level subscriber Set. SSE endpoint GET /api/realtime subscribes; game tick POST /api/game-tick/notify broadcasts. Single-instance only — will not work across multiple server processes.

Where to look

Task	Path
Add storage rule logic	storageRules.ts (pure functions)
Modify transaction flow	lib/banking/index.ts — applyTransaction()
Change NPC pricing	lib/market/negotiations.ts — NPC_ACCEPT constants
Add notification type	lib/notifications/notificationTypes.ts
Add pure client+server logic	Verify no Payload import; place in appropriate domain dir

Anti-patterns

• NEVER import @payload-config in files under market/npcDialogue.ts or market/chatBubbles.ts — they must stay client-safe
• NEVER duplicate business logic in server actions — always delegate to lib/{domain}/
• NEVER use module-level state in realtime/bus.ts for cross-instance scenarios — use external pub/sub (Redis) instead
• NEVER mutate storageRules.ts enforcement order without updating all 3 call sites (structure actions, shipment creation, arrival processing)