---
title: The Virtual Realm
description: Canonical product and implementation plan for the grounded spatial twin and owner-private local Cityform operations view of Particle Realms Online.
audience: architects, RealmForge authors, engine developers, security reviewers, and QA engineers
updated: 2026-08-13
status: approved planning baseline
---

# The Virtual Realm

The Virtual Realm is the first Realm of Particle Realms Online. It is a living spatial twin in which authorized files create geography, software creates architecture, processes create inhabitants and machinery, communication creates transportation, and real source becomes Code Matter. Ordinary world use is grounded first person; the authenticated local operator may explicitly enter a bounded owner-private operations view of only their own Cityform.

This documentation set is the canonical planning baseline. It defines the product, architecture, contracts, privacy model, RealmForge pipeline, Storylet system, multiplayer protocol, rendering strategy, implementation roadmap, and certification gates. The active M0 implementation is the additive 100-module contract package and its browser/Python conformance suite. Later renderer, scanner, Storylet, and multiplayer runtime milestones remain controlled by their roadmap gates.

## Locked product statement

The Virtual Realm is not a 3D file browser, detached graph viewer, virtual desktop, MindWalk clone, or imitation of an existing fictional world.

Each computer manifests as a mobile **Cityform**, its macro-scale body in the shared digital world. The user remains a human-scale, first-person **Traveler** inside that Cityform during exploration and every shared encounter. The same authenticated local operator may open a separate isometric or eagle-eye **Local City Operations View** and minimap for their own Cityform only. The filesystem shapes the city, WebGPU OS supplies live truth, RealmForge authors and compiles stable form, and SecureMesh becomes the central train station and network hub.

## Non-negotiable rules

1. Grounded first person is the only traversal mode for Travelers, visitors, multiplayer, bridges, Code Matter inspection, and replay.
2. The sole overview exception is an explicitly entered, authenticated, capability-authorized, owner-private Local City Operations View with bounded isometric or eagle-eye framing and a minimap for exactly the operator's own Cityform.
3. The Operations View is not third-person Traveler play. It has no orbit, free flight, avatar follow, detached graph navigation, remote-city view, or authority of its own.
4. Connected Cityforms and their shells, poses, rendezvous, bridges, Travelers, resources, picks, and map records are structurally absent from the Operations View and minimap before scene assembly.
5. Outside that exception, overview information appears through the first-person visor, signs, observatories, station boards, windows, and physical projections.
6. Readable code is always real, authorized code.
7. Decorative animation never masquerades as telemetry.
8. Unknown information appears as sealed, denied, stale, estimated, partial, or absent.
9. WebGPU OS and the kernel remain authoritative for files, processes, identities, permissions, networking, source bytes, and zone-management results.
10. Cameras, minimaps, picking, gameplay, and Storylets can request authority. They cannot grant it.
11. RealmForge authors and compiles the world. It does not own live runtime state.
12. Public, private, and capability-refined worlds compile independently.
13. Proximity never implies trust or permission.
14. Modules are flat peers connected by explicit contracts and application composition roots.
15. The implementation introduces no Node.js or npm dependency.
16. Stable geography changes only through a verified bake revision, never as a side effect of live telemetry.
17. The First Shard is excluded from all source, test, imported documentation content, dependency, scan, and design decisions for this Realm; only explicit exclusion assertions may name it.
18. Playground research contributes only public Engine API knowledge and independently restated behavioral invariants; no demo implementation, WGSL, UI, camera, authored topology, loader state, or fallback enters production.

## Authoritative flow

The authored bake and live system truth remain separate until the Virtual Realm runtime projects both into ECS state.

```mermaid
flowchart TB
  privateInput[Authorized private source snapshot] --> privateProjection[Private audience source projection]
  publicInput[Explicit public appearance inputs] --> publicProjection[Public audience source projection]
  refinementInput[Exact capability-scoped inputs] --> refinementProjection[Refinement audience source projection]

  privateProjection --> privateCompiler[Independent private RealmForge compiler job]
  publicProjection --> publicCompiler[Independent public RealmForge compiler job]
  refinementProjection --> refinementCompiler[Independent refinement RealmForge compiler job]

  privateCompiler --> pb[PrivateRealmBake]
  publicCompiler --> ps[PublicRealmShell]
  refinementCompiler --> ar[AccessRefinement]
  pb --> loader[Verified bake loader]
  ps --> loader
  ar --> loader

  os[WebGPU OS truth] --> ports[Typed observation ports]
  ports --> projectors[Domain projectors]
  projectors --> deltas[Immutable RealmDelta stream]

  mesh[SecureMesh and RealmLink] --> station[Station and docking adapters]
  station --> deltas

  loader --> runtime[Virtual Realm runtime]
  deltas --> runtime
  runtime --> ecs[ECS synchronization]
  ecs --> gpu[Dedicated WebGPU presentation]
  gpu --> fp[Grounded first-person Realm]
  runtime --> localFilter[Owner-private local-only projection]
  localFilter --> ops[Local City Operations View and minimap]
  kernel[Kernel capabilities] -. authorize requests .-> runtime
```

