# V7 — Systems Deep Dive

> The `libs/v7/` area: the foundation libraries for **V7 (Mawu)** — a typed
> contract surface plus three Rust crates (roleplay-character primitives, the
> realm netcode protocol, and the substrate bridge into reused V1/V6 platform
> services) that a server-authoritative, creator-built realm platform is built
> on.

## What this area is

V7 is the "Mawu" realm platform: server-authoritative multiplayer realms that
creators build and that players incarnate characters into. The `libs/v7/`
directory holds its lowest layers — four tracked Nx projects, one TypeScript and
three Rust — each pinned to a distinct architectural layer by its `tags` in
`project.json` (`layer:contracts`, `layer:domain`, `layer:protocol`,
`layer:substrate`). The three Rust crates share a single Cargo workspace at
`libs/v7/Cargo.toml` (members `nana`, `realm-protocol`, `substrate-bridge`,
edition 2021, `unsafe_code = "forbid"`).

The four projects stack rather than sprawl. `@v7/contracts` defines the wire
types — realms, characters, marketplace listings, payouts, governance, safety
scans, incidents — as canonical Zod schemas and generates OpenAPI plus
TypeScript/Rust/C++ artifacts from them. `@v7/nana` is the in-Rust character
record primitive (the "Nana" roleplay domain) that the realm servers and the
substrate bridge agree on. `@v7/realm-protocol` is the netcode layer: signed
cross-trust message envelopes, client prediction and reconciliation, snapshot
interpolation, delta compression, lag compensation, and wire conformance, all
expressed as deterministic eval reports. `@v7/substrate-bridge` is the
integration seam that authenticates a platform principal and persists a Nana
character through the **reused** V6 Egbe Ori event store rather than
reimplementing identity or storage.

A recurring design choice across the area is "reuse over reimplementation": V7
explicitly consumes V1 platform boundaries (identity, economy, safety,
moderation) and V6 realtime/Ori boundaries, and the `realm-protocol` crate is
described in its own module doc as "layered over the V6 Egbe transport." That is
why the deepest crate here, `realm-protocol`, deliberately carries no transport
dependency (only `hmac` + `sha2`) — it defines the protocol so gateways and
realm servers can share it.

## How it fits the wider system

`@v7/contracts` is the BFF/service-facing surface: its `V7_CONTRACT_REGISTRY`
drives an OpenAPI 3.1 document (`buildV7OpenApiDocument`) and a code-generation
step that emits `src/generated/{openapi.json,typescript.ts,rust.rs,cpp.hpp}`,
with a `generate:check` target wired as a `dependsOn` of `build`/`typecheck` so
the committed artifacts can never drift from the Zod sources. The Rust realm
servers consume `@v7/realm-protocol` for the on-wire framing and the netcode
evals, and `@v7/nana` for the canonical character record. `@v7/substrate-bridge`
is where V7 actually touches the rest of the monorepo: it depends on the real
`egbe-ori-service`, `ori-model`, and `maya-world` crates (V6 Ori storage and the
Maya engine-core world config) and reuses the V6 Aye Bridge incarnation contract
to move characters across V2–V6 destinations. The boundary the bridge enforces
in the other direction is just as important: an identity firewall and
trust-boundary evals keep platform secrets out of realm-process and creator
web-view contexts.

## Entity reference

### @v7/contracts

The V7 typed wire-contract package (`libs/v7/contracts`, `layer:contracts`,
TypeScript). Its `src/schemas.ts` defines ten canonical Zod contracts collected
in `V7_CONTRACT_SCHEMAS` — `Realm`, `RealmLock`, `Character`, `ModCollection`,
`Listing`, `Payout`, `Governance`, `ScanReport`, `AgeBand`, and `Incident` —
plus shared primitives (`V7RefSchema`, `V7ContentHashSchema`, `V7MoneySchema`,
realm transform/vector/color schemas). `src/registry.ts` turns each into a
`V7ContractDescriptor` (route segment, id field, tag, summary, fixture), which
`src/openapi.ts` (`buildV7OpenApiDocument`) renders into an OpenAPI 3.1 document
and `scripts/generate-v7-contract-artifacts.ts` emits as the committed
`src/generated/` openapi/typescript/rust/cpp artifacts (guarded by a
`--check`/`generate:check` mode). It is more than schemas: `src/realm-lock.ts`
implements content-addressed Mawu realm lock files (canonical JSON + `sha256:`
hashing via `node:crypto`,
`computeV7RealmLockFileHash`/`verifyV7RealmLockFileHash`), and
`src/accessibility-eval.ts`, `src/creator-analytics.ts`, and
`src/platform-cost-telemetry.ts` add real evaluators (the Mawu accessibility
floor linter with five rules, the creator-analytics dashboard, and the
platform-cost telemetry dashboard). The package `description` is authoritative:
"V7 realm, character, collection, marketplace, governance, safety, and incident
contracts."

