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 catalog (5)#
The 5 tracked Nx projects in v7, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 4 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
contracts (1)#
V7 realm, character, collection, marketplace, governance, safety, and incident 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."
roundTripV7Contract3V7GeneratedContract3V7GeneratedContractMap3V7GeneratedContractName3domain (1)#
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.
protocol (1)#
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
RealmEnvelopes 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().
service (1)#
Governed Metis education for V7 creator publication safety.
substrate (1)#
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.