From 6c17968fc31171641585a39714941dafa35ae06a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 25 Apr 2026 10:01:31 +0100 Subject: [PATCH] Add Aetheria population model note --- README.md | 1 + .../aetheria-agent-population-model.md | 361 ++++++++++++++++++ .../aetheria-cold-wake-mvp-scenario.md | 2 +- .../aetheria-persistent-agent-architecture.md | 2 + 4 files changed, 365 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/aetheria-agent-population-model.md diff --git a/README.md b/README.md index dbaaad3..ccc75e1 100644 --- a/README.md +++ b/README.md @@ -555,5 +555,6 @@ Reasonable next steps from here: - [Architecture Overview](./docs/architecture/overview.md) - [Aetheria Persistent Agent Architecture](./docs/architecture/aetheria-persistent-agent-architecture.md) - [Aetheria Cold Wake MVP Scenario](./docs/architecture/aetheria-cold-wake-mvp-scenario.md) +- [Aetheria Agent Population Model](./docs/architecture/aetheria-agent-population-model.md) - [Things To Steal](./docs/research/things-to-steal.md) - [TypeScript Workspace Decision](./docs/decisions/0001-typescript-workspace.md) diff --git a/docs/architecture/aetheria-agent-population-model.md b/docs/architecture/aetheria-agent-population-model.md new file mode 100644 index 0000000..aa653f7 --- /dev/null +++ b/docs/architecture/aetheria-agent-population-model.md @@ -0,0 +1,361 @@ +# Aetheria Agent Population Model + +This note explains how a socially dense Aetheria region can feel inhabited without simulating every implied person as a fully persistent agent. + +The short answer is that population and agency are not the same thing. + +A corridor can imply hundreds of thousands or millions of people while only a few dozen individuals need to exist as full long-lived social nodes. + +## Design Goal + +We want a region that feels: + +- crowded +- economically alive +- politically pressured +- socially stratified +- full of rumor, labor, traffic, and institutional drag + +We do **not** want: + +- ten thousand expensive little chatbots idling in a warehouse +- fake scale achieved by silent cardboard extras +- a world where only named characters seem to exist + +So the population model needs to separate: + +- who exists as a persistent social mind +- who exists as a grouped social force +- who exists only as local scene color +- how offscreen population pressure becomes visible + +## Four Population Layers + +The MVP should use four layers. + +### 1. Persistent Agents + +These are the full agents. + +They have: + +- identity +- memory +- relationships +- goals +- obligations +- changing stance toward institutions and people + +These are the characters who accumulate history and can plausibly remember what happened last week, who lied to them, who saved them, and which institution just humiliated them. + +Examples in the Cold Wake slice: + +- a navigator council delegate +- a Lightsail dispatcher +- a dock labor organizer +- an insurer adjudicator +- an Aya sanctuary coordinator +- a pirate broker +- a cutout cognition vendor +- a Cryonix or Rossum technical rep + +These are not the population. They are the pressure points where population-scale systems become legible. + +### 2. Cohorts + +Cohorts are grouped social bodies that matter but do not need full individual cognition. + +They should represent classes of people whose collective condition can change over time. + +Examples: + +- dock labor shifts +- convoy deck crews +- insurer back-office clerks +- sanctuary residents +- clinic queues +- pirate route crews +- private security contractors +- debt pilgrims +- repair-bay technicians +- refugee transit waves + +Each cohort should have state such as: + +- size +- location +- stress +- trust in institutions +- rumor exposure +- faction sympathy +- fatigue +- scarcity pressure +- protest potential +- desertion / mutiny risk + +This is how the world gets to have labor, crowds, queues, shortages, and unrest without pretending every forklift operator needs a hundred memories and a private speech cadence. + +### 3. Ephemeral Scene Actors + +These are temporary people instantiated only when a scene needs bodies, witnesses, clerks, mechanics, medics, bystanders, or small bits of friction. + +They should have: + +- a role +- a scene goal +- local awareness of current events +- a little voice +- minimal short-term memory + +They should **not** be treated as deep persistent minds by default. + +Examples: + +- a berth marshal waving traffic through a panic checkpoint +- a frightened passenger arguing with a clerk +- a dockhand spreading a fresh rumor +- a medic triaging one more body than the shift can really handle +- a sanctimonious insurer junior who disappears once the scene ends + +If an ephemeral keeps mattering, the system can promote them into a persistent agent later. + +### 4. Ambient Population Pressure + +This is the layer that makes the world feel bigger than the visible cast. + +It is not represented by people at all. It is represented by signals. + +Examples: + +- berth queues growing or shrinking +- cargo backlogs +- corridor delay maps +- sanctuary occupancy +- clinic wait times +- food prices +- insurance repricing +- labor slowdown notices +- protest bulletins +- casualty lists +- rescue requests +- media chatter +- tribunal rulings +- route closures + +This is where the implied millions live in practice. + +## How The Layers Interact + +The model should feel like this: + +- ambient pressure changes cohort state +- cohort state changes the incentives around persistent agents +- persistent agents make decisions that alter ambient pressure +- ephemeral actors express the local scene consequences + +That loop lets a single adjudicator decision or pirate rescue cascade outward into visible population-level effects without simulating every single person affected. + +## Why A Few Dozen Persistent Agents Is Enough + +Because the simulation is not trying to create a census. It is trying to create a socially legible machine. + +In a corridor like Ganymede, one persistent agent can sit at the hinge point for a great many people: + +- one dispatcher affects dozens of ships and hundreds of crew +- one sanctuary coordinator gates a network under pressure from thousands of vulnerable lives +- one insurer official can reprice route access across the corridor +- one navigator delegate can legitimize or delegitimize rescue, inspection, and route closure +- one pirate broker can redirect shadow traffic across many dependent cells + +The persistent cast is therefore best understood as: + +- decision-makers +- bottlenecks +- brokers +- organizers +- interpreters of institutional rules +- people with unusual leverage over larger flows + +They are the knots in the rope, not every fiber. + +## Cohort Model + +Cohorts should be tractable and opinionated. + +Each cohort record should include: + +- `cohortId` +- `type` +- `sizeBand` +- `region` +- `factionAffinity` +- `currentPressures` +- `resourceDependency` +- `confidence` +- `grievance` +- `discipline` +- `mobilizationPotential` +- `recentIncidents` + +Useful cohort types for Cold Wake: + +- dock labor +- convoy crews +- sanctuary residents +- insurer workforce +- pirate crews +- repair-yard workers +- shadow clinic clients +- private security detachments +- local merchant bodies +- transient passenger pools + +Cohorts do not need rich dialogue. They need believable collective reactions. + +## Ephemeral Actor Rules + +Ephemeral actors should be generated from: + +- scene location +- cohort state +- current world pressures +- factional tone +- time of day / shift + +That means the same dock concourse can produce different incidental people depending on whether the corridor is calm, panicking, starving, over-inspected, or politically inflamed. + +Ephemerals should support: + +- local exposition +- scene texture +- small moral friction +- witness testimony +- short disputes +- visible consequences + +They should expire cheaply unless the world keeps pulling them back into relevance. + +## Promotion Rules + +Some ephemerals should be promoted into persistent agents when: + +- a player or major agent forms an ongoing relationship with them +- they become central to repeated incidents +- they accumulate leverage or notoriety +- they are the surviving witness to something politically explosive +- they become the face of a cohort-level shift + +Promotion is how the world grows specific people organically instead of requiring the whole cast to be authored up front. + +## Population Signals That Make A Place Feel Busy + +If the corridor is meant to feel inhabited, the system should constantly surface signs of offscreen life. + +That means scenes, dashboards, and local UI should be fed with things like: + +- arrivals and departures +- route advisories +- late manifests +- dockside rumor digests +- occupancy warnings +- strike whispers +- inspection delays +- tribunal alerts +- debt-claim notices +- casualty and rescue numbers +- commodity shocks +- public feeds and scandal bursts + +The player does not need to meet everyone. They need to feel surrounded by consequences. + +## Cold Wake-Specific Population Recipe + +For the first slice, a sensible starting mix is: + +- **20-40 persistent agents** +- **10-25 cohorts** +- **0-20 ephemerals per active scene**, generated on demand + +Persistent clusters: + +- Navigators +- Lightsail +- PSC / insurers +- Aya +- pirates +- cutout vendors +- local technical reps + +Cohorts: + +- dock labor +- convoy crews +- sanctuary overflow +- clinic queues +- inspector pool +- security contractors +- pirate cells +- repair techs +- cargo handlers +- passengers / transients + +That is enough to make the world feel socially populated without turning the runtime into a screaming furnace. + +## Simulation Tier Mapping + +The population layers should map onto the simulation tiers cleanly. + +### Tier 0 + +- dormant persistent agents +- slowly changing cohorts +- coarse ambient indicators + +### Tier 1 + +- active persistent agents making strategic moves +- cohorts shifting under pressure +- route, labor, and sanctuary state updating + +### Tier 2 + +- a handful of persistent agents in scene +- relevant ephemerals generated for the local moment +- cohort state informing mood, risk, and crowd behavior + +### Tier 3 + +- full interactive dialogue for the most relevant persistent agents +- ephemerals only as needed for texture or interruption +- world pressure visible through feeds, queues, alerts, and consequences + +This keeps expensive cognition focused where it matters. + +## What Not To Do + +Do not: + +- simulate every resident as a full agent +- let cohorts become inert statistical wallpaper +- use ephemerals as consequence-free decoration +- make named agents behave as if the rest of the world does not exist +- make ambient scale purely visual with no mechanical pressure + +That path leads to a world that looks crowded and feels dead. + +## Success Criteria + +The model is working if: + +- the player can feel institutional pressure without being told about it in lore prose +- small decisions by key agents visibly affect larger populations +- cohorts can become restless, relieved, fearful, or politically active +- scenes feel crowded when they should +- the same corridor can feel different under calm, panic, shortage, scandal, or repression +- the named cast feels embedded in a larger society rather than posed in a diorama + +The real test is simple: + +If the player leaves the room, do they still believe thousands of people are having a bad day because of what just happened? + +If yes, the world is inhabited. diff --git a/docs/architecture/aetheria-cold-wake-mvp-scenario.md b/docs/architecture/aetheria-cold-wake-mvp-scenario.md index c74b1a2..2b68c78 100644 --- a/docs/architecture/aetheria-cold-wake-mvp-scenario.md +++ b/docs/architecture/aetheria-cold-wake-mvp-scenario.md @@ -2,7 +2,7 @@ This is the first buildable scenario brief for the persistent-world agent work. -The broader machine lives in [Aetheria Persistent Agent Architecture](./aetheria-persistent-agent-architecture.md). This document is the narrower, dirtier thing: one bounded slice of the setting that is small enough to simulate and rich enough to misbehave. +The broader machine lives in [Aetheria Persistent Agent Architecture](./aetheria-persistent-agent-architecture.md). The population scaling answer lives in [Aetheria Agent Population Model](./aetheria-agent-population-model.md). This document is the narrower, dirtier thing: one bounded slice of the setting that is small enough to simulate and rich enough to misbehave. ## Premise diff --git a/docs/architecture/aetheria-persistent-agent-architecture.md b/docs/architecture/aetheria-persistent-agent-architecture.md index a846062..bedc53d 100644 --- a/docs/architecture/aetheria-persistent-agent-architecture.md +++ b/docs/architecture/aetheria-persistent-agent-architecture.md @@ -4,6 +4,8 @@ This is the companion document to [Things To Steal](../research/things-to-steal. For the first concrete slice, see [Aetheria Cold Wake MVP Scenario](./aetheria-cold-wake-mvp-scenario.md). +For the scaling model that explains how a crowded region can be simulated with a relatively small persistent cast, see [Aetheria Agent Population Model](./aetheria-agent-population-model.md). + That document is the theft list. This one is the machine we are trying to build out of the stolen parts. The target is a persistent world full of in-universe agents who: