# 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)