# Economy

This document defines the intended economic model for the simulation.

The economy should be market driven.

That means production, transport, shortages, and prices should emerge from station behavior, commander intent, and resource availability rather than from fixed scripted chains alone.

See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the intended entity vocabulary behind market orders, construction sites, and policy sets.

## Design Goals

The economy should support:

- real shortages and surpluses
- trade incentives
- meaningful logistics
- station specialization
- commander-driven buy and sell behavior
- faction growth constrained by market conditions
- workforce support through life-support goods

See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the shared item vocabulary behind these flows.

## Core Principle

Stations participate in the economy by publishing market intent.

The primary mechanism is:

- buy orders
- sell orders

These orders should be created and maintained by station commanders.

## Market Actors

The intended market actors are:

- stations
- factions
- ships acting on behalf of commanders

Stations are the main visible market nodes.

Factions shape policy and strategy.

Ships execute transport, procurement, and delivery.

For now, market exchange should be station-centric:

- ship-to-station trading is supported
- ship-to-ship trading is out of scope for now

## Market Units

The economy should be expressed through explicit market units rather than vague station desires.

Recommended market units:

- `buy order`
- `sell order`
- `reservation`
- `fulfilled trade`
- `cancelled trade`

This gives the economy observable state and event history.

See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the market and trade event families that should represent this history.

## Buy Orders

A buy order expresses that a station wants to acquire a resource.

A buy order should include, conceptually:

- item
- desired amount
- price or valuation
- minimum delivery size if needed
- urgency or priority
- optional sourcing restrictions

Buy orders let a station express:

- production input demand
- construction material shortages
- military resupply needs

Construction storage for a planned station should be allowed to publish buy orders before the finished station is fully operational.

Recommended additional fields later:

- issuing station
- expiry or review time
- maximum acceptable route cost
- whether partial fulfillment is acceptable

## Sell Orders

A sell order expresses that a station is willing to release a resource.

A sell order should include, conceptually:

- item
- offered amount
- price or valuation
- reserve threshold
- optional buyer restrictions

Sell orders let a station express:

- exportable surplus
- intentional specialization
- market-facing production

Recommended additional fields later:

- issuing station
- reserve floor
- preferred buyer class if needed
- priority relative to internal faction demand

## Station Commander Market Role

The station commander is responsible for market participation.

The station commander should:

- observe stock levels
- observe production demand
- observe dock throughput and logistics health
- set or adjust buy orders
- set or adjust sell orders
- choose production priorities
- request support when shortages threaten station function

Without a station commander, a station should not act like a healthy market participant.

However, there is an important exception during founding or emergency intervention:

- a higher actor may force transfers toward the station or construction site even without ordinary market behavior

Recommended review loop:

1. inspect current inventory
2. inspect production queues or goals
3. inspect incoming and outgoing reservations
4. inspect defense, and construction reserves
5. update buy orders
6. update sell orders
7. request logistics or strategic help if necessary

## Prices And Valuation

The design does not require a single global static price list.

It is better to think in terms of valuation driven by:

- local scarcity
- strategic need
- production usefulness
- reserve thresholds
- faction doctrine

This allows stations to value the same item differently at different times.

Recommended interpretation:

- prices are not only “market prices”
- they are commander valuations
- commander valuations can still produce a market when many actors interact

There should not be a mandatory fixed global baseline price underneath this system.

Traders should optimize for profit, not just headline sale price.

## Resource Flow

The intended economy should eventually support flows such as:

1. extract raw resources
2. move them to useful stations
3. refine or process them
4. consume them for production or expansion
5. produce intermediate and advanced goods
6. sell surpluses or acquire shortages through the market

The important design point is that each stage should create economic pressure for the next, not just scripted state transitions.

See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the conversion-side rules behind these flows.

## Logistics

Logistics should emerge from market demand, not only from hardcoded behavior loops.

Examples:

- a hauler sees a profitable sell-to-buy opportunity
- a faction commander subsidizes strategic resource movement

This is a better long-term basis than one-off scripted “mine and deliver to this exact station” logic.

Traders should generally prefer the best reachable buy opportunity within their allowed operational range, subject to:

- travel time
- risk
- behavioral restrictions
- territorial or regional limits

Recommended logistics sources of work:

- open buy orders
- profitable route opportunities
- commander-assigned emergency deliveries
- faction-priority strategic transfers

Not every cargo move needs to be pure free-market behavior, but the market should be the baseline.

Behavior-restricted work should still exist.

Example:

- `mine-for-station` is a constrained behavior, not a different economic ontology

The ship still sells into the market structure, but with restrictions on where and for whom it will trade.

## Reservations And Commitments

The economy will work better if stations can reserve expected inventory changes.

Examples:

- outbound metals are reserved for a construction project
- a hauler claims part of a sell order before pickup

Without reservations, the same goods are too easy to double-allocate.

Current design choice:

- first one to deliver wins

This means market competition can remain simple at first, even if fuller reservation logic is introduced later for other workflows.

## Market Visibility

Market intent should generally be open knowledge, subject to access rules.

The baseline assumption is that buy and sell orders are visible to authorized observers and usable as input for commander planning.

Worker support goods are economically important because workforce depends on them. See [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).

Those support goods are defined as item roles in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).

## Market And Space

The market should respect the spatial model in [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md).

Implications:

- stations live in localspaces owned by anchors
- docking and transfer happen in localspace
- in-system logistics move through warp between anchors
- inter-system trade moves through stargates or FTL

Distance and travel friction should matter economically.

This means:

- a nearby station may be economically better than a richer but distant one
- warp and dock congestion affect profitability
- inter-system trade should be slower and riskier than local trade

Operational range restrictions should come from behavior and policy, not only from physics.

Examples:

- stay in-system
- stay in-region
- faction-only trade
- station-serving behavior

See [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md) for the policy layer behind these restrictions.

## Minimal Functional Rules

The following rules should remain true unless deliberately broken:

- stations express demand through buy orders
- stations express surplus through sell orders
- station commanders manage those orders
- logistics ships respond to economic incentives, not only fixed scripts
- shortages should propagate into visible gameplay effects
- market state should influence production, travel, and expansion

## Minimum Viable Economic Loop

The smallest useful version of this system would be:

1. stations publish buy and sell orders
2. station commanders update those orders from inventory thresholds
3. logistics ships choose a station demand to satisfy
4. cargo transfer creates reservations
5. delivery fulfills reservations and updates inventory
6. shortages and surpluses visibly change future orders

## Station Construction Demand

A planned station should generate economic demand before full completion.

The recommended mechanism is:

1. claim becomes active
2. construction storage appears
3. station design determines required build materials
4. construction storage publishes buy orders for those materials
5. deliveries accumulate
6. constructor ships consume them into built progress

This lets station construction participate directly in the same economic model as ordinary station operation.

## Relationship To Other Documents

- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
  - defines who owns market decisions

- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
  - defines station roles and market participation

- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
  - defines logistics and industrial ship roles

- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
  - defines population demand and workforce consequences

- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
  - defines the item categories moving through the market

- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
  - defines how goods are transformed into other goods over time

- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
  - defines who may participate in trade and under what restrictions
