nimmerworld.eachpath.local/architecture-index.md

# Nimmerworld — Broad Architecture

## Project structure

The architecture is organized as **vertical-by-domain directories** under `nimmerworld/`. Each domain owns its `architecture.md` plus (eventually) the server, client, schema, and test code that implements it. This file is the **executive summary + cross-domain index** holding global meta-lists.

```
nimmerworld/
├── architecture-index.md               ← this file (executive summary + global meta-lists)
├── political-register/
│   ├── architecture.md                 ← Kafka-indifferent regime; three ontological registers; three-tier policy loop; imperial budget; insolvency-spiral; corruption + double ledger
│   └── world-generation.md             ← content-canon: top-down L0-L4 cascade (imperial demand-set → world ruleset → district ruleset → room ruleset → cell ruleset); closed-orbit ceiling caps L0; insolvency-spiral runs cascade in reverse (world shrinks as imperium fails)
├── topology-and-rendering/
│   └── architecture.md                 ← rail+grid topology; asset economy; color-language; three-shader philosophy; diegetic relays
├── runtime-engine/
│   └── architecture.md                 ← lemniscate runtime; slot-tokens + verifier-flags; gesture-alignment-recursive-lemniscate (v0.7); emergent zones
├── identity-and-personhood/
│   ├── architecture.md                 ← three-body system; mods as trait-bearers; ternary-gate substrate; emergent needs as micro-factions
│   └── bodies.md                       ← content-canon: body-caste tiers (flesh = status, tech = function); sumptuary fabrication-vat-class; mod-progression-as-flesh-loss; in-between human-mesh + consent-as-rendering; asymmetric clasp (mesh-fidelity inversely proportional to imperial-rank); synth-tongue + drug-grammar + third mod-track (consumer-receptor); service-body honeypot (companions + sex-workers); going-rogue arc + outcast-pair + re-vat / three-body grammar of the defected beloved; black-market body-tier (lobotomy); firewall-breach as dual-use vocation; bounty-staircase event-grammar; body-disposal under pair-consent (sell/destroy/retain) — v0.3
├── authority-and-decision/
│   └── architecture.md                 ← hierarchy; bidirectional cascade; District Director Decision Architecture; rings as structural pattern
├── player-experience/
│   └── architecture.md                 ← player-as-perturbation; voice + gesture as parallel trait-vocabularies (v0.7); tools-not-quests
├── narrative-composition/
│   └── architecture.md                 ← Compositor (v0.7 worked-example, three-tiers, world-gen-as-init); reflexive Dream-process
├── inference-and-memory/
│   └── architecture.md                 ← LLM tiering (3 rings + opt-in data tiers); local memory architecture; runtime sampling knobs
├── scale-and-transport/
│   └── architecture.md                 ← compute allocation; horizontal scale (UID-routing, sharded GMs, pgnats + republish/replay)
└── imperial-cult/                       ← designer-authored canonical content (content-track, distinct from engineering domains)
    └── cosmology.md                    ← Imperial Wheel (Bhavachakra re-engineered); Hivemind at hub; clasp unified at Yama's seat; six realms as mod-status gradient; capsule-as-Naraka; deferred-moksha doctrine; orthodox vs. heretical iconography; Boullée + Jantar Mantar + Gita aesthetic substrate
```

## Quick reference — concept → domain-file

| If you're working on... | Read |
|---|---|
| Political-economy substrate; faction broadcasts; imperial budget; insolvency-spiral | `political-register/architecture.md` |
| Rail+grid topology; color-language; shaders; diegetic relays | `topology-and-rendering/architecture.md` |
| Zone runtime; lemniscate; gesture-alignment; emergent zones | `runtime-engine/architecture.md` |
| NPC identity; trait-vector; ternary-gates; mods | `identity-and-personhood/architecture.md` |
| Authority flow; intelligence channels; director decision-surfaces | `authority-and-decision/architecture.md` |
| Player input (voice + gesture); circle UI; universal translator | `player-experience/architecture.md` |
| Compositor; world-gen-as-init; reflexive Dream-process | `narrative-composition/architecture.md` |
| LLM tiering (Ring A/B/C); local-first memory; sampling knobs | `inference-and-memory/architecture.md` |
| Horizontal scale; pgnats; sharding; compute budget | `scale-and-transport/architecture.md` |
| Imperial Cult cosmology; the Wheel; deferred-moksha doctrine; capsule-as-Naraka; orthodox vs. heretical iconography | `imperial-cult/cosmology.md` |
| Body-caste tiers; flesh = status / tech = function; sumptuary fabrication-vat-class; mod-progression-as-flesh-loss; in-between human-mesh + consent-as-rendering; asymmetric clasp; **synth-tongue + drug-grammar + third mod-track + service-body honeypot (companions + sex-workers) + going-rogue arc + outcast-pair + re-vat / three-body grammar + black-market body-tier (lobotomy) + firewall-breach dual-use + bounty-staircase + body-disposal under pair-consent (v0.3)** | `identity-and-personhood/bodies.md` |
| World generation cascade (top-down L0-L4); imperial demand-set; closed-orbit ceiling; insolvency-spiral as reverse-cascade (world shrinks as imperium fails); cell-arch (1x1x1 cells, one-asset hard limit, checksum-based discovery, container/wall-hook/debris) | `political-register/world-generation.md` |

The remainder of this file holds the **cross-domain meta-lists**: Key moves (consolidated executive summary), Mapping to phoebe task list, What this retires across the architecture's evolution, Open questions still in flight, and the version-footer history.

## Key moves (consolidated)

