# V7 Architecture — Mawu: The Open World & Creator Republic

Status: V7 technical architecture Source: derived from `V7/V7_features.md` (the
product spec) and the `V7/V7_GAP_ANALYSIS.md` SOTA research, cross-referenced
against the reusable substrates in V1/V3/V5/V6 and the Maya engine domain. This
document carries the **technical design**: protocols, data models, numeric
budgets, the trust model, and the concrete reuse sites. `V7_features.md` carries
product behavior; `V7_TODOS.md` carries the execution backlog;
`V7_DEPENDENCIES.md` carries the build-order graph. Date derived: 2026-05-30

> **This architecture reference has been decomposed into focused pages under
> [`architecture/`](./architecture/README.md).** This file remains the canonical
> hub (every section heading is preserved, so existing `arch§"…"` anchors keep
> resolving); the in-depth, code-grounded companion pages live under
> [`architecture/`](./architecture/README.md). Start at the
> [architecture page index](./architecture/README.md). The product feature map
> is in [`V7_features.md`](./V7_features.md) /
> [`features/`](./features/README.md).

## Cross-Reference Convention

- `§N` → `V7_TODOS.md` §N. `features§"<anchor>"` → `V7_features.md`.
- `arch§"<anchor>"` → this document. `deps§N` → `V7_DEPENDENCIES.md`.
- `maya§"<anchor>"` → `DOMAINS/maya/features.md`.
- `v5arch§`, `v6arch§`, `v3arch§` → the respective architecture docs.
- Concrete reuse paths are given as repo-relative `libs/...` / `apps/...`.

## Table of Contents

- [Architectural Thesis](#architectural-thesis)
- [The Trust Boundary — Platform vs. Realm](#the-trust-boundary--platform-vs-realm)
- [High-Level Topology](#high-level-topology)
- [The Substrates V7 Reuses](#the-substrates-v7-reuses)
- [Project Layout](#project-layout)
- [Determinism — The Cross-Cutting Invariant](#determinism--the-cross-cutting-invariant)
- [Moremi — Realm Server Architecture](#moremi--realm-server-architecture)
- [Netcode and Replication](#netcode-and-replication)
- [Danu — Server Meshing](#danu--server-meshing)
- [Nephthys — Persistence and the Replication Layer](#nephthys--persistence-and-the-replication-layer)
- [Ixchel — The Modding Runtime](#ixchel--the-modding-runtime)
- [The WASM Sandbox](#the-wasm-sandbox)
- [Dependency Resolution and Content-Addressed Storage](#dependency-resolution-and-content-addressed-storage)
- [Nàná — Character and Economy Data Model](#nàná--character-and-economy-data-model)
- [Pheme — Voice Architecture](#pheme--voice-architecture)
- [Hera — Social Graph Data Model](#hera--social-graph-data-model)
- [Hosting, Orchestration, and the Realm Fleet](#hosting-orchestration-and-the-realm-fleet)
- [Abundantia — Distribution and Payout Architecture](#abundantia--distribution-and-payout-architecture)
- [The Economy Firewall and Anti-Fraud](#the-economy-firewall-and-anti-fraud)
- [Sekhmet — Trust, Safety, and Child-Protection Architecture](#sekhmet--trust-safety-and-child-protection-architecture)
- [Anti-Cheat and Client Integrity](#anti-cheat-and-client-integrity)
- [Eunomia — Governance Data Model](#eunomia--governance-data-model)
- [Cross-Version Bridge (Ori Passport)](#cross-version-bridge-ori-passport)
- [Data Architecture, Residency, and Compliance](#data-architecture-residency-and-compliance)
- [Observability and Live Operations](#observability-and-live-operations)
- [Performance Budgets](#performance-budgets)
- [Build, Cook, Patch, and Cert](#build-cook-patch-and-cert)
- [Testing, Eval Gates, and Golden Replays](#testing-eval-gates-and-golden-replays)
- [Launch Readiness](#launch-readiness)

## Architectural Thesis

The entire architecture follows from one decision: **who runs the authoritative
server.** The two reference points sit at opposite ends — FiveM
(community-hosted; operators control the server, so identity/economy/safety
cannot be trusted to it) and Roblox (platform-hosted; the platform runs every
server, eliminating the operator-trust problem but owning all compute cost). V7
takes the **defensible hybrid**:

- **Platform-hosted, inviolable central services** for identity, the real-money
  economy and payouts, client integrity, child-safety, and cross-realm
  ban/reputation.
- **Community-hosted realm logic only**, and only as **capability-sandboxed
  WASM** (never raw native code), behind a **hardened, attested client** the
  operator cannot patch.

Three invariants bind the rest of the system and must be designed in at the
core, not retrofitted:

1. **The trust boundary** (arch§"The Trust Boundary — Platform vs. Realm") —
   certain things are never delegated to a realm.
2. **Determinism** (arch§"Determinism — The Cross-Cutting Invariant") — rollback
   netcode, atomic authority handoff with replay-based crash recovery, and
   replayable creator plugins all require a deterministic simulation core. Lock
   it down once at the engine core and every other system inherits it.
3. **Server-authoritative-by-default** — clients send intent, the realm decides,
   the platform owns truth above the realm.

## The Trust Boundary — Platform vs. Realm

This is the most important table in the document. A community realm operator is
**assumed potentially hostile** (data theft, RCE attempts on players via
malicious resources, currency/cosmetic theft, ban evasion, PII/voice
harvesting). The FiveM threat model is explicit: a malicious _resource_ on the
server host has near-total power over that host, and the highest-risk channel to
the _client_ is server-pushed UI/script. V7's boundary:

| Concern                                                                                              | Owner        | Why never delegated                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Platform identity / authentication**                                                               | **Platform** | One platform account; realms receive only an opaque, per-realm pseudonymous handle. Identity-spoofing and realm-hopping ban evasion are defeated only by platform-owned identity + device attestation. |
| **Real-money economy, entitlements, payouts**                                                        | **Platform** | Purchases, cosmetic ownership, currency conversion, creator payouts settle through Aje, never touch a realm process.                                                                                   |
| **Client integrity / anti-tamper**                                                                   | **Platform** | Operators never ship or patch the client binary; the client is signed and attested (Roblox-Hyperion precedent).                                                                                        |
| **Child-safety, CSAM/grooming, age assurance**                                                       | **Platform** | Central scanning, age estimation, voice screening; an operator must never run the age check or be the CSAM-scanning authority.                                                                         |
| **Cross-realm ban / reputation**                                                                     | **Platform** | A ban must follow the player across realms; Themis/Kuanyin issue platform bans.                                                                                                                        |
| **Asset malware scanning**                                                                           | **Platform** | Every uploaded artifact is platform-scanned before any client can fetch it; realms never serve unscanned binaries.                                                                                     |
| **Realm-local gameplay state** (RP inventory, vehicles, jobs, world objects, in-realm play-currency) | **Realm**    | Safe to delegate — but **non-fungible** with platform currency (arch§"The Economy Firewall and Anti-Fraud").                                                                                           |
| **Realm rules, scripts, content, moderation-above-floor**                                            | **Realm**    | Sovereign within the platform safety floor; runs only in the Ixchel sandbox.                                                                                                                           |

**What a malicious realm can attempt, and the mitigation:** push hostile
script/UI to clients → contained by the WASM sandbox (no FS/socket/process) and
a locked-down web view for any creator UI (HTTPS-only secure context, strict
CSP, no platform session tokens ever exposed to that context); forge
client→server events → every cross-trust message is authenticated and
server-validated, defaulting to "assume hostile sender"; harvest PII/voice →
voice and chat safety run platform-side, never realm-delegated; steal
currency/cosmetics → those live in Aje behind the trust boundary, not in realm
state.

## High-Level Topology

```
                          ┌──────────────────────────── PLATFORM PLANE (inviolable) ──────────────────────────┐
   Mawu client (UE5.5 /   │  Identity/Auth (V1)   Aje economy+payouts   Sekhmet safety   Abundantia catalog   │
   Maya) — attested,      │  Kuanyin moderation   Themis adjudication   Eunomia gov       Ori service (V6)     │
   sandboxed web view ────┼──────────────────────────────────────────────────────────────────────────────────┘
        │  (intent)        │
        ▼                  ▼
   Mawu Gateway (V6 Egbe-Gateway fleet) ── WebTransport/WebRTC/WS + Pheme voice SFU
        │  realm session routing, interest-managed delta stream
        ▼
   ┌──────────────── REALM PLANE (sandboxed, community- or platform-hosted) ───────────────┐
   │  Moremi realm server (Rust) ── authoritative sim, Ixchel WASM resource host           │
   │        │ authority leases                                                              │
   │  Danu mesh cluster ── spatial partition, atomic authority handoff, dynamic split/merge │
   │        │ read/write entity views                                                       │
   │  Nephthys replication/persistence layer ── decoupled source of truth, crash recovery   │
   └────────────────────────────────────────────────────────────────────────────────────────┘
```

The platform plane is the same multi-region Kubernetes the prior versions use;
the realm plane is orchestrated on Agones (arch§"Hosting, Orchestration, and the
Realm Fleet"). The gateway is the only ingress from clients to realms, so it is
also the enforcement point for interest management, rate limiting, and DDoS
scrubbing.

## The Substrates V7 Reuses

V7 is mostly integration. Concrete reuse sites (real code unless marked
planned):

| Capability                                                             | Reuse from      | Path                                                                       | Surface V7 consumes                                                          |
| ---------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Realtime gateway + voice SFU                                           | V6              | `apps/v6/egbe-realtime-gateway/`, `libs/v6/egbe-protocol/`                 | WebTransport primary / WebRTC fallback, voice media mix, snapshot/delta wire |
| Authoritative world-server pattern                                     | V6 (extends V3) | `apps/v6/egbe-world-server/`                                               | room/shard state, tick loop, action validation, durable flush                |
| Portable identity + passport                                           | V6              | `libs/v6/ori-model/`, `libs/v6/aye-bridge/`, `apps/v6/egbe-ori-service/`   | event-sourced biography, passport mint, incarnation journal                  |
| Multiplayer protocol / interest mgmt                                   | V3              | `libs/v3/multiplayer-protocol/`                                            | snapshot/delta encoding, interest management                                 |
| Spatial audio                                                          | V3              | `libs/v3/spatial-audio/`                                                   | HRTF / ambisonic per platform (extended to proximity by Pheme)               |
| Avatar pipeline                                                        | V3              | `libs/v3/avatar-pipeline/`                                                 | VRM 1.0 + MetaHuman bind, retarget                                           |
| Online services backbone                                               | V5              | `apps/v5/` (16 apps)                                                       | login, friends, parties, matchmaking, leaderboards, replays, telemetry, DSAR |
| Anti-cheat (EAC + ML)                                                  | V5              | `apps/v5/` + `libs/nous/`                                                  | kernel EAC + server-side ML classifier + 3-strike                            |
| Workshop/moderation pipeline                                           | V5              | `apps/v5/` workshop                                                        | upload → ML pre-screen → human review → publish                              |
| Engine core (ECS, streaming, physics)                                  | Maya            | `libs/maya/engine-core/`, `libs/maya/{physics,renderer,scene,server}/`     | **real code**; ECS, world partition, physics                                 |
| Modding framework `forge-*`                                            | Maya            | `DOMAINS/maya/` spec                                                       | **planned, no code** — V7/Ixchel implements it (§9–§10, §15)                 |
| Identity/auth, contracts, persistence, events, queue, residency, audit | V1              | `libs/oshun/`, `libs/shared/`                                              | RBAC+JWT, Zod/OpenAPI codegen, Prisma, event-bus, queue, residency, audit    |
| Generation/safety/grounding/memory                                     | V1              | `libs/isis/`, `libs/lilith/`, `libs/sophia/`, `libs/iris/`, `libs/psyche/` | governed gen, persona/welfare policy, grounding, memory, dialogue runtime    |
| Commerce / media / adjudication                                        | V1              | `libs/aje/`, `libs/yemaya/`, `libs/themis/`                                | payouts/royalties, offline render, dispute resolution                        |

Maya note: the Maya **engine-core/physics/renderer/scene/server/genesis-\*** are
**real code**; the `forge-*` modding family is **spec-only**. V7 continues on
the UE5.5 LTS / Maya client path (per V3–V6) and **implements** the `forge-*`
family as the Ixchel runtime under `libs/maya/forge-*` (deps§"Ixchel").

## Project Layout

```
V7/ue/                          # UE5.5 LTS / Maya client (Mawu) — single project
  Source/MawuCore               # game instance, save, account bridge, attestation hooks
  Source/MawuRealm              # client-side realm model, interest-set apply, prediction
  Source/MawuBuilder            # in-realm builder (VR + desktop), gizmo, CSG
  Source/MawuVoice              # Pheme client: capture, positional mix, radio UI
  Source/MawuUI                 # browser, character mgmt, Hera console, governance UI
  Plugins/MawuMode_*            # Solo / Listen / Dedicated / Meshed mode gating
apps/v7/
  moremi-realm-server/          # Rust + tokio + QUIC — authoritative sim + Ixchel host
  danu-mesh-cluster/            # Rust — partition, authority handoff, split/merge
  nephthys-replica-service/     # Rust — decoupled state store, crash recovery
  mawu-gateway/                 # extends apps/v6/egbe-realtime-gateway — + Pheme positional
  sekhmet-scanner/              # Rust — static/dynamic scan, hash-match, integrity
  abundantia-market-service/    # TS/NestJS — catalog, browser, Collections, payouts
  eunomia-governance-service/   # TS/NestJS — proposals, voting, execution
  hera-social-service/          # Rust — crews/guilds, treasuries, reputation
libs/v7/
  nana/                         # TS + Rust — characters, jobs, economy, property, institutions
  realm-protocol/               # wire schema extensions over egbe-protocol
libs/maya/
  forge-resolver/  forge-conflict/  forge-sandbox/  forge-compositor/   # Ixchel (Rust + WASM)
```

## Determinism — The Cross-Cutting Invariant

Rollback prediction (netcode), replay-based crash recovery (mesh), and
replayable creator plugins (Ixchel) all demand a deterministic simulation core.
The determinism contract:

- **Fixed-timestep simulation** on the authoritative node; gameplay logic never
  reads wall-clock or un-seeded RNG. PRNG is explicitly seeded per realm and per
  tick (the V5 netcode PRNG-seeding pattern,
  `v5arch§"Combat Authority & Determinism"`).
- **WASM determinism controls** for all gameplay-affecting plugins: NaN
  canonicalization (Cranelift `cranelift_nan_canonicalization`), relaxed-SIMD
  disabled or deterministic, no shared-memory threads, `memory.grow`
  pre-allocated to max or rejected, all host imports deterministic
  (virtualized), and **fuel** (instruction-counted) interruption — not epoch —
  so a plugin traps at the exact same instruction every replay. (Wasm 3.0's
  deterministic profile is the standard.)
- **Determinism is tiered:** only gameplay-state-affecting code runs under the
  full deterministic profile (fuel + canonicalization). Cosmetic/UI scripts run
  under the cheaper epoch metering.
- **Golden replays** (arch§"Testing, Eval Gates, and Golden Replays") are the CI
  guard: a recorded input log must reproduce the exact authoritative state hash.

## Moremi — Realm Server Architecture

A realm server is a Rust process (`apps/v7/moremi-realm-server/`) extending the
V6 `egbe-world-server` pattern. It owns: the fixed-timestep authoritative sim
loop, the Ixchel WASM resource host, interest-set computation, action validation
against realm rules + Nephthys, and durable flush.

**The resource model.** Behavior is built from **resources** (the FiveM unit,
hardened): a resource is an Ixchel layer bundling assets + data + WASM scripts,
declaring deps, the required sandbox tier, and exported events/callbacks. The
reference RP framework (the Nàná core) is itself a resource exposing
inventory/job/economy/target primitives; content resources depend on it.
Resources hot-load/unload via the Ixchel lifecycle manager without restarting
the realm.

**Authority.** All gameplay state is server-owned. The validation rule: a
client-originated event can never mutate authoritative state without server-side
validation; cross-trust messages are authenticated (security-token pattern) and
default to "assume hostile sender." Money, items, and position are server-owned
— a tampered client cannot grant itself any of them.

**Tick tiers.** Combat/instanced zones run at **60 Hz** (16 ms); persistent
open-world zones at **10–30 Hz** with interest-managed per-entity update rates.
The server processes queued intents, steps the deterministic sim once, evaluates
rules, and emits per-client deltas each tick.

## Netcode and Replication

The client↔realm contract is **server-authoritative with client-side
prediction + reconciliation**, reusing the V3 `multiplayer-protocol` and the V5
netcode patterns, with these concrete parameters:

- **Prediction + reconciliation (Gambetta/Overwatch model).** Every client input
  carries a monotonic sequence number; the client predicts immediately; the
  server replies with the last-processed sequence number; the client snaps to
  authoritative state and **re-applies all unacknowledged inputs**. On
  misprediction, roll back to the server snapshot and replay buffered inputs to
  "now." Predict-by-default with explicit per-ability opt-out.
- **Snapshot interpolation.** Interp buffer =
  `max(2× send-interval, jitter-adaptive)`; starting point ~100 ms (Valve
  default), i.e. ~85 ms at 60 Hz, ~150 ms at 30 Hz, ~350 ms at 10 Hz. Position
  via Hermite splines (uses velocity), orientation via SLERP.
- **Delta compression (Quake 3 model).** Per-client 32-snapshot ring; each
  update is delta-encoded **against the last snapshot the client acknowledged**,
  1-bit changed/unchanged per field, entropy-coded; pre-fragment at **1400
  bytes** (under 1500 MTU). Only interest-set entities are sent, so per-client
  bandwidth is independent of total realm population.
- **Lag compensation.** Rewind window = `RTT/2 + client-interp`; store ~1 s
  position history per entity; cap the rewind window (~200–250 ms) beyond which
  the server stops favoring the shooter and switches to extrapolation.
- **Bandwidth budgets.** Per-client downstream target **64–256 kbit/s** in open
  world, up to ~1 Mbit/s in dense combat — interest-managed so bandwidth scales
  with _visible_ density, not world population. Adaptive jitter buffer with
  input-buffer time-dilation on starvation.

## Danu — Server Meshing

Danu makes many sim nodes one seamless world. Architecture follows the Star
Citizen replication-layer lesson and the SpatialOS failure lesson:

- **Single authoritative writer per entity.** Exactly one sim node holds write
  authority over a given entity (first-come allocation); all other nodes hold a
  **read-only view** sourced from Nephthys. This yields strong per-entity
  consistency and eventual consistency across views.
- **Atomic authority handoff (2-phase).** At a partition boundary: source node
  **freezes** the entity → **transfers** state through Nephthys → destination
  **acks** and assumes authority → source **releases**. The failure window (node
  dies mid-handoff) is an explicit test target — there must be no window with
  two writers or zero owners. The client never reconnects across a handoff.
- **Co-location constraint (the SpatialOS lesson).** Entities that physically
  interact at high frequency must live on the **same node**. Danu partitions by
  spatial cell/district/logical-shard and keeps an interaction's participants
  co-located; it never splits tightly-coupled physics across nodes (that path is
  what made SpatialOS/Worlds Adrift fail to O(n²) cross-worker traffic).
- **Interest management.** Grid-based area-of-interest: a client/node subscribes
  only to entities in its AoI cells; cross-node RPC routes through Nephthys by
  entity-of-interest set. AoI radii are per-zone-type (dense urban small, open
  world large), following the V5 pattern (`v5arch§"Client-Server Netcode"`).
- **Dynamic split/merge.** When density at a location crosses a threshold, Danu
  splits the region onto a new node and spins it up; on disperse, merges back.
  **Static meshing ships before dynamic** (the SC sequencing lesson — authority
  transfer is the hard part; prove it static-first).
- **Overload valve = time dilation, not authority drop.** When a node cannot
  simulate a hot region in real time, it slows that region's clock (EVE TiDi
  model, floor 10% real-time) rather than dropping authority or disconnecting
  players.

## Nephthys — Persistence and the Replication Layer

Nephthys is the **decoupled source of truth**, separate from the sim nodes
(`apps/v7/nephthys-replica-service/`, Rust). It is both the replication layer
(brokers entity read/write views between mesh nodes) and the durable store.
Design:

- **Event-sourced + snapshot-checkpointed**, consistent with the V6 Ori model
  (`libs/v6/ori-model/`): realm and character state are an append-only event log
  with periodic projections. A sim-node crash loses nothing — a replacement
  rehydrates from Nephthys and the mesh re-leases authority.
- **Schema:** per-realm state (world mutations, economy ledger, property,
  vehicles) and per-character state (Nàná records) are separate aggregates with
  independent projections, so a character can travel a federation corridor
  carrying only its own aggregate.
- **Residency.** State is tagged with region under
  `libs/shared/data-residency/`; federation corridors honor cross-region travel
  rules.

## Ixchel — The Modding Runtime

Ixchel implements the Maya `forge-*` family (planned, no code) as the V7 modding
runtime. Four components under `libs/maya/forge-*`:

- **`forge-resolver`** — dependency resolution (arch§"Dependency Resolution and
  Content-Addressed Storage").
- **`forge-conflict`** — semantic conflict resolution: rules compose
  algebraically (additive/multiplicative/min-max), world mods partition space,
  code mods order hooks with disjoint-state detection, audio mods get
  independent buses. Only true contradictions surface — to Eunomia, never a
  load-order tweak.
- **`forge-sandbox`** — the WASM sandbox (arch§"The WASM Sandbox").
- **`forge-compositor`** — applies layers in fixed priority (Engine < BaseGame <
  ContentPack < ServerRealm < CommunityVariant < PersonalOverride) with
  per-field provenance. The composed result is pinned by the realm lock file.

Genomes (`Loom`), forking (`Variants`), and AI balance verification (`Crucible`)
are Ixchel capabilities built on the same substrate (§15).

## The WASM Sandbox

The security keystone — what lets V7 run untrusted creator code (lifting V5's
data-only limit). Built on **Wasmtime**:

- **Capability-typed host interface** via the Component Model + WIT: the host
  API is a WIT world; a plugin receives only the imports its tier and manifest
  grant — no ambient authority, no filesystem/socket/process access unless
  explicitly granted. This is the UEFN-Verse "no FS/sockets/system resources"
  guarantee made language-agnostic.
- **CPU budgeting:** **fuel** (deterministic, instruction-counted) for
  gameplay/rollback-critical plugins; **epoch** (≈2–3× faster,
  non-deterministic) for cosmetic/UI work. Budget N fuel units per tick per
  plugin; overrun → throttle + flag, never hang the realm.
- **Memory/stack limits** via `StoreLimits`: per-plugin linear-memory cap, stack
  cap, guard pages for bounds-check elimination, async-stack zeroing to prevent
  cross-instance data leaks.
- **Six tiers** (features§"The Six Sandbox Tiers"): DataOnly, Scripted,
  Extended, System, Native, Trusted. Community uploads default
  Scripted/Extended; System for trusted realm-framework authors; Native/Trusted
  are review+signature gated.
- **AOT at upload:** vetted plugins are AOT-compiled at upload time to `.cwasm`;
  production runs with the JIT compiler disabled (`enable_compiler(false)`) for
  speed and reduced attack surface.
- **Hardening borrowed from Luau:** freeze host globals/metatables (read-only),
  a per-plugin environment table, an interrupt callback guaranteed to fire for
  CPU termination, no bytecode loading from untrusted sources.
- **Determinism controls** as in arch§"Determinism" for any plugin in the
  deterministic tier.
- **Audit log:** every host-API call is recorded with plugin attribution for
  debugging + abuse detection; a faulting plugin is isolated and disabled
  without crashing the session.

## Dependency Resolution and Content-Addressed Storage

- **Resolution: PubGrub.** `forge-resolver` uses a PubGrub (CDCL-for-versions)
  solver (`pubgrub-rs`) over SemVer ranges with optional deps, feature gates,
  and capability alternatives. On conflict it produces a plain-English
  root-cause explanation (the PubGrub incompatibility DAG), not a silent
  failure. The solution is frozen to a **lock file** (Cargo-lock model) the
  realm pins.
- **Storage: content-addressed (Nix model).** Every mod artifact's id is the
  cryptographic hash of `(content + full dependency closure)`. This gives, for
  free: deduplication, tamper-evidence (a swapped dependency changes the hash),
  atomic install/rollback (old paths persist), and side-by-side versions. The
  lock file pins exact content hashes — which is also the Sekhmet supply-chain
  integrity primitive (arch§"Sekhmet") and the AOT `.cwasm` cache key.

## Nàná — Character and Economy Data Model

A character is an **Ori record** (`libs/v6/ori-model/`) extended with roleplay
aggregates, persisted in Nephthys:

```
Character { ori_id, realm_id, legal_name, aliases[], appearance_ref,
            licenses[], employment{job_id, grade}, property[], vehicles[],
            inventory[], balances{cash, bank, society},
            record{criminal[], medical[]}, relationships[] (realm-scoped) }
```

- **Economy** is a realm-scoped, server-authoritative, double-entry ledger:
  payroll, taxes, fines, business revenue settle through it; the realm owner
  tunes faucets and sinks. Built-in sink primitives (repair/degradation,
  property upkeep, transaction tax, service fees) ship so a realm can't
  accidentally build a sink-less hyperinflationary economy; an optional
  auto-balancer adjusts faucet/sink rates against a target inflation band (the
  Alter Aeon dynamic-control model). Inflation rate, sink coverage, and wealth
  inequality are first-class per-realm health metrics.
- **Deletion limits** via Iris (`libs/oshun/memory-iris/`): a realm owner cannot
  silently erase a character record; deletion follows consent + the V6
  steward-not-owner posture.
- **Federation corridor:** a character crosses realms carrying only a
  realm-negotiated subset of its aggregate, under Themis-adjudicated treaty.

## Pheme — Voice Architecture

Pheme extends the V6 Egbe-Gateway voice SFU with positional mixing:

- **Codec/transport:** Opus over WebRTC (gateway SFU). Per-client voice
  bandwidth budgeted separately from state bandwidth.
- **Proximity mix:** the realm server computes per-listener gain from
  speaker-listener distance (scriptable whisper/normal/shout ranges) +
  occlusion, and instructs the SFU mix; only in-range speakers are mixed to a
  listener.
- **Radio channels:** job/role-gated multi-channel nets with PTT and squelch,
  independent of proximity; **phone** is point-to-point/conference, also
  proximity-independent.
- **Safety:** all voice is platform-monitored for child-safety (arch§"Sekhmet" —
  AI voice screening), never realm-delegated; captions + speaker/ range/channel
  visual indicators for accessibility parity.
- **Scale budget (adopted 2026-06-12):** server-side proximity mixing is
  bounded, not population-proportional — **≤40 audible streams per listener**
  after AoI culling (nearest-N by computed gain, then truncation); **mixing CPU
  budget ≤2 cores per 256 concurrent speakers per realm node**; radio and phone
  channels add **≤8 streams per listener** on top of the proximity mix; **p95
  mouth-to-ear latency ≤250 ms** at 1,000-inhabitant realm scale. These budgets
  gate the Danu 1000+ population target — voice must not be the first system to
  saturate a hot region.

## Hera — Social Graph Data Model

```
Group { id, kind(crew|guild|gang|org), roles[{role, perms[]}],
        members[{ori_id, role}], treasury(aje_account), shared_assets[],
        reputation{cross_realm_score, history[]}, governance_charter_ref }
```

Treasury is an Aje-backed account with role-gated access and an audit ledger;
reputation is readable at another realm's whitelist gate; a group travels into
V2–V6 via the Ori passport. A group is a per-guild governance tier in Eunomia.

## Hosting, Orchestration, and the Realm Fleet

Realms run on **self-hosted Agones** (Kubernetes-native) — explicitly **not** a
single managed vendor, because the managed-orchestration market is unstable
(Unity Multiplay shut down Dec 2025; Hathora shut down May 2026). Design:

- **Agones `Fleet`/`GameServer` CRDs:** a realm maps to a Fleet; allocation
  moves a server to `Allocated` (protected from scale-down until
  `SDK.Shutdown()`).
- **Scheduling:** `Packed` for elastic cloud regions (cheap scale-down),
  `Distributed` for owned bare-metal (the repo's Hetzner footprint).
- **Autoscaling:** buffer-based autoscaler keeps N pre-warmed ready realms so
  joining a popular realm is instant (absorbs cold-start); a webhook autoscaler
  encodes RP-specific demand curves (evening peaks).
- **Cost tiering:** stateless/respawnable realm sessions run on **Spot** (up to
  ~90% savings, GameLift-FleetIQ pattern: latency-first then cost-first
  placement, 2-min reclaim handling); **persistent-state RP realms** run
  On-Demand / owned hardware. Persistent state is safe on cheap/preemptible
  compute only because Nephthys holds the truth (arch§"Nephthys").
- **Who pays:** hybrid — platform pays for identity/economy/safety services + a
  buffered "official" realm fleet; creators may bring-their-own-compute for
  high-volume realms, but **only sandboxed realm logic, never platform
  services** (the GSP model, with the trust boundary intact). Session
  allocation/matchmaking to fleets reuses the V5 matchmaking service for
  skill/region where realms opt in.
- **DDoS:** the gateway is the only client ingress and runs upstream scrubbing +
  rate limiting; community-hosted realms sit behind the platform gateway so
  their origin IPs are not exposed (closing the FiveM origin-exposure weakness).

## Abundantia — Distribution and Payout Architecture

- **Catalog + CDN:** content-addressed artifacts (arch§"Dependency Resolution")
  served from a CDN; a single account's installs sync cross-platform (mod.io
  model). Console distribution defaults to require-approval (cert compliance);
  PC supports auto-approve for trusted creators with post-publish moderation.
- **In-game browser:** one-click install resolves the lock file and fetches only
  Sekhmet-cleared artifacts; Collections install their full set atomically.
- **Payout engine (Aje-settled):** three rails — engagement payouts (a pool
  funded by **40% of eligible platform net revenue** — committed default
  2026-06-12, amendable via the Eunomia governance process), direct
  sale/subscription (≥70% creator floor), and dependency-revenue chains that
  flow a configured share to declared dependencies' creators (computed from the
  lock file's dependency set; **default 10% of an item's gross revenue, routed
  pro-rata to its declared dependencies, operator-configurable 0–25%, never
  reducing the original creator below the 70% floor** — committed default
  2026-06-12, amendable via Eunomia). All settle through Aje with
  KYC/tax/refund/payout/reserve gates (the V5 paid-mod compliance spine).
  Anti-fraud below.

## The Economy Firewall and Anti-Fraud

Two firewalls, both mandatory:

- **The currency firewall.** The real-money platform economy (purchases,
  payouts, cosmetic ownership) is **platform-controlled and one-directional** —
  money flows _in_ to entitlements. **In-realm RP play-currency is non-fungible
  and non-cashable** to real money through any community operator. This keeps
  casinos/ loot mechanics out of gambling regulation (no real-money cash-out)
  and clarifies age-gating. (Jurisdiction-specific legal counsel required.)
- **Payout-fraud prevention (Roblox/UEFN model).** Engagement that counts toward
  the payout pool comes **only from monetized accounts** (accounts with prior
  verified real-money spend) — the single strongest anti-bot lever, since farms
  can't cheaply fake real spend. Payouts weight **multi-day retention** and
  new/reactivated paying users over raw concurrency (kills CCU-inflation bots).
- **RMT + self-dealing detection.** A platform-side graph over
  account↔realm↔device↔payment relationships flags one-directional "free money"
  flows and anomalous network centrality (the gold-farming topology), and
  clusters of same-device/never-spent accounts (creator farming their own
  realm). ML on retention-predictive actions scores engagement _quality_.
  Random-forest/graph models from the RMT-detection literature transfer
  directly.

## Sekhmet — Trust, Safety, and Child-Protection Architecture

All of this is **platform-central, never realm-delegated.** A community operator
never sees raw biometric data, runs an age check, or is the CSAM-scanning
authority.

- **Asset malware scanning** at ingest, before any client can fetch: signature +
  heuristic (ClamAV-class) plus dynamic WASM capability analysis; nothing is
  served unscanned.
- **CSAM detection:** perceptual-hash match (PhotoDNA + PDQ) against NCMEC hash
  DBs on every uploaded image/texture; CSAI Match for video; a Thorn
  **Safer**-class ML classifier for novel/unhashed CSAM. **3D/texture assets:**
  render canonical 2D views and hash those (native 3D-mesh CSAM hashing is an
  open problem — flagged).
- **Grooming detection:** a Project-Artemis-class conversation classifier
  (licensed free via Thorn) scores chat for grooming patterns; high scores route
  to human moderators. **Voice** is screened by direct audio analysis
  (intonation), not just STT — voice is the highest-risk grooming channel and is
  platform-monitored.
- **Longitudinal patterns:** a Sentinel-class detector (Roblox open-sourced one
  — verify license before adoption) surfaces early child-endangerment signals
  across realms.
- **Cross-platform signal sharing:** join **Lantern** (Tech Coalition) to catch
  realm-hopping/platform-hopping predators.
- **NCII:** StopNCII hash ingestion + a ≤48h takedown pipeline (TAKE IT DOWN Act
  compliance).
- **Age assurance:** facial-age-estimation via a third-party vendor that deletes
  biometrics immediately (minimize PII liability); users are age-banded;
  cross-age contact and unfiltered chat are restricted by default and gated on
  age estimation (the UK OSA / EU DSA / US-state regulatory wave makes this
  day-one, not retrofit).
- **Supply-chain integrity:** content-addressing + signing + lock-file hash
  pinning; account-takeover step-up on re-publish (the fractureiser defense);
  the incident-response playbook (suspend new-file approval, rescan, lockdown,
  recall by content hash, public report).

## Anti-Cheat and Client Integrity

- **Client integrity is platform-owned:** a hardened, signed, **attested**
  client (Roblox-Hyperion precedent); operators never ship or patch client
  binaries.
- **Server-authoritative netcode** is the structural foundation (a tampered
  client can't grant itself state). On top, the V5 anti-cheat stack (EAC kernel
  driver + server-side ML signals: impossible-angle, speed-hack via
  position-delta, wall-hack via LOS mismatch; 3-strike flow) extends to
  community realms: signals run on the authoritative node so a tampered client
  can't suppress them. Realm-scoped enforcement; platform bans route through
  Kuanyin/Themis. Anti-cheat governs competitive/anti-exploit surfaces, not
  roleplay choices.

## Eunomia — Governance Data Model

```
Proposal { id, tier(platform|game|realm|server|guild), state(draft|deliberation
           |voting|execution|appeal), voting_model, ballots[], outcome, appeal_ref }
```

Five tiers each hold a sovereign rule space a parent cannot override without
consent, bounded by the non-negotiable platform safety floor (Lilith/Kuanyin).
Voting models: token-weighted, reputation, quadratic, conviction, delegated,
time-weighted. Appeals route to Themis (`libs/themis/`). Optional tamper-evident
on-chain recording via Aje, but governance does not require a chain.

## Cross-Version Bridge (Ori Passport)

V7 reuses the V6 Aye Bridge (`libs/v6/aye-bridge/`) unchanged for incarnation
into V2–V6: a V7 character is an Ori record, so the passport carries it (and its
Hera group) into a V-destination with per-destination capability mapping and the
incarnation journal. V7 adds one corridor — **realm-to-realm** under federation
treaty — governed by the same passport + Themis. The Ori remains the truth; a
realm (like any Aye destination) is a stage it is rendered into.

## Data Architecture, Residency, and Compliance

- **Stores:** Nephthys (realm/character state, event-sourced), the V6 Ori store
  (identity), Postgres+pgvector for catalog/social/governance (reusing the V1
  persistence stack `libs/oshun/persistence/`), content-addressed object store
  for artifacts.
- **Residency:** `libs/shared/data-residency/` tags every aggregate;
  cross-region federation honors travel rules.
- **Compliance:** GDPR/CCPA DSAR (reuse V5 `compliance-dsar`), DSA reporting,
  COPPA-path for under-13, the age-assurance regime above, audit via
  `libs/shared/audit-platform/`.

## Observability and Live Operations

- **Metrics:** realm population/retention, mesh node utilization + split/merge
  frequency, authority-handoff latency + failure count, sandbox fuel-overrun
  rate, scan-queue latency, payout distribution, economy inflation per realm,
  per-client bandwidth.
- **Creator analytics:** Roblox/UEFN-class dashboards — DAU/retention/playtime,
  funnel, revenue, per-mod engagement — so creators can iterate.
- **Tracing/logging/SLOs** reuse the V1 observability stack; the gateway exports
  per-realm health used by the Abundantia browser (a degraded realm is flagged,
  not surfaced as healthy).

## Performance Budgets

- **Client frame:** **60 fps target / 16.7 ms frame budget on the reference
  platform tier, 30 fps floor on minimum spec** (adopted 2026-06-12), sustained
  in a meshed realm at 1000+ inhabitants via interest-managed culling (a client
  never simulates/renders the whole realm) + Nanite/LOD streaming + tiered
  fidelity.
- **Server:** per-node sim budget with split/merge triggered _before_
  saturation; per-plugin per-frame fuel/memory budgets.
- **Netcode:** playable at 5% loss, graceful at 20%; 64–256 kbit/s open-world
  per-client; authority handoff **≤250 ms p99** (adopted 2026-06-12), no
  reconnect.
- **Voice (Pheme):** ≤40 audible streams per listener after AoI culling; mixing
  CPU ≤2 cores per 256 concurrent speakers per realm node; radio/phone channels
  add ≤8 streams per listener; p95 mouth-to-ear ≤250 ms at 1,000-inhabitant
  realm scale (adopted 2026-06-12; see arch§"Pheme — Voice Architecture").
- **Distribution:** one-click Collection install resolves+fetches **p95 ≤120 s
  for a 5 GB Collection on a 100 Mbit/s connection**; Sekhmet scan-queue **p95
  ≤15 min upload-to-verdict at launch scale** (adopted 2026-06-12) so
  publish-to-available is predictable.

## Build, Cook, Patch, and Cert

UE5.5 cook + per-platform packaging (reuse the V5/V6 build pipeline), console
cert constraints gate which sandbox tiers a console realm may grant. Mod
artifacts are content-addressed and CDN-distributed; client patches are
platform-signed (never operator-distributed). AOT plugin compilation runs in the
upload pipeline.

## Testing, Eval Gates, and Golden Replays

CI gates (must be green, must fail against the adversarial case):
`sandbox-escape` (0 escapes over a hostile-module corpus), `mesh-handoff` (0
loss/dup over 10k boundary crossings incl. mid-handoff node death),
`netcode-loss` (playable @5%, graceful @20%), `resolver`/`conflict` (correct
lock + only true contradictions), `anticheat` (signal precision/recall),
`malware-corpus` (detection rate), `csam-hash` (100% on a synthetic known-hash
set), `payout-formula` (known-correct distribution to the cent),
`minor-protection`, `passport`. **Golden replays** assert that a recorded input
log reproduces the exact authoritative state hash (the determinism guard).

## Launch Readiness

V7 is launch-ready when the gates above are green and: the trust boundary is
enforced (no platform secret reachable from realm code or the creator web view);
the sandbox has zero escapes on the corpus; Danu sustains 1000+ with clean
handoffs; Sekhmet meets CSAM/grooming/malware bars and passes an IR drill; age
assurance + NCII ≤48h pipeline are live; payouts settle correctly with
anti-fraud gates; anti-cheat meets its bar on community servers; and the
Lilith/Kuanyin safety floor is enforced on every realm regardless of operator
configuration.