otivm/docs/architecture/terminology.md

# Terminology and Naming Convention
### TheRON — OTIVM / CIVICVS / TESSERA Stack
### Status: Living document — terms are added as they are established, never removed
### Date: 2026-04-28

---

## 0. Purpose and standard

This document is the referee for all naming decisions across code, database
schema, API endpoints, documentation, and UI text.

A term is admitted to this vocabulary only if it passes three tests:

1. **Period-authentic.** The term belongs to the period and culture it
   describes. It is not borrowed forward or backward in time. A term that
   applies equally to a Mesolithic forager and a Roman merchant and a
   modern logistics manager has lost its precision and must not be used
   as a canonical token.

2. **Semantically dense.** The term carries more information than its
   nearest equivalent in the other layer. If the English and Latin mean
   the same thing with equal precision, English is used in code. If the
   Latin carries meaning the English cannot carry without a sentence of
   explanation, Latin is used as the canonical token.

3. **Scope-bounded.** The term cannot be misapplied across periods without
   the misapplication being immediately visible. GLADIVS cannot be used to
   describe a Viking sword without the error being obvious. That visibility
   is a feature, not a limitation.

**The exemplar:** CIVICVS. One word. Irreducible. Carries civic duty,
social obligation, public life, and the specifically Roman relationship
between the individual and the res publica — all at once. No English
word or phrase carries the same cargo. It is scoped to Rome: it cannot
be applied to the Mesolithic without obvious anachronism, and its modern
descendants ("civic") have shed most of its meaning. It passes all three
tests. It is the model for every term that follows.

---

## 1. Three layers

### Layer 1 — Universal substrate terms
Concepts that exist across all periods, cultures, and contexts.
These are the code tokens used in TESSERA, in database schemas, in API
endpoints, and in any code that must be period-neutral.

Universal terms are always lowercase in code. They describe the physics
and logic of the simulation, not the human experience of it.

### Layer 2 — Period-specific human terms
The vocabulary of a specific culture in a specific period. These are the
labels the participant or player encounters. They are never used as
database column names or API parameters — they live in UI text, journal
entries, documentation prose, and research briefs.

Period-specific terms are written in the conventions of their period.
Latin terms for Rome: CAPITALS for canonical introduction, mixed case
in prose thereafter. Reconstructed Mesolithic terms: follow the
conventions of the relevant scholarship.

### Layer 3 — Code tokens
The actual identifiers in source code, database columns, API parameters,
and file names. Always lowercase, snake_case for multi-word tokens.
Never use a period-specific term as a code token unless it has been
explicitly admitted to Layer 3 in this document.

---

## 2. Universal substrate terms (Layer 1)

These terms apply across all periods. They are the atoms of the simulation.

| Universal term | Definition | Code token | Notes |
|---|---|---|---|
| **actor** | Any individual or collective capable of initiating action in the simulation. A person, a clan, a guild, a vessel. | `actor` | Not "player", not "character", not "agent". An actor acts. |
| **location** | A point or bounded area in TESSERA space, identified by H3 cell ID at a specified resolution. | `location` | Never a coordinate pair alone. Always H3. |
| **movement** | A displacement of an actor or cargo from one location to another, with a start time, end time, mode, and cost. | `movement` | The universal abstraction of leg, route, voyage, journey, expedition. |
| **resource** | Any quantifiable thing that can be held, transferred, consumed, or produced. Physical goods, money, time, social capital. | `resource` | Deliberately broad. Specialised in period layer. |
| **exchange** | A transfer of resource between two or more actors, with terms, at a location and time. | `exchange` | Not "trade", not "sale", not "barter". Exchange is universal. |
| **venture** | A bounded sequence of movements and exchanges with a defined purpose, initiated by an actor. Has a start, an end, a cost, and an outcome. | `venture` | The universal abstraction of NEGOTIVM, foraging expedition, hunting party. |
| **leg** | A single movement within a venture. One mode, one route, one origin, one destination. | `leg` | Indivisible unit of movement within a venture. |
| **interval** | A bounded period of time during which an actor is not in movement. Rest, preparation, waiting, otium. | `interval` | Not "downtime". An interval has parameters — what the actor did, what it cost, what it produced. |
| **cost** | Any resource consumed by a movement, exchange, or interval. Time is always a cost. | `cost` | Time is the master cost. All others are denominated alongside it. |
| **outcome** | The net change in resources held by an actor at the conclusion of a venture. | `outcome` | Not "profit". Outcome can be negative, zero, or positive across multiple resource types simultaneously. |
| **parameter** | A quantifiable attribute of any simulation entity — actor, movement, exchange, resource, location. The atomic unit of the behavioral record. | `parameter` | Parameters are recorded. They are never inferred after the fact. |
| **event** | A timestamped record of a state change in the simulation. The atomic unit of history. | `event` | Time is the master dimension. Every event has a timestamp. No event is undated. |
| **epoch** | A named period of time with defined physical world parameters — sea level, climate, terrain. | `epoch` | Defined in `paleo_epochs` table. Not a game concept — a physical reality concept. |

---

## 3. Roman period terms (Layer 2) — OTIVM

Terms authentic to Rome, approximately 1st century BCE to 1st century CE,
western Mediterranean context. These are the human-facing vocabulary of OTIVM.

The test for each term: would a literate Roman of the period use this word
in this sense, in this context, without anachronism?

| Latin term | Literal meaning | Simulation meaning | English gloss | Notes |
|---|---|---|---|---|
| **MERCATOR** | merchant, trader | The actor in OTIVM. A free person conducting commercial ventures for personal profit. | merchant | Not "trader". MERCATOR implies a specific social and legal status in Rome. A NEGOTIATOR was higher status, a INSTITOR lower. MERCATOR is the correct term for our actor. |
| **NEGOTIVM** | business, affair, occupation | A venture: a bounded commercial undertaking with a defined route, cargo, and expected outcome. The opposite of OTIUM. | venture | The universal term `venture` maps to NEGOTIVM in the Roman layer. |
| **ITER** | journey, march, road | A single leg of a NEGOTIVM. One mode, one route, origin to destination. | leg | The universal term `leg` maps to ITER in the Roman layer. |
| **OTIUM** | leisure, rest, withdrawal | An interval of deliberate non-commercial activity. Has social, civic, and restorative functions. Produces AVCTORITAS when conducted correctly. | otium | Not "rest" or "downtime". OTIUM is a moral and social category. It has costs and outcomes like any other interval. |
| **AVCTORITAS** | authority, influence, reputation | A resource accumulated through correct conduct — commercial reliability, civic participation, social relationships. Opens opportunities unavailable to those who lack it. | auctoritas | Not "reputation points". AVCTORITAS was real social capital in Rome with legal and commercial consequences. |
| **CODEX ACCEPTI ET EXPENSI** | account book of receipts and expenditures | The merchant's ledger. The record of all resources received and spent. | ledger | The Ledger tab in OTIVM. The name is correct and intentional. |
| **RATIONES** | accounts, reckoning | The disaggregated line items of a NEGOTIVM — what was spent, on what, at what leg, with what outcome. | accounts | The third tab in OTIVM. The name is correct and intentional. |
| **FACTOR** | agent, doer | A trusted agent resident at a destination who acts on the MERCATOR's behalf. Negotiates prices, arranges storage, manages local relationships. | factor | An NPC in future releases. Not a "merchant's assistant" — a FACTOR had legal standing and could bind the MERCATOR contractually. |
| **AMPHORA** | two-handled vessel | The standard Roman cargo unit for liquids. Type-specific: Dressel 1 (wine), Dressel 20 (olive oil), Dressel 7-11 (garum). Not interchangeable. | amphora | The cargo unit. When the code records cargo, it records amphora type, not generic "units". |
| **MODIVS** | measure | Standard dry measure for grain and other bulk goods. ~8.62 litres. | modius | The cargo unit for grain. |
| **SVCCINUM** | amber | Fossil resin from the Baltic coast, traded south through intermediary networks over centuries. In OTIVM, the first good that connects Roman commerce to pre-Roman worlds. | amber | Not merely "amber". SVCCINUM is the Roman term for a specific good with a specific, traceable provenance chain reaching back to Maglemoisian forests. |
| **TVS** | frankincense, incense | Aromatic resin from southern Arabia. Reached Rome via intermediary networks through Egypt and the Levant. In OTIVM, the good that extends the supply chain furthest from Rome. | frankincense | |
| **VECTVRA** | carriage, transport charge | The freight cost for a specific leg of a NEGOTIVM. Paid to the carrier, not the MERCATOR. | freight charge | A cost parameter recorded per leg. |
| **PORTORIUM** | customs duty, toll | The tax levied on goods crossing provincial or customs boundaries. Collected by PVBLICANI (tax farmers). Rate and collection point are leg-specific. | customs duty | A cost parameter recorded per crossing point. |
| **HORREUM** | warehouse, granary | Storage facility at a port or market. The MERCATOR pays for storage by the day or season. | warehouse | A location type in the simulation. |
| **NAVIS ONERARIA** | cargo ship | A broad class of sailing vessels designed for cargo. Subtypes: CORBITA (round ship, slow, large capacity), ACTUARIA (oared, faster, smaller). | cargo vessel | Not "ship" or "galley". The vessel type determines capacity, crew size, speed, and weather vulnerability. |
| **NAUFRAGIVM** | shipwreck | Loss of vessel and cargo at sea. The catastrophic failure mode for maritime legs. | shipwreck | A failure event type. Probability derived from archaeological wreck distribution data. |
| **MARE CLAVSVM** | closed sea | The period approximately November to March when Mediterranean maritime commerce was suspended due to weather risk. A hard seasonal constraint on maritime legs. | closed sea season | An epoch-level parameter that disables or heavily penalises maritime legs during its duration. |
| **COLLEGIUM** | association, guild | A voluntary association of merchants, craftsmen, or others with shared commercial interests. Membership provides social capital, dispute resolution, and mutual aid. | guild | A social structure the MERCATOR may belong to. Affects AVCTORITAS and available NEGOTIA. |
| **CLIENTELA** | client relationship | The network of mutual obligation between a patron (PATRONVS) and clients (CLIENTES). A MERCATOR both has clients and is a client. Obligations compete with NEGOTIVM for time. | clientela | A social resource that generates and consumes OTIUM. |