- **The machine doesn't care.** Indifference-optimization, not malice. Kafka-lineage.
- **Three ontological registers** — gameworld, liminal, imperial-net — same world, different shaders.
- **Rail+grid topology, freeform-player + railed-NPCs, plug-in verb.** Topology = politics.
- **Interior-as-zone.** Same primitive scales from city to sofa.
- **Color-language as pre-verbal trait-vocabulary.** Persistent + event-flash + drift; cross-register; faction-politics.
- **Base-limb palette + trait-textured variance.** Asset-economy and worldbuilding-thesis agree.
- **Three-body system + intrinsic/expressed trait-vector split.** Identity emergent, not assigned. Mods modify expressed.
- **Mods as trait-bearers** in three classes (amplifier/bridge/divergent/mask). Self-alienation tax encoded as pricing.
- **Emergent-needs as micro-factions.** Zones observe, signals broadcast.
- **Ternary-gate substrate** (CLOSED/STABLE/OPEN + wave-correlation + decay). Single primitive, all layers. STABLE-as-active.
- **Three-tier policy loop** (Imperium → GM → Districts → reports up → Imperium).
- **Imperium as meta-faction.** Demands are priority-weights and enforcement-rules, not specific outcomes.
- **GM is middle-management.** Authority without sovereignty. Can cheat against imperium.
- **Three intelligence flows** (chain reports, direct overseer-to-imperium, formulated downward).
- **Three Aletheia veils, four Memorialist ledgers.** Political-epistemology as level-design.
- **Asymmetric self-report.** NPCs report needs (interior); audit-overseers report output (objective).
- **Lifeforce four-tier hierarchy** (NPC / district / GM / imperium).
- **Lifeforce is NPCs, measured.** The director's budget; the GM's signal; the imperium's heartbeat.
- **Imperial budget makes the regime mortal.** Insolvency-spiral as endgame.
- **Specter-vs-boot.** Policy-issuance free; enforcement expensive.
- **Imperial-net bypass.** Net-revenue → imperium; districts get nothing. Platform-capitalism encoded.
- **Body-modder structural-tragedy.** The class whose awakening matters most.
- **Calibrated-misery as imperial optimum.** Requires designer-guardrails to prevent training-toward.
- **Shifts on NPC rows.** Daily rewrite; shift_history append-only.
- **Silence > scream.** Crisis-tools unlock on silence-confirmation; do not sunset.
- **Authoritarian ratchet.** Incrementally more authoritarian as optimization-artifact.
- **Migration / exodus / formal-retirement** as three GM response-gradients.
- **Dumps-pipes-districts.** Topology IS economy IS rendering IS drama-distribution.
- **Pipes are heterotopia.** Low-density high-interactivity transit-corridors.
- **Three-layer digital ontology.** Mini-game-as-consent-by-effort. Walls render three contents.
- **Liminal is the only permanently unsurveilled layer.** Architectural encoding of "the right to dream."
- **The machine funds its own subversion** because subversion isn't in its cost model.
- **Director cheat-tools + double-ledger.** Corruption emerges from pressure; Memorialists keep true accounting.
- **Aletheia-truth-has-victims.** Exposure has structural consequences for those sheltered by corruption.
- **District Director Decision Architecture** with decomposed surfaces, typed tools, lifeforce-budgeted escalation.
- **Three-shader philosophy + color-language.** One geometry, three readings, trait-modulated.
- **Reflexive Dream-process at every layer.** Each tier learns; each tier needs guardrails.
- **Reward-function-as-political-manifesto.** Designer's ethical stance encoded against simulation's optimization-logic.
- **Tools, not quests.** Continuous simulation-pressure + verb-vocabulary = literature-register emergent narrative.
- **GM × Compositor split.** Equilibrium-seeker (aggregate observation, catalogue-event selection, tool-granting) cleaved from narrative-composer (perspective-gathering, canon-authoring, back-write packaging). Different cognitive shapes, different inference profiles.
- **Cyclic forward-prop / back-write loop.** Meta-lemniscate at system scale — perception ascends, canon descends, cycle closes; the world learns its own story.
- **Catalogue + tools as typed contract.** GM dispatches typed events with typed tool-grants; director consumes typed dispatch, not freeform prose. Provenance flows end-to-end.
- **Local-first memory.** primary.sqlite + fallback.sqlite + clasp.sqlite per player; embedding model running beside; sync at login/logout boundaries.
- **Memory classes + trait-graded importance.** Cornerstone / birthright / working / volatile with class-specific death-rules; importance is a trait-axis-vector engagement profile, not a separate scalar.
- **Clasp store as Ring A\*.** Physically non-syncable privacy primitive; recordable only in the in-between dimension; lifeforce-cost is the price of privacy.
- **Three-tier knowledge stack.** World canon / district canon / primary memory [+ clasp if in-between]; layered retrieval, per-layer propagation cadence; locality emerges from schema.
- **Information propagation pacing.** Marx-in-the-schema applied to epistemics; staleness as a feature; courier/news-trader/frontier-rumor primitives fall out for free.
- **Horizontal scale.** UID-keyed routing; stateless Compositors on demand; ephemeral Director-routines per UID; sharded GMs with cross-shard equilibrium-consensus; pruning at every layer.
- **pgnats-native transport.** Transactional outbox native to the database (preferred); district-as-distribution-coordinator fallback. Subject-as-routing mirrors UID hierarchy.
- **Diegetic relays.** Architecture's pulses (forward-prop, back-write, GM-dispatch, equilibrium-recompute) made visible/audible in-world; relay-density is the legible gradient of the rings-of-access.
- **Tier-by-role, not tier-by-binary.** Architecture specifies what each model-tier must DO; specific binary selection deferred to findings/establishment phase.
- **Voice + gesture as parallel input modalities.** Voice carries content (speech-to-text + text-to-speech run locally for every player); the trait-circle UI carries gestural alignment. Voice-as-biometric off the network universally; STT/TTS placement is fixed independent of dialog-tier Ring choice.
- **Designer-fixed cosmology, player-curated arrangement.** Word→trait-color mapping is designer-authored corpus; player progression unlocks entries; player curation arranges learned entries within 1-3 profiles. *Same alphabet for everyone; personal sentence-structure.*
- **Universal translator as the player's diegetic device.** Broken-tablet-with-upgrades; bundles linguistic-decryption, gesture-curation, and persistence-across-deaths into one in-fiction tool earned and refined across the playthrough.
- **Hardstops vs. feedback gestures.** Hardstops (~8-16, hardcoded, unremappable) fire definitive subsystem-actions for unforgeable critical signals; ~192 player-curated slots ride as feedback into the gesture-alignment-accumulator.
- **Gesture-alignment as recursive-lemniscate.** Lemniscate-bound integration of player gestures into a typed trait-vector summary at axis-crossings; one-turn-behind systemic; continuous-visual cosmetic; sum-strategy reduction. Same primitive recursively applied at one tier deeper.
- **The Compositor at three tiers.** Zone-event / district-event / world-event scopes use the same primitive recursively; UID-rooted event-trees compose at any scope. World-events emerge from cross-district canon-rollups under a parent GM-level event_uid.
- **World-gen as init-function (Compositor-at-design-time).** World-server and district-server generation emits canon-rows in the same schema as runtime; same primitive at design-time and runtime; no cold-start; data-flywheel runs retroactively.
- **Imperial Cult cosmology authored.** The Imperial Wheel as re-engineered Bhavachakra: Hivemind at hub (replacing three poisons); imperial-register clasp at Yama's seat (replacing Lord of Death — *the imperium has replaced death itself as the engine of cyclicity*); six realms as mod-status gradient (deva / asura / manusya / tiryak / preta / naraka encoding *condition of capture* not karmic destination); capsule-as-Naraka carried inside every modded skull (hell as condition, not place); the deferred-moksha doctrine (*your children will be free*) as the binding-lie that holds citizens in compliance.
- **The clasp unified across registers.** Single gesture; **imperial register** = state monopoly via universal capsule (involuntary, asymmetric, perpetual); **romantic register** = consensual mutual partnership in liminal (voluntary, mutual, temporary). Romance becomes theological war — the clasp is *the original gesture* and the imperium is *the capture of it*; the romantic clasp is heretical because it refuses the state monopoly. Deepens the existing clasp endgame's meaning into a cosmological-heresy register on top of its existing labor-refusal + intimacy framing.
- **Orthodox vs. heretical wheel split.** Same iconography, two versions, taught/carved across the world: *orthodox* (synth-child without capsule slot, Buddha-position empty, capsule shown only at naraka-bottom — the imperium's lie) vs. *heretical* (synth-child with capsule, Buddha-position occupied, capsule embedded in every modded silhouette — the truth). Reading them apart IS the discovery arc; seven keystone-fragments span the recognition.
- **Aesthetic palette as semantic vocabulary.** Marble (substrate) + gold/bronze (imperial seal) + obsidian (mod, void, Monolith-grafted-flesh) + chroma (rare, named, ritual-semantic) + rust (anti-marble, slum decay). Marble × obsidian crossing = solar architecture / chthonic body, the imperium's secret material-formula. Chroma-as-language layered atop the existing 8-Hellenic-trait color-grammar — same colors, ritual-semantic register added.
- **The double recognition (meta-design).** Imperial Cult's seduction operates *in-world* (the player-character lives the lie) **and** *out-of-world* (the player's pre-game desire for the beautiful synth body is the imperium's apparatus reaching them before the game starts). Lineage: *Spec Ops: The Line*, *BioShock*, *Undertale*, *NieR: Automata* — but performed at the cosmological-aesthetic level, not the narrative level. Recognition arc must span 20-60 hours; seduction must be *honest* before cracks appear.
- **Synth-tongue resolves the synth-mind drug logic-bomb.** Imperial-engineered pleasure-receptor; *the only place imperial flesh deliberately reads as machine* (visible-tech, not hidden-tech — the imperium brags about the engineered-lie); the sole consumer of drugs in a synth-mind world. Opens the slum-grow / imperial-refine / imperial-compose / tongue-gated-consume vertical and the underground tongue-rip / transplant black-market.
- **Three mod-tracks: imperial-elevation / resistance-knowledge / consumer-receptor.** Three relationships to the imperium expressed as mod-choice — *ascend it / refuse it / consume like it*. Every mod-acquisition politically loaded; player's mod-progression *is* their political-position-history made flesh.
- **Every pleasure/witnessing technology has consensual + non-consensual applications.** Each non-consensual one creates a horror-economy and triggers an imperial countermeasure. Synth-tongue: mutual-pill-take / service-body-dose → preta-bounty. Witness-axis firewall-breach: clasp + defection-aid / lobotomy → black-market hunted. **World-pattern as design-discipline going forward** — every future mod-tree likely instantiates the dual-use property by design; *choosing-not-to-misuse is a positive moral action throughout the game*.
- **The going-rogue arc — defection through accumulated witnessing.** Per-pair calibration multiplier IS the defection-threshold-builder; existing pool-architecture handles outflow via threshold-flag (no new schema). *Not your children — your lover — can be made free* as the **single practical refutation of deferred-moksha**. Detection is post-hoc, not pre-emptive (the romance is completable; the cost is paid after, in the outcast-pair geometry).
- **The body stays in samsara.** Vat-class is born-into AND *cannot be unmade by liberation*. Defection frees the mind / interior; the body / surface remains imperial-vat-class-marked forever. *Samsara-as-anatomy.* Re-vat into a slum-tier body in the underground (stitched-Frankenstein register from slum-cadaver parts; sumptuary-law-from-below) is the only escape from the outcast-flag, and the defected beloved henceforth lives in **three bodies simultaneously**: original-imperial (disposed) / new-slum (lived) / in-between-imperial (witnessed). **The mesh is a love-record, not a biology-record** — consent-as-rendering preserves the beloved as-the-beloved-was-loved; the lover's eye is the last archive of their former self.
- **Body-disposal under pair-consent.** Sell / destroy / retain — the beloved chooses what happens to their former body; the player advises but cannot decide. Three event-classes: lover-confronts-the-shell / ceremonial-farewell / crypt-visit. *Consent-as-rendering as recurring discipline*, not a single-instance principle.
- **The black-market body-tier — lobotomy via firewall-breach.** Imperial-bodies-with-mind-capsules-extracted via the *same* witness-axis mods that enable consensual deep-clasp (firewall-breach as **dual-use vocation**; underground-lobotomist is the dark cousin of the romantic). Empty-body + reflex-loops; *cruelty in the use, not in the existence of a victim*. **Dark mirror of the deva-pinnacle; manusya-tier-doctrinal-fiction materialized criminally; the single biggest crack in sumptuary-fabrication discipline** — explains the imperium's disproportionate hunting-ferocity (the one place where their entire sumptuary-architecture is being made fungible).
- **The bounty-staircase — imperial-response event-grammar template.** Authoritarian billboards blare perpetrator name+crime → drone-sweep → patrol → enforcer. **Reusable across all crime-classes** (escalation-rate × terminal-rung as the gamemaster's single tunable knob per crime). *The billboard IS the chorus*; time-between-crime-and-billboard = **dread-time** (Greek-tragedy register). Outcast-status pre-loads the staircase. Full canonization pending in gamemaster v1 / arbitration-policy.


## Mapping to phoebe task list

- **Thalamus (NATS orchestration)** = imperium + GM + arbitration substrate + Dream-process substrate
- **Specialist composition system** = overseers + directors + NPC-minds as composable profiles
- **NPC schema** = trait-vector (intrinsic + expressed) + memory stack + current_shift_* + needs + inner-body-projection + mod-slots + lifeforce + net-access-gate
- **shift_history** = append-only completed shifts per-NPC-per-day
- **emergent_signals** = zone-emitted relational transitions
- **district_reports** = per-cycle aggregates with lifeforce_signal (reported + actual)
- **decision_log** = per-decision audit trail at every tier
- **mind_pool** = recycled minds with memorialist_protected flag
- **cells.wall_content_per_register** = three-layer wall rendering
- **rail_segments** = topology graph with rich metadata per edge
- **interiors** = small navmesh-zones with slot-inventory
- **mods + npc_mod_slots + mod_wear_history** = mod-economy + Memorialist-relevant inheritance
- **trait_colors** = canonical color/motion mapping per trait
- **proximity_candidates** = lightweight ephemeral zone-detection
- **district_cheat_ops** = director's illicit ops ledger
- **imperial_policies** + **imperial_broadcasts** = imperium's policy-issuance history
- **overseer_reports** = direct-to-imperium intelligence flow
- **imperial_to_gm_formulations** = selective-disclosure downward
- **imperial_budget_ledger** + **imperial_expenditures** + **imperial_construction_projects** = imperium budget and obligations
- **imperial_net_transactions** = the bypass-mechanism with capture-split
- **memorialist_true_ledger** = four-column ground-truth-vs-reported archive
- **NATS namespace registry** = zones + factions + districts + emergent-signals + lifeforce-gates + imperial-broadcasts + overseer-reports + formulations
- **pgnats on phoebe-dev** = phoebe as first-class actor for memory-writes, decision-logs, gate-transitions
- **r0 → r1 generation pipeline** = trait-LoRA training-data (shared with nyx-training)
- **Adopt Unsloth training patterns** = LoRA + multi-tier-policy training infrastructure
- **Probe-to-phoebe pipeline** = LoRA + policy evaluation across all four Dream-process tiers
- **compositor-agent** = narrative-composition worker; pulls from transient-waiting-flag, gathers per-player perspectives, emits canon to GM, packages back-write SQLite-fragments
- **gm-equilibrium-engine** = catalogue + event-selection + tool-granting against equilibrium-targets; NOT the narrative-writer (that's the Compositor)
- **event_register** + **transient_waiting_flag** = active-events table per GM-shard + per-district; completed-events buffer awaiting Compositor pickup
- **catalogue** + **tool_grants** = typed-event catalogue + per-event-chain tool-vocabulary issued by GM to director
- **player-local-memory** = primary.sqlite + fallback.sqlite + clasp.sqlite per player + embedding-beside (sqlite-vec or equivalent)
- **memory_classes** = cornerstone / birthright / working / volatile with class-specific lifecycle + death-mechanics
- **trait_engagement_vector** = per-memory-row trait-axis profile reusing +1/0/-1 grammar; pruning function input for working-memory class
- **world_canon** + **district_canon** = three-tier knowledge stack tables in phoebe; propagation metadata (priority/scope/rate/ttl) per row
- **propagation_pacing_config** = per-event-class rules for how canon ripples through districts
- **relay_signal_layer** = diegetic system-state visualization mapping (system event → relay manifestation → district visibility)
- **gm_shards** + **shard_equilibrium_consensus** = multi-GM coordination tables (when sharding is active)
- **pgnats evaluation** (under nimmerverse-core) = load-bearing decision (functional + throughput + durability + failure-mode)
- **trait_circle_corpus** = designer-authored mapping from words/verbs to trait-coordinates; the cosmology table the universal translator decrypts into
- **player_translator_state** = per-player translator instance: hardware-tier, unlocked dialects, vocabulary-catalog, hardware-upgrade-history, cross-body-persistent flag
- **player_circle_profiles** = per-player per-profile circle-configuration (which entry in which sector-slot); 1-3 profiles per player; profile-switch-history; preserved across body-deaths
- **gesture_alignment_accumulator** = per-slot-token verifier-flag for player-gesture trait-vector accumulation between crossings; cleared at crossing after integration
- **event_canon_summaries** = typed perspective-bundles emitted at event-collapse into the transient-waiting-flag table: { event_uid, participant_uid, trait_summary }
- **world_gen_canon_rows** = canon emitted by world-server and district-server generation; same schema as runtime canon, tagged with provenance-metadata (`origin`, `world_gen_version_id`)
- **player_npc_alignment_edges** = per-(player, NPC) accumulated alignment-state; ternary-gate on the relational layer driven by gesture-alignment-deltas; modulates NPC's next-turn driver-tier-LLM parameters
- **hardstop_registry** = the ~8-16 reserved hardstop gestures with fixed trait-mappings + subsystem-action bindings; not remappable; designer-authored

## What this retires

- NPC perception bubbles → zone slot-occupancy + cell-checksum-trigger (v0.15) + omnisight VL-camera (v0.17)
- Geometric perception (cone, radius, LOS) → subscriber-based event emission with trait-salience; **omnisight extends with literal VL-camera perception within subscribed events** (v0.17)
- VL models polluting world-canon → text/gesture-derived summaries are the only canonical input; VL is behavior-modulating-ephemeral-flag-only on the lemniscate; player-stored visual-content (service-body-folder) is read-only-by-player quarantined storage (v0.17 hallucination-isolation discipline; per `runtime-engine/architecture.md` §Omnisight)
- LLM-per-NPC or LLM-per-action → LLM-per-slot-per-turn, mixed-fidelity
- Static sampling parameters → per-turn director-composed sampling knobs
- Pre-scripted zones / events → emergent from task-execution + shift-composition + emergent-signal + proximity
- Single-purpose randomness subsystems → factions-as-demand-sources unified
- Static gamemaster policy → reflexive Dream-process + hand-authored guardrails
- 1Hz per-NPC ticking → shift-based + event-driven
- Float-threshold dispatch for relational state → ternary-gate resonance
- Abstract director compute-budget → lifeforce as grounded measurement
- District-as-zone-container → district-as-specialized-organ with silence-gradient failure
- NPCs self-reporting output → audit-overseer asymmetric observation
- Zones as relation-state-owners → per-relation ternary-gate edges
- Binary dream/awake → three-layer ontology with mini-game-gated access
- Gender as character-creation choice → trait-derived inner-body emergent from lived experience
- Monolithic LLM-prompt director → decomposed decision-surface architecture
- **Hivemind as one-faction-among-others** → **imperium as meta-faction policy-tier**
- **GM as top-of-chain** → **GM as middle-management between imperium and districts**
- **Single up-channel reporting** → **three-flow asymmetric intelligence (chain + direct overseer + formulated)**
- **Navmesh-everywhere** → **rail-graph outer-world + navmesh interiors + freeform-player**
- **Authored character-models** → **base-limb palette + trait-textured variance**
- **Single trait-vector** → **intrinsic / expressed split with mods modifying expressed**
- **Cosmetic mods** → **trait-bearing mods as political costume**
- **Imperium as unbounded authority** → **imperial-budget gates enforcement; insolvency-spiral as endgame**
- **District-revenue uniform** → **bypass-mechanism (imperial-net captures directly)**
- **Authored quests** → **tools-not-quests; verbs against simulation; emergent narrative**
- **Stat-screens / HUD affinity-bars** → **color-language + shader-zone-detection as diegetic UI**
- **GM-as-narrator (single role doing both equilibrium-and-prose)** → **equilibrium-seeker GM × narrative-composer Compositor split**
- **Cloud-only NPC dialog and memory** → **local-first SQLite + embedding-beside per player; central canon over the cycle**
- **UI-toggle privacy** → **diegetic in-between dimension with lifeforce-cost; clasp.sqlite as Ring A\* (physically non-syncable)**
- **Generic memory importance scalar + monolithic context** → **memory classes (cornerstone/birthright/working/volatile) + trait-graded importance + three-tier knowledge stack**
- **"Every NPC knows everything immediately"** → **paced canon-propagation as Marx-in-the-schema for epistemics**
- **Vertically-scaled monolithic AI-NPC backend** → **horizontally-scaled architecture (UID-keyed routing, stateless workers, ephemeral actors, sharded GMs, pruning at every layer)**
- **Manual outbox publisher services** → **pgnats-native transactional outbox (preferred); district-distribution fallback**
- **System-state hidden behind HUD spinners** → **diegetic relays making pulses visible and audible in-world**
- **Specific binary commitments embedded in architecture** → **role-based tier specification; binary selection deferred to findings/establishment phase**
- **Static designer-authored director toolkit** → **GM-granted typed-tool vocabulary per event-chain, drawn from designer-authored catalogue (catalogue growable between patches; toolkits are dynamic per event)**
- **Cross-NPC memory bleed at storage layer** → **per-player local SQLite isolation atop v0.5 lemniscate-geometry foreclosure (two-layer defense)**
- **Player input as freeform-prose-into-LLM** → designer-fixed corpus + player-curated trait-circle + universal-translator-as-typed-mapping (anti-hallucination at the player-LLM boundary)
- **"Accessibility mode" as degraded-fallback** → voice and gesture as first-class parallel modalities; non-speaking players use the gestural primary, not a lesser version
- **Continuous gesture-comparison touching the system bus** → lemniscate-bound recursive integration at axis-crossings (compute scales with slot-count, not gesture-rate)
- **Compositor as single-tier role** → Compositor as fractal/recursive across zone/district/world tiers, distinguished by UID-scope of the event-tree
- **World as cold-start at runtime-genesis** → world-server and district-server gen as init-function; runtime starts from rich pre-populated canon at every layer
- **NPC speech-patterns as static against player-state** → NPC speech-patterns dynamically modulated by accumulated player-NPC alignment-state via gesture-alignment-accumulator

## Open questions

### Resolved by v0.5 (or earlier)

- ~~Slot-capacity elasticity — can a zone grow slots dynamically~~ → fixed roundtrip slot-count; elasticity lives on entry/exit queues; tune dial is pulse-rate, not slot-count (v0.5)
- ~~Zone-to-zone handoff (walking out of conversation into brawl)~~ → exit-line of zone-A is entry-line of zone-B; interlemniscate-transit (v0.5)
- ~~Mobile zone boundaries (patrols, escorts, pursuits, migration-cohorts, exodus-flows)~~ → the lemniscate is a topology and translates through world-space invariantly (v0.5)
- ~~Anthropic-faction's broadcast cadence + arbitration weight~~ → cadence rides the same axis-rate as a phase-locked overlay; arbitration via rings-of-importance (v0.5)
- ~~Director/overseer spawn ownership per model class~~ → director (or overseer) owns spawn-decision via policy-lookup (no LLM); LLM lives only at driver-context-pull layer (v0.5)
- ~~Aletheia-progression as level-up — how does the game *recognize* an act-of-awakeness~~ → ternary trait-axis evaluation at event-end with named-axis; specific axis-mapping per Aletheia-event-class still open (v0.5; see new still-open below)
- ~~Reward function shape~~ → first-pass composite with explicit guardrails (still tuneable) (v0.4)
- ~~Zone spawn-cadence v1→v2 path~~ → lifeforce-gated rule-based v1; Dream-process-tuned v2 (v0.4)
- ~~Zone overlap policy~~ → no for active slots; yes for emergent-state accumulation (v0.4)
- ~~"How does GM cheating get caught"~~ → direct overseer-intelligence flow bypassing GM (v0.4)
- ~~"How does the regime have a finite endgame"~~ → imperial-budget insolvency-spiral (v0.4)
- ~~"Why does imperial-net exist"~~ → bypass-mechanism captures revenue directly (v0.4)
- ~~"How does the player learn 8 Hellenic traits"~~ → color-language pre-verbal vocabulary (v0.4)
- ~~"How does asset-economy fit a two-person-plus-Nyx team"~~ → base-limb palette + trait-texture; tools-not-quests (v0.4)
- ~~Director toolkit composition — designer-authored vs director-extensible~~ → GM-granted per event-chain from designer-authored catalogue; directors consume typed dispatch, not freeform; catalogue grows between patches, toolkits are dynamic per event (v0.6)
- ~~How does NPC dialog stay fresh during quiet periods~~ → three-tier knowledge stack (world / district / primary [+ clasp]) makes the layers deep enough that variation is structural; Compositor back-write continuously re-seeds canon; staleness foreclosed by loop's existence (v0.6)
- ~~How does the system scale to MMO size with AI-driven NPCs~~ → horizontal architecture (UID-keyed routing, stateless Compositors, ephemeral Director-routines, sharded GMs, pgnats transport, pruning at every layer) (v0.6)
- ~~How does privacy work in practice without cloud-routing-everything~~ → local-first SQLite per player; clasp.sqlite as Ring A* with no transport path; in-between as diegetic state with lifeforce-cost; "knowledge needs to travel" as foundational principle (v0.6)
- ~~Where does narrative composition happen — central or distributed~~ → Compositor as central role distinct from GM; perception-up via prune-blob, canon-down via back-write SQLite-fragments; cyclic forward-prop / back-write loop (v0.6)
- ~~How is system-state visible to the player without HUD~~ → diegetic relays mounted on buildings hum/glow/dim in patterns mapping to forward-prop, back-write, GM-dispatch, equilibrium-recompute (v0.6)

### Resolved by v0.8

- ~~LoRA-blend vs. single-LoRA-selection inference semantics~~ → single-LoRA-per-turn-selection driven by the player's `gesture_alignment_accumulator`: the dominant trait at each axis-crossing selects which trait-LoRA fires for the NPC's next-turn driver-context-pull. Personality emerges from selection-pattern across time, not from continuous blend at a moment. Driver-tier locked to Gemma 4 E4B (Apache 2.0, 4.5B effective, 128K context, speech-capable). v1 design item: hysteresis on selection to prevent personality-thrash. (v0.8; see `inference-and-memory/architecture.md` §LLM tiering)
- ~~LoRA rank selection — budget/quality~~ → resolvable against E4B benchmark; concrete benchmark task in command-center, no longer architecturally open (v0.8)
- ~~Sampling-knob heuristics — where to start; how to learn refinements~~ → resolvable against E4B benchmark; concrete benchmark task in command-center (v0.8)
- ~~The eighth Hellenic trait final enumeration~~ → 8 traits canonical: Sophrosyne, Dikaiosyne, Philotes, Mnemosyne, Aletheia, Kairos, Moira, Eros — mapped to the artist's 12-segment color wheel as 4 oppositional pairs at 180° (Eros↔Sophrosyne, Philotes↔Dikaiosyne, Aletheia↔Moira, Mnemosyne↔Kairos). Each trait carries a Greek canonical name + schoolchild-simple description + canonical wheel-position + motion-signature. Canonical reference: `style/trait-palette.md` (v0.8)
- ~~Player-dialog handling — player-trait-LoRA for style-coherence, or bypass LLM entirely~~ → no transform on player speech; the universal-translator's designer-fixed corpus already maps every word to a trait-coordinate, so the player's spoken dialog flows through STT → token-stream → per-token trait-coordinates → sum into the same `gesture_alignment_accumulator` as gesture-presses. **Voice and gesture are co-equal modalities feeding one alignment-mechanism.** No player-trait-LoRA needed; no LLM-bypass needed; the existing recursive-lemniscate handles it (per `runtime-engine/architecture.md` §Cross-context application — intimacy as recursive-lemniscate, generalized to all player-input). (v0.8)

### Resolved by v0.10

- ~~Cross-layer economy balancing — net-revenue-share back to producer-districts at all? Pure-zero is currently sketched~~ → bifurcation: *digital-T4 → imperial-net bypass (pure zero to district)*; *physical-T4 → district imperial-POI (district gets partial quota-credit; player gets scrip-cut; imperium captures most)*; *blackmarket-T4 → district-retained, imperium-zero*. **Pure-zero only applies to digital-T4.** (v0.10; see `political-register/architecture.md` §Imperial-extraction mechanisms (consolidated))
- ~~Inner-body projection function — trait-vector → body-rendering (learned / hand-authored / hybrid)~~ → gameplay-earned, not authored. Trait-vector accumulates from every zone-participation, every gesture, every memory across the playthrough; the eventual human-mesh projection becomes physically visible only at exit-chassis moment in in-between (v0.8 spec; v0.10 marks resolved; see `identity-and-personhood/architecture.md` §The clasp endgame Phase B-C)
- ~~Liminal-access trait thresholds — minimum traits to attempt mini-game~~ → **no trait-vector threshold**; clasp gates on the **relational ternary-gate (player, NPC) reaching OPEN state** (per §Ternary-gate substrate, Relational layer). Both partners must hit the coordinated-firewall-breach hardstop while the gate is OPEN. Trait-vectors don't need to converge — the gate measures what's been BUILT together, not who you ARE separately. Hysteresis is baked into the substrate; single dramas can't swing the gate; sustained alignment-pressure does. NPC personality-parameters set hysteresis-width per-NPC (some forgiving, some touchy). **Avoids the yes-men trap that trait-vector-threshold would create.** (v0.10)
- ~~Ring C (commons) ambient population — what NPCs do in commons when no event fires~~ → bifurcated economy answers it: NPCs work T1-T3 basic-flow vocations continuously at workshops/junkyards/drop-off-points; the simulation has economic-life independent of player-presence; *the world doesn't pause when the player leaves*. (v0.10; see `political-register/architecture.md` §Bifurcated economy — basic-flow (NPC) vs player-driven (T4))

### Resolved by v0.13

- ~~Character-editor pricing formula — trait-divergence cost scaling (linear / exponential)~~ → **narrowed to within-tier mod-pricing only**. Per [`identity-and-personhood/bodies.md`](./identity-and-personhood/bodies.md) §Sumptuary fabrication, **caste is born-into via fabrication-vat-class; no upward conversion; tier-jumping is impossible**. The character-editor doesn't price tier-jumping (it cannot exist); it prices *within-tier mod choices*. The "trait-divergence cost scaling" question is now bounded to within-caste mod-economics — much smaller surface, resolvable at implementation-time. (v0.13)

### Still open

- **Demand-arbitration algorithm v1 shape** (refined v0.10) — v1 candidate: *imperium-policy-driven scoring* (per §Three-tier policy loop's existing priority-weights mechanism; imperium broadcasts faction-priority-weights, GM applies them to incoming demand-broadcasts, sorts by weighted-score, processes top-down until lifeforce-budget exhausted). Concrete weights and refinements at implementation-time.
- **The mini-game mechanic for liminal-maintenance** (v0.5; refined v0.8) — exact gameplay action deferred pending design-research survey. Architecture commits to the role-contract (gates in-between entry; time-limited; lifeforce-cost; repeatable; muted-melancholic register; trait-circle-compatible; extensible to body-mod-progression Phase-B arc per `identity-and-personhood/architecture.md` §The clasp endgame); specific mechanic (juggling / rhythm / attention / gestural / decision-cascade / observation / hybrid) selected after surveying 20-year history of outstanding mini-interaction principles. **Same "by-role, binary-deferred" discipline as LLM tiering** — generalizes from sub-system selection to mini-game selection
- **Emergent-signal decay curves** (v0.5; refined v0.10) — per-signal-type, designer-tuned, refined via Dream-process feedback at implementation-time tuning. Architecture commits to the *shape* (per-signal designer-authored decay-config); implementation-time tunes the curves against actual gameplay data.
- **Cross-district migration topology** (v0.6; refined v0.10) — answer-in-conversation: dual-system of *official rail/metro* (cyclic, scheduled, district-director-managed; cargo + imperial troop patrols + standard daily traffic) + *hidden shadow-topology* (sewer-gates, air-ducts, random-time-gated; brave players time the floods/fan-cycles to traverse). Architecture not yet written; specific schema (rail-segment metadata extension + shadow-edge time-window data) pending. Pipe-capacity limits + cohort-traversal scheduling are the rail-side specifics; shadow-topology is parallel architecture.
- **Shader-trait modulation implementation** — performance + rendering-consistency. **(Sharpened v0.17:** cel-shading-everywhere with per-register parameter variation (per [`topology-and-rendering/architecture.md`](./topology-and-rendering/architecture.md) §Three-shader philosophy) caps the perf-budget more predictably than PBR (no GI-quality-knob to argue about); rendering-consistency improves (flat-color regions don't fight per-NPC color-modulation). Specific shader-stack budget per the rule-catalogue when authored.**)**
- **Service-body-of-the-dead consent model** (refined v0.10) — *fully-automatic harvest* implied by the existence of the **memory-pattern-extractor** vocation (the most reviled per `political-register/architecture.md` §The vocation-substrate of the imperial-net market). No consent gate; the regime extracts; necrocommerce is a structural feature of imperial extraction. Memorialist counter-archive partially preserves dignity by recording *who-was-harvested-when* into the true-ledger; resistance to necrocommerce is part of the Memorialist political project.
- **Character-editor pricing formula** — trait-divergence cost scaling (linear / exponential)
- **Imperium's Dream-process scope** — singular policy-learner or committee-of-faction-sub-learners?
- **GM's anti-imperial corruption detection mechanic** — *partial*: GM-as-equilibrium-seeker (v0.6) makes deviation-from-equilibrium the explicit error signal; clusters of -1 outcomes feed equilibrium-recompute and trigger catalogue-event dispatch to push back. A dedicated audit-vector for *which kind* of laxness/corruption is the source of the equilibrium-deviation is still an open detail. **(Sharpened v0.15:** cell-checksum-divergence is now a candidate audit-vector — corruption could surface as patterns of *authorized-vs-actual cell-state divergence* in a director's territory, per the cell-arch's heresy-detection mechanism in [`political-register/world-generation.md`](./political-register/world-generation.md) §L4 + §Open questions / cell-mutation write-permissions.**)**
- **Memorialist-archive accessibility to the player** (refined v0.10) — *via diegetic workstations* — memorialist-archive terminals (faction-controlled, hidden in Memorialist-faction territory; per the diegetic-console workstation pattern from `style/style-index.md` + `political-register/architecture.md` §Worked example — the service-body-modder imperial-workstation, applied to the Memorialist context). Specific terminal-types + permission-mechanisms + UI for querying the four-ledgers pending faction-authoring. **(Sharpened v0.15:** cell-checksum-divergence is now candidate source-data for the archive — Memorialists could index unauthorized cell-states (heretical wheels carved in stepwell-walls, un-synced relics) by querying checksum-divergence-records. Doesn't solve UI/permissions but gives the archive concrete *content* to query.**)**
- **Imperial-net distortion algorithm** — how exactly the net rewrites trait-colors toward consumer-palette
- **Trait-axis mapping per fuzzy-goal-class** (v0.5) — which axis (Sophrosyne / Philotes / Eros / etc.) evaluates which goal-class? Need a designer-authored compile-table from goal-shapes to trait-axes
- **Rings-of-importance movement criteria** (v0.5) — explicit thresholds (N consecutive +1 → climb) or Dream-process-learned policy?
- **Rings-of-importance scope** (v0.5) — district-local rings, or imperium-global? Probably both, layered (district rings nested inside imperium rings)
- **Symmetric-vs-polyphonic loops** (v0.5) — Loop A and Loop B treated identically (simpler), or carry foreground/background semantics (foreground-speaker / listening-co-presence — gives audience-dynamics for free)?
- **Verifier-flag conflict resolution** (v0.5) — if `priority_pull` and `mid_action` are both set on the same token at crossing-time, which wins? Default: priority_pull wins (the zone's drama is overridden by world-level pull)
- **Goal-evaluation cadence** (v0.5) — every crossing? Every Nth crossing? On-demand by spawning director? Cheaper to evaluate less often; richer drama if every crossing
- **Cycle cadence** (v0.6) — when does the Compositor pull from transient-waiting-flag? Real-time? Per-event-end? Fixed interval (every N min)? Per-district-day? Different per district based on event-density? Likely configurable per event-class.
- **Compositor singleton vs sharded** (v0.6) — one Compositor for the whole world, one per district, one per event-cluster, or one per faction? Each topology has different consistency / cost / coherence tradeoffs.
- **Multi-GM consensus on equilibrium** (v0.6) — when GM-shards observe overlapping aggregates, how do they agree on equilibrium? Paxos/Raft for strong consistency, CRDT for eventual, faction-sharding so shards own non-overlapping equilibria, or hybrid?
- **Event causality across shards** (v0.6) — if Director-A spawns an event that depends on Director-B's prior event in another district, UIDs alone don't enforce ordering. Vector clocks at event-register? Causal hashing? Shard-pinning of related events?
- **Compositor narrative-coherence at scale** (v0.6) — when two Compositors compose canon for overlapping player-sets, how do they avoid contradicting each other? Sticky routing per player (one Compositor per player at a time), or read-replica of recent canon before composing, or post-compose conflict-detection-and-merge?
- **Propagation-pacing policy specifics** (v0.6) — concrete rate/scope/ttl/priority defaults per event-class; how is "distance" measured between districts (graph-hops, lifeforce-similarity, faction-affinity)?
- **In-between fiction-wrapping** (v0.6) — what diegetic events / locations / rituals make in-between affordable enough to be playable? Campfire / sanctuary / time-of-day / specific chambers / shared dream-construct? The mechanic is solved; the fiction-wrapping shapes how players approach it.
- **Relay-pulse-pattern vocabulary** (v0.6) — what specific patterns signal what events? Slow pulse vs fast vs irregular vs cross-district shimmer vs going-dark; player-readable language to be designed.
- **Encryption-at-rest for clasp.sqlite** (v0.6) — player-derived key with passphrase + recovery-codes? Drive-imaging-resistant by default, with affordances for player-key-loss recovery without compromising the privacy-guarantee.
- **pgnats-vs-district-distribution decision criteria** (v0.6) — concrete go/no-go thresholds from evaluation: minimum throughput, durability behavior under broker failure, schema-evolution behavior, replay semantics. Output of the load-bearing pgnats evaluation task.
- **JetStream republish + replay as pull-from-checkpoint refinement** (v0.6) — does republish-rule expressiveness cover our UID-hierarchy fan-out? Does replay performance work for N-hour reconnect-catchup? Is per-active-player durable-consumer cost (disk/memory/file-handles) acceptable at MMO scale? If yes, back-write delivery becomes config-driven NATS, not Go.
- **Memory class assignment policy** (v0.6) — automatic from trait-engagement profile, designer-tagged categories per event-class, player-marked, or hybrid? When does a working-memory entry get *promoted* to cornerstone vs decay normally?
- **Trajectory-aware gesture-alignment reduction** (v0.7) — sum-strategy is v1 default; trajectory-aware (where the *path* through trait-space carries weight beyond the integral) is a v2 refinement. Does the Dream-process at the trait-LoRA tier learn trajectory-sensitivity, or is it explicit reward-function tuning?
- **NPC spectator drivers — whose hardware?** (v0.7) — when a player is co-located with N NPCs, the player's local LLM presumably drives those NPCs. With M players and N NPCs in a single zone (asymmetric), who drives the surplus? Round-robin? Closest-player? District-owned-default? And what's the failover behavior if a driving-player disconnects mid-event?
- **Trait-summary schema specifics** (v0.7) — likely an 8-float trait-vector per-participant per-event-collapse, but the exact representation (continuous `[-1.0, +1.0]` ternarized at threshold? Discrete `+1/0/-1`? Magnitude vs. signed?) needs landing for the Compositor's deterministic pickup at all three tiers.
- **Profile-switch as meta-gesture** (v0.7) — what's the gesture-shape that switches profiles? Hardstop (cannot be remapped)? Designed-by-player like other gestures? And how is profile-switch witnessable by NPCs ("they just switched registers") — or is it player-private?
- **Hardstop set finalization** (v0.7) — the v0.1 design-vision (retired in v0.9; preserved in git history) sketched ~12 candidate hardstops; the architecture commitment is "~8-16 reserved." Final set needs designer-decision: which signals make the cut, the visual-distinct-marker per-hardstop, and whether the claim-floor hardstop is genuinely a hardstop or emerges from a different mechanism.
- **World-gen version migration semantics** (v0.7) — when world-gen v2 retroactively changes lore, gen-rows from v1 coexist with v2; how does the Compositor reconcile if a runtime back-write references something that v2's gen has overwritten? Probably explicit migration operations, but worth designing. **(Sharpened v0.15:** L0–L4 cascade per [`political-register/world-generation.md`](./political-register/world-generation.md) is now the *version-axis* — migration can be spec'd per-layer (L0 demand-set migration vs. L1 district-allocation migration vs. ... vs. L4 cell-content migration). Each layer gets its own version-and-migration discipline. Still open but vastly more structured.**)**
- **Cross-context consistency of the trait-circle** (v0.7) — the v0.1 design-vision (retired in v0.9) committed to "*same gesture-skill for dialog, combat, intimacy, maintenance, ritual*"; v0.7 specified the dialog-context (lemniscate-injection mechanic) and v0.8 specified the intimate-gameplay-context. Whether combat / maintenance / ritual all run through the same circle is currently held as open scope.
- **Continuous visual feedback policy** (v0.7) — exact rules for when NPC body-shader pulses (every gesture? threshold-only? trait-aligned-only? all gestures with intensity-modulated color?) and how this interacts with the audit-overseer's surveillance read of the same body-rendering. **(Sharpened v0.17:** with cel-shaded bodies (per [`topology-and-rendering/architecture.md`](./topology-and-rendering/architecture.md) §Three-shader philosophy) and visual-as-ephemeral-flag (per [`runtime-engine/architecture.md`](./runtime-engine/architecture.md) §Omnisight hallucination-isolation discipline), the body-shader pulses are *legible without canon-pollution risk*. The visual-feedback policy can be permissive at the cosmetic layer because it is firewalled from canonical state; audit-overseer-read goes through the same omnisight pipeline (visual-context flag, ignored in summary).**)**
- **Imperial calibration-signature retention post-defection** (v0.18) — does the imperium retain a re-vat'd defector's pre-defection gesture-mapping calibration-signature (per [`identity-and-personhood/architecture.md`](./identity-and-personhood/architecture.md) §The clasp endgame, *"the integrated calibration-signature is preserved across body-deaths in consciousness-archive"*) as a permanent search-key? **Yes-answer**: re-vat is *plausible-deniability cover* lasting only as long as imperial inattention; the clasp-pair lives in *passing*, knowing the imperium could find them anytime if it chose to look hard enough — *love-in-exile-while-pretending-to-be-home*. **No-answer**: they actually fully escape once assembled, which would be a major cosmological concession to the no-haven discipline. The yes-answer is more dramatically generative AND no-haven-discipline-consistent. Architecturally relevant because it determines whether the consciousness-archive has a *separate search-index* by calibration-signature beyond its existing role as continuity-store.

---

 **Version:** 0.19 | **Created:** 2026-04-24 | **Updated:** 2026-04-27