RealmForge controls static form and projection bindings. WebGPU OS controls live facts. The runtime loads immutable bakes and applies ephemeral projections. Nothing flows backward into an authored RealmForge document.

## Canonical terminology

| Term | Meaning |
| --- | --- |
| Virtual Realm | Canonical name of this Realm |
| Cityform | A computer's mobile macro-scale embodiment |
| Traveler | A user's human-scale first-person presence |
| Local City Operations View | Owner-private bounded isometric or eagle-eye management projection of exactly the operator's local Cityform |
| Mesh Expanse | Shared encounter space between Cityforms |
| RendezvousFrame | Temporary shared coordinate frame for approaching and docking Cityforms |
| Root Spine | Primary local orientation and transit landmark |
| SecureMesh Exchange | Train station, network hub, and visible trust boundary |
| Code Matter | Spatial matter backed by authorized source or data |
| RealmVisualBake | Immutable, runtime-ready authored world package |
| PrivateRealmBake | Exact authorized local topology and bindings, unpublished by default; plaintext source remains in the reveal-gated vault |
| PublicRealmShell | Sanitized, complete-looking public Cityform presence |
| AccessRefinement | Capability-scoped additional world content |
| RealmObservation | Normalized immutable fact from an authoritative source |
| RealmDelta | Immutable live projection change derived from observations |
| Storylet | Deterministic scenario that stages real events and authorized requests |
| Bridge Epoch | One authenticated docking and authorization generation |
| Chronicle | Signed semantic history and replay source |

Earlier planning names are normalized without losing their intent: `PublicCityBake` means `PublicRealmShell`, and `AccessRefinementPack` means `AccessRefinement`. The canonical names emphasize that a public shell is not a reconstruction of the private machine and that a refinement is separately authorized.

## Documentation map

- [Architecture and ownership](architecture.md) defines the flat module model, composition roots, dependency rules, and source-of-truth boundaries.
- [Playground clean-room foundations](playground-clean-room-foundations.md) freezes the CSE, URC, State-First, and Root Algebra adoption boundary, production adapter seam, truth planes, lifecycle, source ledger, and milestone placement.
- [Contract catalog](contracts.md) defines the complete V1 record families, fields, canonicalization, audience separation, authority receipts, and validation order.
- [RealmForge bake pipeline](realmforge-pipeline.md) defines authored resources, compilers, independent audience variants, dependency closure, and publication.
- [World projection grammar](world-projection.md) maps real WebGPU OS data to stable first-person geography and live presentation.
- [Local City Operations View](local-operator-view.md) defines owner-private isometric/eagle-eye framing, the own-city minimap, zone proposals, and structural exclusion of connected Cityforms.
- [Code Matter](code-matter.md) defines sealed, structured, and revealed source states with exact authority and privacy rules.
- [Cityforms and SecureMesh](cityforms-securemesh.md) defines the station, public presence, rendezvous frames, docking, bridges, epochs, and revocation.
- [Storylets](storylets.md) defines deterministic event-driven scenarios, authoring, runtime arbitration, multiplayer scope, Chronicle records, and replay.
- [Rendering and experience](rendering-experience.md) defines the dedicated renderer, first-person controller, semantic LOD, visual language, audio, accessibility, and performance strategy.
- [Security and privacy](security-privacy.md) defines noninterference, hostile-content handling, capability boundaries, metadata protections, and threat invariants.
- [Implementation roadmap](implementation-roadmap.md) defines the dependency-ordered build milestones, deliverables, exclusions, approval gates, and rollback boundaries.
- [Certification plan](certification-plan.md) defines deterministic, privacy, rendering, network, recovery, accessibility, and architecture acceptance tests.
- [Research and originality ledger](research-originality.md) records the MindWalk and fictional-inspiration boundary without importing their expression or implementation.

## Scope of the first release

The first release includes:

- One locally authored and baked Cityform.
- The Root Spine and one SecureMesh Exchange district.
- Grounded first-person traversal with collision and interaction, plus the bounded owner-private Local City Operations View and own-city minimap.
- Real local boot, filesystem, process, syscall, IPC, permission, storage, and network projections.
- Local sealed, structured, and revealed Code Matter with byte-exact verification.
- An independently generated PublicRealmShell.
- Two authenticated peers and mutual presence consent.
- One public destination and one deterministic bridge.
- Directional capability grants, expiry, disconnect, and revocation.
- Public skyline persistence after departure until the signed shell expires.
- Storylet-driven orientation, inspection, station activity, incident explanation, and Chronicle replay.
- Device-loss recovery, performance evidence, privacy certification, and accessibility certification.