---

## 4. Mesolithic period terms (Layer 2) — CIVICVS

Terms authentic to the Mesolithic, approximately 10000–4000 BCE, northern
European context (Maglemoisian, Ertebølle, Sauveterrian, Azilian cultures).

This section is a stub. Terms will be added as the CIVICVS corpus develops
and as scholarship is incorporated. The same three-test standard applies.
No term is admitted without a traceable source in the archaeological or
linguistic record.

| Term | Culture | Simulation meaning | Notes |
|---|---|---|---|
| *pending* | — | — | Terms to be established through corpus development and research briefs parallel to the Roman research brief. |

---

## 5. Code tokens (Layer 3)

The identifiers used in source code, database columns, API parameters,
and file names. All lowercase, snake_case. Period-neutral.

A code token maps to exactly one universal term (Layer 1). Its
period-specific expression (Layer 2) is documented here for reference
but never used in code.

| Code token | Universal term | Roman expression | Mesolithic expression | Used in |
|---|---|---|---|---|
| `actor` | actor | MERCATOR, FACTOR | Constructor | database, API |
| `venture` | venture | NEGOTIVM | foraging expedition | database, API, events |
| `leg` | leg | ITER | movement corridor | database, API |
| `interval` | interval | OTIUM | rest period | database, API, events |
| `exchange` | exchange | — | — | database, API |
| `resource` | resource | denarii, amphora, avctoritas | calories, flint, social bond | database |
| `location` | location | OSTIA, CAPVA, etc. | hex H3 ID | database, API |
| `movement` | movement | — | — | database |
| `cost` | cost | VECTVRA, PORTORIUM | — | database |
| `outcome` | outcome | profit/loss | net resource change | database |
| `parameter` | parameter | — | — | database |
| `event` | event | — | — | database, save file |
| `epoch` | epoch | roman_14bce | mesolithic_8000bce | database, API |
| `event_type` values: | | | | |
| `venture_start` | — | NEGOTIVM begins | expedition departs | events |
| `venture_complete` | — | NEGOTIVM returns | expedition returns | events |
| `leg_start` | — | ITER begins | — | events |
| `leg_complete` | — | ITER ends | — | events |
| `interval_start` | — | OTIUM begins | rest begins | events |
| `interval_complete` | — | OTIUM ends | rest ends | events |
| `exchange_complete` | — | sale/purchase | — | events |
| `session_abandoned` | — | MERCATOR withdraws | Constructor withdraws | events |
| `chapter_advance` | — | chapter milestone | — | events |
| `journal_unlock` | — | journal entry fires | — | events |