### @v7/nana

The Nana roleplay-domain primitive crate (`libs/v7/nana`, `layer:domain`, Rust
`v7-nana`). It is small and honest about it: its `src/lib.rs` doc comment states
the crate "intentionally starts small" and defines "the public record and
validation surface that Moremi, Nephthys, and future TS bindings can agree on
before the full character, job, housing, and economy systems are implemented."
What exists is real and tested, not a stub — `NanaCharacterRecord` (Ori id,
realm id, display name, optional `NanaEmployment`, `NanaBalances`), a
`stable_key()` of the form `nana:{realm}:{ori}`, and a `validate()` that rejects
missing ids, empty names, and negative balances (`NanaValidationError`), with
unit tests covering the happy path and negative-balance rejection. It has no
dependencies (empty `[dependencies]`) and pins the schema label
`NANA_CHARACTER_SCHEMA_VERSION = "v7.nana.character.1"`. Treat it as a
foundation primitive consumed by `@v7/substrate-bridge`, with the larger
character/job/housing/economy systems still to come.

### @v7/realm-protocol

The V7 realm netcode protocol crate (`libs/v7/realm-protocol`, `layer:protocol`,
Rust `v7-realm-protocol`) — by far the largest entity here (`src/lib.rs` is
~4,400 lines) and a substantial real implementation, not a scaffold. Per its
module doc it "defines the first stable Rust API for realm envelopes, protocol
versions, and capability negotiation" and "deliberately avoids transport
dependencies" so it can be shared by gateways and realm servers; its only deps
are `hmac` and `sha2`. It covers the full server-authoritative netcode surface
as deterministic, gateable eval reports: HMAC-SHA256-signed cross-trust
`RealmEnvelope`s with platform security tokens and intent expiry
(`RealmEnvelopeError` enumerates ~20 validation failures), authoritative state
with a `sha256:` `state_hash`, client prediction + server reconciliation
(`RealmPredictionEvalReport`, 80 ms RTT gate), snapshot interpolation with
Hermite position and quaternion SLERP (`RealmInterpolationEvalReport`, 5% loss /
±2-frame jitter), ack-relative delta compression over a 32-snapshot ring with a
64–256 kbit/s bandwidth budget, a delayed read-only spectator stream, lag
compensation with favor-the-shooter rewind and exploit blocking, a combined
netcode-loss gate, an event-tamper eval, and a wire-protocol conformance harness
across the V6 gateway transports (WebTransport/WebRTC/WebSocket). The capability
inventory is enumerated in `baseline_realm_capabilities()`.

### @v7/substrate-bridge

The V7 substrate integration crate (`libs/v7/substrate-bridge`,
`layer:substrate`, Rust `v7-substrate-bridge`). Its job, per the module doc, is
to keep "the first integration path deliberately small and observable":
`authenticate_and_sync_character` authenticates a `V7AuthenticatedPrincipal`,
projects it through a deterministic `V7IdentityFirewall` into an opaque
per-realm handle, writes a Nana character memory into the **reused** V6 Ori
event store, and reads back the audited Ori projection. The reuse is genuine —
it depends on the real `egbe-ori-service`, `ori-model`, and `maya-world` crates
(`EgbeOriFacade` calls `PartitionedPostgresOriEventStore`,
`OriProjectionMaterializer`, and `operator_read_ori_projection`;
`maya_runtime_probe()` builds a real `WorldConfig`). It also implements the
security seams around realms: identity-leak and trust-boundary evals that keep
platform secrets out of realm-process and creator web-view contexts, a
locked-down `V7CreatorWebViewPolicy` with a webview-escape eval, and
cross-version Aye Bridge incarnation passports plus Themis-signed realm
federation corridors. Be precise about its honesty seam:
`default_substrate_bindings()` marks most boundaries as
`V7SubstrateBindingMode::Mock` — every V1 substrate (identity, aje, lilith,
kuanyin, themis, iris, psyche, isis, sophia, yemaya) and the V6 Egbe gateway are
deliberately scoped mocks; only `V6OriAyeBridge` and `MayaEngineCore` are
`Reused`. So the Ori-write/read path and the Maya runtime probe are real,
wired-up integrations, while the other named substrates are declared-but-mocked
integration points awaiting their real bindings.