The first release defers permanent global coordinates, remote exact-source reveal, private interior refinement streaming, group docking, arbitrary remote visual assets, zero-knowledge shell proofs, guaranteed presence after the browser closes, native whole-PC scanning without a separately authorized companion, combat, economy, VR, and every camera or map mode other than grounded first person and the owner-private local Operations View.

## First playable sequence

The vertical slice proves the complete architecture through grounded first-person traversal and one explicit owner-private operations interlude:

1. Launch The Virtual Realm from WebGPU OS.
2. Spawn at the Root Spine inside a locally generated Cityform.
3. Open the own-city minimap, explicitly enter the Local City Operations View, select and focus one local zone, submit one bounded management proposal, receive its authority result, and return to the preserved first-person anchor.
4. Walk through the five shipped foundational territories created from authorized repository structure.
5. Follow one real boot, syscall, IPC, storage, and network path through its roads and conduits.
6. Approach one Code Matter structure, inspect its identity and commitment, request local reveal authority, and verify exact source.
7. Diagnose one clearly simulated presentation fracture without modifying the real filesystem.
8. Enter and activate the SecureMesh Exchange.
9. Observe a signed remote public Cityform approach and see its Traveler arrive only after authentication and mutual presence consent.
10. Re-enter the Local City Operations View and prove that the connected Cityform, public shell, remote Traveler, rendezvous, and bridge records remain absent while the local station exists only as a local landmark; then return to first person.
11. Negotiate one directional capability, independently bake and verify one deterministic bridge, cross into one permitted public district, and inspect real route traffic.
12. Revoke the capability and verify that protected traffic stops, the track retracts, protected interaction disappears, and the sanitized remote skyline remains until shell expiry.

All Traveler traversal, remote encounters, bridge use, Code Matter reveal, and replay remain first person. The Operations View is an owner-private local management projection, never part of the shared spatial session. Route summaries, topology history, and MindWalk-like activity playback otherwise appear only as visor data or physical in-world projections.

## Existing foundations

The plan reuses the repository's current narrow contracts instead of extending its largest modules:

- Frame scheduling: `engine/core/framepipeline/FramePipeline.js`
- GPU pass dependencies: `engine/core/framegraph/FrameGraph.js`
- ECS: `engine/ecs/world/World.js`
- Culling: `engine/render/state/StateFirstGpuCuller.js`
- Picking: `engine/tools/picking/RayPicking.js`
- Close-range code surfaces: `engine/surfaces/CodeSurface.js`
- Spatial audio: `engine/audio/core/AudioEngine.js`
- Processes: `webgpu-os/kernel/ProcessTable.js`
- Filesystem: `webgpu-os/kernel/VirtualFS.js`
- Persistent storage events: `webgpu-os/storage/StorageManager.js`
- Permissions: `webgpu-os/kernel/Permissions.js`
- SecureMesh sessions: `webgpu-os/drivers/NetworkDriver.js`
- Authenticated Realm links: `engine/network/realm/link/RealmLink.js`
- Semantic history: `engine/network/realm/chronicle/RealmChronicle.js`
- RealmForge semantic hashes: `webgpu-os/apps/realmforge/document/hash/RealmForgeContentHash.js`
- RealmForge SystemGraph compilation: `webgpu-os/apps/realmforge/modeler/system-graph/RealmForgeSystemGraphCompiler.js`
- RealmForge assembly compilation: `webgpu-os/apps/realmforge/modeler/compile/AssemblyCompiler.js`
- RealmForge Engine materials: `webgpu-os/apps/realmforge/material/RealmForgeEngineMaterialAdapter.js`
- Storylet facade and eligibility: `webgpu-os/kernel/storylets/StoryletRuntime.js` and `webgpu-os/kernel/storylets/StoryletEligibilityBridge.js`

The CSE/URC public barrel at `engine/state/index.js` and the Engine State-First surface are eligible only through composition-root-injected adapters. The audited Playground files remain research evidence and are never production imports; the exact boundary and citations are recorded in [Playground clean-room foundations](playground-clean-room-foundations.md).

The existing immersive desktop compositor is not the Virtual Realm renderer. It presents windows as textured quads and does not supply continuous world traversal, city geometry, spatial audio, deterministic Cityform bakes, HLOD, or authoritative world interaction.

## See also

- [Realm Network](../realm-network.md)
- [WebGPU OS architecture](../architecture.md)
- [Engine rendering](../../engine/rendering.md)
- [Security and Trust Model](../../concepts/security-model.md)