---

## 6. Terms explicitly rejected

These terms were considered and rejected. They must not appear in code,
schema, or canonical documentation. The reason for rejection is recorded
so the decision is not revisited without new argument.

| Rejected term | Reason for rejection |
|---|---|
| `trade` | Too broad. Applies equally to barter, gift exchange, market sale, and tribute. Erases the distinctions the simulation depends on. Use `exchange` or `venture` as appropriate. |
| `route` | Implies a fixed, named path. A NEGOTIVM is not a fixed route — it is a sequence of legs chosen by the MERCATOR. The path is a parameter, not the unit. Use `venture` and `leg`. |
| `player` | Implies a game. The MERCATOR is an actor in a simulation. The participant is a participant. Use `actor` in code. |
| `NPC` | Game terminology. Use `actor` with a `controlled_by` parameter indicating AI, simulation, or participant. |
| `points` | Any resource described as "points" has been stripped of its meaning. AVCTORITAS is not "reputation points". Use the correct resource name. |
| `dispatch` | Used in OTIVM-I and OTIVM-II as scaffolding. To be replaced by `venture_start` in OTIVM-III. The Dispatch Galley button will be renamed. |
| `galley` | Inaccurate. The vessel type is NAVIS ONERARIA or a subtype. The word "galley" implies an oared warship. The MERCATOR does not operate warships. |
| `reset` | A player resets a game. A MERCATOR abandons a NEGOTIVM or withdraws from a session. Use `session_abandoned`. |

---

## 7. Naming convention rules

**Databases and files:**
- Per-player database: `data/players/{token}.sqlite3`
- Master store: named by container role, not by content
- Never use a period-specific term in a file name

**API endpoints:**
- Always versioned: `/api/v1/...`
- Use code tokens (Layer 3): `/api/v1/venture`, not `/api/v1/negotium`
- Period-specific terms belong in response body documentation, not in endpoint paths

**Database columns:**
- Use code tokens (Layer 3) exclusively
- Timestamp column is always `recorded_at` — not `created_at`, not `timestamp`
- Every table that records simulation events must have `recorded_at` as its primary time dimension

**UI text:**
- Use period-specific terms (Layer 2) in all player/participant-facing text
- The Ledger tab: CODEX ACCEPTI ET EXPENSI in header, "Ledger" in navigation
- The Accounts tab: RATIONES in header, "Accounts" in navigation
- Never expose code tokens (Layer 3) to participants

**Comments in code:**
- When a code token maps to a period-specific term, note it in a comment on first use
- Example: `// venture = NEGOTIVM in Roman layer, foraging expedition in Mesolithic layer`

---

*Terminology and Naming Convention — living document, 2026-04-28*
*A term admitted is never removed. A rejected term is never reinstated without new argument.*
*TheRON — single contributor. AI assistants implement, document, flag — do not direct.*