From 890cc8e3036be8a22ce4c84c6689c4c3f9514e42 Mon Sep 17 00:00:00 2001 From: TheRON Date: Tue, 28 Apr 2026 11:48:24 -0400 Subject: [PATCH] initial upload --- docs/parameter-registry.md | 781 +++++++++++++++++++++++++++++++++++++ 1 file changed, 781 insertions(+) create mode 100644 docs/parameter-registry.md diff --git a/docs/parameter-registry.md b/docs/parameter-registry.md new file mode 100644 index 0000000..b7d99de --- /dev/null +++ b/docs/parameter-registry.md @@ -0,0 +1,781 @@ +# Parameter Registry +### TheRON — OTIVM / CIVICVS / TESSERA Stack +### Status: Living document — parameters added as established, never removed +### Date: 2026-04-28 + +--- + +## 0. Purpose + +This document is the authoritative registry of all simulation parameters across +all layers. It sits between the prose documents (scenarios, actor backgrounds, +city substrates) and the SQL schema. It prevents the schema from prematurely +flattening complex concepts into simple integers. + +Every parameter here declares four structural fields before any values are given: + +``` +token: canonical code identifier (snake_case, period-neutral) +scope: actor | city | scenario | relation | derived +layer: roman | mesolithic | universal +maturity: canonical | provisional | research_needed +``` + +**scope** — where the parameter lives in the architecture: +- `actor` — per-player, drifts with decisions, lives in per-player SQLite +- `city` — shared across players, changes with events, lives in city substrate +- `scenario` — exists within a scenario's active window only +- `relation` — cross-layer dependency or derived interaction +- `derived` — computed from other parameters, not stored independently + +**layer** — which cultural period the parameter belongs to: +- `roman` — Roman-specific, approximately 1st c. BCE to 1st c. CE +- `mesolithic` — Mesolithic-specific, approximately 10000–4000 BCE +- `universal` — exists across all periods with different expressions + +**maturity** — confidence in the parameter's definition: +- `canonical` — fully defined, passes all three admission tests, schema-ready +- `provisional` — defined but awaiting research confirmation or design decision +- `research_needed` — identified as necessary, definition incomplete + +**On uncertainty:** parameters marked with `observable: partial` or +`observable: hidden` must not be stored as clean point values. They carry +epistemic status — the actor does not know their precise value, only signals. +The schema must preserve this. A hidden parameter has a true value (server-side) +and a perceived value (actor-side). These are different records. + +--- + +## 1. Actor Parameters + +Parameters that live in the per-player database and drift over time as the +actor makes decisions. These are the twelve canonical parameters from +CHARACTER-FRAMEWORK plus extensions identified through scenario development. + +--- + +### AVCTORITAS +``` +token: auctoritas +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Social capital with legal and commercial consequences. Not a +reputation score — a social reality that other actors respond to. Accumulated +through correct conduct, reliable commercial behaviour, appropriate OTIUM, +and maintained CLIENTELA. Lost through failure, disgrace, or unmet obligations. + +**Type:** ordinal scale, not a precise number +**Unit:** none — expressed as a band (low / medium / high / distinguished) +**Observable:** partial — the actor infers their own AVCTORITAS from social +signals, not from a ledger. The harbour master's speed, the factor's promptness, +the willingness of witnesses to sign — these are the observables. + +**Drift mechanics:** +- Increases with: completed ventures, correct OTIUM, CLIENTELA maintenance, + successful FAENUS recovery, public witness of reliability +- Decreases with: defaulted obligations, visible commercial failure, association + with disgraced parties, FAENUS seen as predatory, prolonged absence from + social obligations +- Lag: changes are not immediate — AVCTORITAS shifts over weeks, not days + +**Uncertainty:** the actor's perceived AVCTORITAS may differ from their true +AVCTORITAS. A recently failed magistrate may not yet know how damaged his +standing is. A freedman may not know how much his practical reputation has grown. + +**Background starting values:** +- Former Legionary: medium +- Freedman Trader: low +- Noble Younger Son: high +- Failed Magistrate: medium (falling — true value lower than perceived) +- Camp Logistician: low +- Guild Scribe: low + +--- + +### CLIENTELA +``` +token: clientela +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** The network of mutual obligation between the actor and their +clients and patrons. Generates social access and information quality. Consumes +OTIUM to maintain. A MERCATOR with strong CLIENTELA receives better information, +better terms, and more reliable witnesses. One who neglects it finds doors closed. + +**Type:** network strength — breadth and depth +**Unit:** none — expressed as low / medium / high / extensive +**Observable:** partial — the actor knows who they know, but not always whether +those relationships remain active and reciprocal + +**Drift mechanics:** +- Increases with: OTIUM spent in social engagement, fulfilled obligations, + reciprocal favours, successful introductions +- Decreases with: neglect, failed obligations, social disgrace, prolonged travel + away from home base +- Lag: slow to build, faster to erode + +--- + +### LIQVIDITAS +``` +token: liquiditas +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Liquid capital available for immediate deployment — denarii in +hand, not goods pledged or debts owed. Distinct from total wealth. A MERCATOR +may be asset-rich and liquidity-poor. LIQVIDITAS is what actually governs +whether a venture can be initiated. + +**Type:** quantity +**Unit:** denarii (as integer) +**Observable:** full — the actor knows exactly what liquid capital they hold + +**Drift mechanics:** +- Decreases with: venture cost, ITER expenses, PORTORIUM, personnel wages, + HORREUM fees, FAENUS principal deployed +- Increases with: venture profit, FAENUS interest received, asset liquidation +- Immediate — no lag + +--- + +### FAMA +``` +token: fama +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Public reputation — what is generally said about the actor. +Distinct from AVCTORITAS (which is earned social capital) in that FAMA is +more volatile, more vulnerable to rumour, and more sensitive to recent events. +A single public failure can damage FAMA severely before AVCTORITAS is affected. + +**Type:** ordinal with valence +**Unit:** none — expressed as low / neutral / mixed / good / distinguished +**Observable:** partial — the actor hears what is said about them, but not all +of it, and not always accurately + +**Drift mechanics:** +- Volatile — responds quickly to visible events +- Affected by: public success or failure, rumour, association with other actors, + behaviour in visible social settings (BALNEA, forum) + +--- + +### DISCIPLINA +``` +token: disciplina +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Operational reliability — the actor's capacity to execute +plans consistently, manage personnel, maintain schedules, and function under +pressure. Not military discipline specifically — commercial discipline. The +ability to show up, follow through, and not improvise when improvisation is costly. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full — the actor knows their own operational habits + +**Drift mechanics:** +- Stable — changes slowly through repeated behaviour patterns +- Increases with: consistent venture execution, reliable scheduling +- Decreases with: erratic behaviour, frequent plan changes, personnel failures + +--- + +### MERCATVS_SCIENTIA +``` +token: mercatus_scientia +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Commercial knowledge — understanding of prices, goods, +markets, seasonal patterns, and the logic of supply and demand. Determines +whether the actor recognises opportunity, correctly prices ventures, and +anticipates market movements. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full — the actor knows what they know, though not what they +don't know + +**Drift mechanics:** +- Increases with: completed ventures, market exposure, information from CLIENTELA +- Background-specific: Freedman Trader and Camp Logistician start high; + Noble Younger Son and Former Legionary start low + +--- + +### ITINERIS_SCIENTIA +``` +token: itineris_scientia +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Route knowledge — familiarity with roads, sea lanes, waypoints, +hazards, seasonal constraints, and the practical logistics of movement. Affects +ITER duration estimates, ability to avoid delays, and recognition of route +disruption. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full + +**Drift mechanics:** +- Increases with: completed ITINERA, especially novel routes +- Former Legionary and Camp Logistician start high + +--- + +### IVS_ACCESSVS +``` +token: ius_accessus +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Legal access — the actor's practical ability to use the Roman +legal system: to enforce contracts, recover debts, obtain witnesses, and resist +legal pressure from others. Not just knowledge of law but standing within it. +A freedman may know the law perfectly and still lack access. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** partial — the actor knows their formal standing but not always +how it will be applied in a specific dispute + +**Drift mechanics:** +- Increases with: AVCTORITAS growth, CLIENTELA with legal contacts, successful + contract enforcement +- Noble Younger Son and Failed Magistrate start high + +--- + +### PERICVLVM_TOLERANTIA +``` +token: periculum_tolerantia +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Risk tolerance — the actor's willingness and capacity to accept +exposure to loss, physical danger, and uncertainty. Affects venture selection, +route choice during MARE CLAVSVM, and FAENUS terms accepted. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full + +**Drift mechanics:** +- Relatively stable — personality-level trait +- May decrease after severe loss events + +--- + +### NEGOTIATIO +``` +token: negotiatio +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Negotiation skill — the ability to achieve favourable terms +in commercial and social exchanges. Affects prices obtained, FAENUS terms, +FACTOR agreements, and conflict resolution. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full + +--- + +### LITTERAE +``` +token: litterae +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Literacy and accounting — the ability to read, write, and +maintain accounts. Affects the actor's ability to detect fraud, draft +contracts, and maintain a CODEX ACCEPTI ET EXPENSI. In 14 BCE Rome, not +universal even among merchants. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** full + +--- + +### OFFICIA_BVRDEN +``` +token: officia_burden +scope: actor +layer: roman +maturity: canonical +``` +**Definition:** Obligation load — the accumulated weight of social, civic, +and personal obligations competing with NEGOTIVM for the actor's time. High +OFFICIA_BVRDEN reduces available time for ventures and forces OTIUM expenditure +on obligations rather than restoration. + +**Type:** ordinal +**Unit:** none — low / medium / high +**Observable:** partial — the actor knows their formal obligations but may +underestimate the informal ones + +**Drift mechanics:** +- Increases with: AVCTORITAS growth (more people seek patronage), CLIENTELA + expansion, Noble Younger Son background +- Decreases with: fulfilled obligations, deliberate social withdrawal + +--- + +### BACKGROUND_DRIFT +``` +token: background_drift +scope: actor +layer: universal +maturity: canonical +``` +**Definition:** The degree to which the actor's starting background profile +still governs their parameter values versus the profile created by their +decisions. A Former Legionary who has conducted fifty FAENUS transactions has +drifted toward Guild Scribe behaviour. Background effects decay; decision +history accumulates. + +**Type:** 0.0 to 1.0 float per parameter (1.0 = fully background-governed, +0.0 = fully decision-governed) +**Observable:** hidden — the actor experiences this as gradual change in how +the world responds to them, not as a visible number + +--- + +## 2. City Parameters + +Parameters shared across players, anchored to a specific city substrate. +These change through events, not individual player decisions. They live in +the city substrate layer, not the per-player database. + +--- + +### RVMOR_VELOCITAS +``` +token: rumor_velocity +scope: city +layer: roman +maturity: canonical +``` +**Definition:** The speed at which information (accurate and inaccurate) moves +through a city's social network. High in port cities, baths, and dense market +districts. Affects how quickly scenario events are known, how distorted they +become in transmission, and how fast prices adjust. + +**Drift:** increases with transient population, decreases in winter + +--- + +### DOCK_CONGESTION +``` +token: dock_congestion_index +scope: city +layer: roman +maturity: canonical +``` +**Definition:** Pressure on port loading and unloading capacity. Affects +ITER departure delay, BAIВLVS availability, and PORTORIUM queue time. + +**Drift:** seasonal — peaks in spring and autumn, low in MARE CLAVSVM + +--- + +### STORAGE_FEE_INDEX +``` +token: storage_fee_index +scope: city +layer: roman +maturity: provisional +``` +**Definition:** Market rate for HORREUM storage. Rises when warehouse capacity +is constrained by high cargo volume or when distressed sellers need to hold +goods while awaiting better prices. + +**Research needed:** specific rate data for Ostia, 1st c. BCE + +--- + +### BATH_SOCIAL_DENSITY +``` +token: bath_social_density +scope: city +layer: roman +maturity: canonical +``` +**Definition:** The social richness of the BALNEA as an information and +relationship node. Determines the quality of rumour available and the +probability of encountering useful contacts during OTIUM. + +**Drift:** time-of-day dependent (midday peak), seasonal + +--- + +### LEGAL_ACCESS_INDEX +``` +token: legal_access_index +scope: city +layer: roman +maturity: provisional +``` +**Definition:** The practical availability and reliability of legal +enforcement in this city. Varies by magistrate quality, current political +pressure, and backlog. Affects IVS_ACCESSVS modifiers for all actors. + +--- + +### FIRE_RISK_INDEX +``` +token: fire_risk_index +scope: city +layer: universal +maturity: canonical +``` +**Definition:** Background probability of industrial or residential fire +in a city zone. Drives scenario trigger probability for SCENARIO-MERCHANT-0001 +and similar events. + +**Drift:** increases with workshop density, dry season, high transient population + +--- + +### RENT_PRESSURE_INDEX +``` +token: rent_pressure_index +scope: city +layer: roman +maturity: provisional +``` +**Drift:** increases with transient population factor + +**Research needed:** Ostia lodging costs, 1st c. BCE + +--- + +### FOOD_PRICE_INDEX +``` +token: food_price_index +scope: city +layer: universal +maturity: provisional +``` +**Research needed:** Ostia grain and prepared food prices, 1st c. BCE + +--- + +### PORTER_AVAILABILITY +``` +token: porter_availability +scope: city +layer: universal +maturity: provisional +``` +**Drift:** seasonal, event-sensitive (disrupted by fires, floods, political events) + +**Research needed:** BAIВLVS wage rates, 1st c. BCE Ostia + +--- + +### CART_AVAILABILITY +``` +token: cart_availability +scope: city +layer: universal +maturity: provisional +``` +**Drift:** decreases during scenario events involving transport disruption + +**Research needed:** cart hire rates, Via Appia, 1st c. BCE + +--- + +## 3. Scenario Parameters + +Parameters that exist only within a scenario's active window. They are +created when a scenario triggers, evolve during it, and are archived when +it closes. They must not persist into the city substrate as permanent values — +they are transient pressures, not permanent conditions. + +--- + +### WORKSHOP_OUTPUT_BRONZE +``` +token: workshop_output_bronze +scope: scenario +layer: roman +maturity: canonical +``` +**Scenario:** SCENARIO-MERCHANT-0001 +**Definition:** Current production capacity of bronze workshops in the +affected district. Drops to near zero at scenario start, recovers over +rebuild_delay_days. + +--- + +### VRBAN_FIRE_DAMAGE +``` +token: urban_fire_damage +scope: scenario +layer: universal +maturity: canonical +``` +**Definition:** Severity of fire damage to a specific district. Drives +multiple secondary parameter effects. +**Type:** ordinal — minor / significant / severe / catastrophic + +--- + +### TIMBER_STOCK_DESTROYED +``` +token: timber_stock_destroyed +scope: scenario +layer: universal +maturity: canonical +``` +**Scenario:** SCENARIO-MERCHANT-0002 +**Definition:** Volume of seasoned timber stock lost in the Capuan yard fire. +Governs the magnitude of downstream shortage effects. + +--- + +### BORROWER_DISTRESS +``` +token: borrower_distress +scope: scenario +layer: universal +maturity: canonical +``` +**Scenario:** SCENARIO-MERCHANT-0003 +**Definition:** Financial and operational stress level of the counterparty +seeking FAENUS. Governs offered return, default probability, and collateral +availability. +**Type:** ordinal — stable / stressed / distressed / insolvent +**Observable:** hidden — the actor infers from signals, never knows precisely + +--- + +### RVMOR_CREDIBILITY +``` +token: rumor_credibility +scope: scenario +layer: universal +maturity: canonical +``` +**Definition:** How accurate the current circulating rumour about a scenario +event is. High rumour credibility means the market has correctly interpreted +the event. Low means prices have not yet adjusted correctly — creating +opportunity or risk depending on the actor's knowledge. +**Observable:** hidden to actor — server-side truth only + +--- + +### VENTURE_WINDOW_DAYS +``` +token: venture_window_days +scope: scenario +layer: universal +maturity: canonical +``` +**Definition:** The number of days before the scenario's primary market +opportunity closes — either through price normalisation, competitor action, +or external resolution of the event. +**Observable:** partial — the actor estimates this from signals, cannot +know it precisely + +--- + +### HIDDEN_CAUSE_STATE +``` +token: hidden_cause_state +scope: scenario +layer: universal +maturity: canonical +``` +**Definition:** The true cause of the inciting scenario event, selected from +the hidden cause variant table at scenario seed time. Never revealed to the +actor directly. Governs which secondary effects dominate and how quickly +the scenario resolves. +**Observable:** hidden — signals only + +--- + +### SCENARIO_CHAIN_FLAG +``` +token: scenario_chain_flag +scope: scenario +layer: universal +maturity: canonical +``` +**Definition:** Whether a prior scenario in the chain has occurred in this +world seed. `recent_scenario_0001 == true` modifies recovery speed in 0002. +`recent_scenario_0001 or 0002 == true` increases FAENUS opportunity in 0003. +**Type:** boolean per scenario ID + +--- + +## 4. Relation and Derived Parameters + +Parameters that exist at the intersection of layers — cross-layer dependencies, +epistemic states, and derived values. These are first-class records, not +comments in the schema. + +--- + +### INFORMATION_QUALITY +``` +token: information_quality +scope: relation +layer: universal +maturity: canonical +``` +**Definition:** The accuracy and completeness of the information available +to a specific actor about a specific event or market state. Function of +CLIENTELA strength, rumor_velocity, and actor's location relative to the +event. +**Type:** 0.0 to 1.0 float (0.0 = pure noise, 1.0 = complete truth) +**Observable:** hidden — the actor does not know how good their information is + +--- + +### CONFIDENCE_TAG +``` +token: confidence_tag +scope: relation +layer: universal +maturity: canonical +``` +**Definition:** The epistemic confidence attached to any parameter value, +derived from source quality and inference chain length. Mirrors the confidence +tags used in research documents. +**Type:** enum — measured | indicated | inferred | estimated | unknown +**Use:** attached to any parameter record where the value is not directly +observable or where source quality is limited. Must be a first-class field +in the schema, not a comment. + +--- + +### DELAYED_KNOWLEDGE +``` +token: delayed_knowledge +scope: relation +layer: universal +maturity: canonical +``` +**Definition:** The lag between when a scenario event occurs and when a +specific actor's information_quality reflects it accurately. A MERCATOR +in Ostia learns about the Capuan timber fire after a delay determined by +route distance, rumor_velocity, and CLIENTELA reach. +**Type:** integer days +**Use:** applied per actor per scenario event + +--- + +### PERCEIVED_VS_TRUE +``` +token: perceived_vs_true +scope: relation +layer: universal +maturity: canonical +``` +**Definition:** The structural distinction between a parameter's true value +(server-side ground truth) and the actor's perceived value (what they believe +or can infer). Applies to: AVCTORITAS, FAMA, borrower_distress, +hidden_cause_state, rumor_credibility, information_quality, and any parameter +marked `observable: partial` or `observable: hidden`. +**Schema implication:** parameters with perceived_vs_true distinction require +two records — `value_true` and `value_perceived` — not one. This is not +optional. + +--- + +### BACKGROUND_AFFINITY +``` +token: background_affinity +scope: relation +layer: universal +maturity: canonical +``` +**Definition:** The degree of match between a specific actor's current +parameter profile and each of the six canonical backgrounds. Used to detect +background drift and to surface narrative signals to the actor about how +others perceive them. +**Type:** 0.0 to 1.0 float per background_id + +--- + +## 5. Universal Parameters (Cross-Period) + +Parameters marked `layer: universal` are candidates for the cross-period +schema shared between OTIVM and CIVICVS. They appear in both periods with +different expressions but the same underlying structure. + +| Token | Roman expression | Mesolithic expression | +|---|---|---| +| `liquiditas` | denarii | calories, stored food, portable goods | +| `information_quality` | rumour in BALNEA | territorial knowledge | +| `rumor_velocity` | port city gossip | inter-clan communication speed | +| `periculum_tolerantia` | maritime risk acceptance | predator territory tolerance | +| `fire_risk_index` | urban workshop density | hearth and camp fire risk | +| `venture_window_days` | market opportunity window | seasonal foraging window | +| `confidence_tag` | source quality | archaeological confidence | +| `delayed_knowledge` | route distance lag | territorial range lag | + +These mappings are provisional. The Mesolithic expressions will be confirmed +through corpus development. + +--- + +## 6. Stub Parameters — Research Needed + +Parameters identified as necessary but not yet fully defined. Listed here +to prevent schema decisions that assume they do not exist. + +| Token | Scope | Layer | What is needed | +|---|---|---|---| +| `portorium_rate` | scenario | roman | Specific rate data per crossing point, 1st c. BCE | +| `vectура_rate` | scenario | roman | Freight charge per cargo unit per leg, research brief target | +| `naufragium_probability` | scenario | roman | Per-voyage shipwreck probability from archaeological record | +| `mare_clausum_state` | city | roman | Binary seasonal flag with transition probability | +| `collegium_presence` | city | roman | Whether a relevant COLLEGIUM operates in this city | +| `factor_reliability` | actor | roman | FACTOR NPC trustworthiness — future release | +| `occ_flag` | city | mesolithic | Occupation evidence from TESSERA stage 06 — pipeline dependency | +| `terrain_restoration` | city | mesolithic | HYDE 3.3 / KK10 corrected terrain — pipeline dependency | + +--- + +## 7. Admission Rules + +A parameter is admitted to this registry when it passes all three tests +from `terminology.md`: +1. Period-authentic or explicitly universal +2. Semantically distinct from existing parameters +3. Scope-bounded — cannot be misapplied across layers without the + misapplication being visible + +A parameter may be added at any maturity level. It may never be removed. +Deprecated parameters are marked `maturity: deprecated` with a note on +what superseded them. + +--- + +*Parameter Registry — living document, 2026-04-28* +*Uncertainty is a first-class record, not a comment.* +*TheRON — single contributor. AI assistants implement, document, flag — do not direct.*