# Nexus Shops

Each Shop is one cohesive Journal-backed service entity. Its Journal flag owns identity, location, current inventory, commerce settings, treasury, provider snapshots, and an embedded `restockProfile`. Potential stock is not a separate world entity.

Runtime code outside Nexus uses `/modules/augur-nexus/scripts/api/shops.js`. `openShop(...)` opens the dossier, while `openShopTrade(...)` enters the player-facing marketplace.

Nexus owns the unified Shop Editor, Shop persistence and lifecycle, trading and settlement, generic catalogs and filters, and product-provider/system-adapter contracts. The editor has three views over one in-memory Shop draft:

- Current Stock: the merchandise players can buy now, including curated drops and explicit generation controls.
- Restock Pool: exact product references plus the full dynamic catalog, search, price, type, source, and tri-state facet filters.
- Store Settings: identity, template application, generation ranges, treasury, pricing, and commerce switches.

Restock entries contain references and selection metadata only: `providerId`, `productId`, enabled state, weight, optional quantity range, optional price override, and non-authoritative display/source hints. Missing references remain visible, are skipped safely during generation, and can be removed explicitly.

Changing or importing a Restock Pool never silently overwrites Current Stock. `Refresh Generated` preserves curated and pinned merchandise; `Replace Everything` is separately confirmed. The whole draft is committed to the Shop Journal only when the GM saves the editor.

Feature modules own shop archetypes, catalog semantics, product resolution, system-specific item eligibility, inventory behavior, currency translation, and atomic actor-side trade sessions. Augur: Fantasy currently supplies the Armorsmith and Weaponsmith templates; the active D&D 5e or Pathfinder 2e provider resolves those semantic merchandise kinds to available world sources.

Inventory rows contain `id`, `providerId`, `productId`, quantity, optional price override, pinned state, and generated state. Provider-owned snapshots for items bought from characters live under opaque `providerData`; Nexus does not interpret system-specific Item data.

A trade has one inventory Actor and one wallet Actor. Purchases and sales are validated together and settled as one net currency movement. The authoritative GM client executes the request. The shared transaction service delegates all system-owned Actor and Item writes to the active system adapter.