--- title: Virtual Realm Implementation Roadmap description: Dependency-ordered milestones, deliverables, exclusions, validation gates, rollback boundaries, and approval points for building The Virtual Realm. audience: project leads, implementers, reviewers, and QA engineers updated: 2026-08-13 status: approved planning baseline --- # Virtual Realm Implementation Roadmap The Virtual Realm implementation proceeds through eight gated milestones. A failed gate stops advancement without invalidating previously accepted artifacts. Each milestone remains modular and leaves a recoverable rollback boundary. ## M0: specification and contract freeze ### Scope - Freeze terminology, ownership, authority, scope, units, coordinate policies, disclosure classes, Storylet rules, originality rules, and flat dependency constraints. - Define every V1 contract as a separate versioned module. - Freeze `RealmScanScopeV1` with explicit allow roots, opaque hard-deny subtree handles, canonical and symlink-safe containment, pre-access checks, and content-safe diagnostics. - Freeze canonical content encoding, acyclic content-address order, external `SignatureEnvelopeV1` preimages, and signer-set rules with cross-client vectors. - Freeze `RealmStoryletInstanceHeadV1`, authored episode heads, external persistence receipts, exact logical-clock and PCG vectors, coordinator terms, and outer recovery state. - Freeze the Playground clean-room boundary: public Engine API versus independently restated invariant versus preview-only expression versus deferred implementation. - Freeze the source-to-CSE-authority-to-observation-to-disclosure-to-State-First-to-frame flow, truth-plane matrix, injected Engine adapter seam, lifecycle generations, and audience-safe historical-witness mapping. - Freeze the two approved view modes, local operator authority binding, local-only overview/minimap projection, connected-Cityform structural exclusion, and powerless zone-management proposal path. - Select reference hardware and supported browser/device tiers. - Define the documentation and independent-rewrite ledger. ### Deliverables - Contract schemas and examples. - Canonical digest, signature-envelope, logical-clock, deterministic-random, and safe-text conformance vectors. - Module and port catalog. - Import-boundary rules. - Threat model. - Originality ledger. - Playground clean-room source ledger, production-ban list, adapter contract, and certification matrix. - Local operator policy, view snapshot, minimap snapshot, and zone-management proposal contracts with adversarial local/remote isolation fixtures. - Reference hardware and measurement protocol. ### Gate - Every source of truth has one owner. - No public/private ambiguity remains. - No contract uses source, test, design, mechanic, scan result, or dependency material from the explicitly excluded application. - No runtime implementation begins before contract review passes. - Synthetic decoy-scope tests prove a hard-denied subtree is never enumerated, statted, opened, hashed, watched, previewed, retried, or named in logs; the actual excluded application is never used as a fixture. - Content-address DAG, signature-envelope, six-axis semantics, safe-text, presence-only Traveler, and Storylet outer-lifecycle certification gates have complete frozen fixtures and no cross-record cycle. - No production module imports `tests/playground/**`, reads Playground loader globals, copies demo WGSL/UI/camera expression, or substitutes demo-authored graph topology or a fallback for live evidence. - Presentation order cannot create causality; projection, belief, similarity, rejected history, State-First decisions, Storylets, and frames cannot grant authority or claim a terminal result. - Local operations records are exactly owner-private and local-private, expose only `localRealmId` with no foreign/viewed-Realm slot, require current authority, reject connected-content fields, and cannot bypass the generic action authority chain. ### Exclusions No renderer, scanner, multiplayer runtime, or production Storylet implementation. ### Rollback boundary M0 is implemented as an additive, side-effect-free contract package under `webgpu-os/apps/the-virtual-realm/contracts/`, with browser and Python conformance fixtures under `tests/network/realm/`. It performs no runtime registration unless an explicit composition root calls `initVirtualRealmContractRegistry()`. The package, catalog entry, fixtures, and this documentation update therefore remain independently revertible without touching Engine, WebGPU OS runtime state, RealmForge documents, SecureMesh, or user data. ### Implementation evidence - 100 independently owned flat V1 contract modules and one ordered catalog. - Strict bounded plain-JSON preflight with malformed-Unicode, NFC, cycle, accessor, symbol, inherited-field, prototype-pollution, unsafe-number, depth, count, and byte rejection. - Atomic all-or-nothing versioned registration with exact name/format lookup and idempotent full initialization. - Frozen code-point-sorted canonical JSON, length-prefixed content and signature preimages, SHA-256 content IDs, PCG-XSH-RR 64/32, unbiased bounded selection, and logical-clock merge/term rules. - Synthetic cross-client vectors, 100-contract browser conformance, an independent Python verifier, a real-Engine clean-room foundation browser harness, a dedicated exact multi-party signer-acceptance harness, and a dedicated local-operator isolation harness. - A normative CSE/URC/State-First/Root-Algebra clean-room foundation with all 15 allow-listed Playground sources plus `engine/state/index.js` cited and dispositioned; no runtime code is imported from them. - Executable clean-room evidence proves CSE commit/replay/conflict behavior, capability attenuation and non-authoritative belief boundaries, URC projection-versus-commit behavior, State-First content-identity preservation, deterministic retrieve-then-exact verification, and proof-gated Root Algebra CPU/WGSL plans. - Active authority, capability, presence-session, rendezvous, bridge, key, allocator, and clock epochs reject zero; inactive scope fields remain absent and predecessor/baseline epoch zero remains representable. - Dedicated local operator conformance proves camera bounds, loaded-cell map closure, connected-Cityform noninterference, and powerless zone proposals. ## M1: RealmForge bake foundation ### Scope - Implement `RealmVisualBakeManifestV1` and the independently compiled `PrivateRealmBake`, `PublicRealmShell`, and `AccessRefinement` package variants. - Implement topology, geometry, material, lighting, collision, navigation, glyph-style, socket, LOD, projection-binding, disclosure, Storylet, closure, validation, and publication peers. - Implement the optional `RealmProofGatedOptimizer` behind the pure compiler seam. It may compile an immutable CPU/WGSL execution plan only after frozen law obligations, counterexamples, baseline parity, bounds, numeric policy, and version binding pass. - Author one complete SecureMesh station kit. - Compile one private-bake local operations lookup with canonical local zones, anchors, cells, routes, landmarks, bounds, and map HLOD. ### Deliverables - Deterministic bake compilers. - Bound `RealmSpatialLayoutPolicyV1` and receipts covering Root Spine, territories, parcels, growth cells, HLOD, relationship routing, clearances, incremental stability, collision, navigation, and independent audience layouts. - Private and public assemblers. - AccessRefinement contract. - Storylet catalog compiler. - Independent dependency closures. - Immutable publisher and verification receipts. - Proof-gated optimizer receipts plus the mandatory unoptimized baseline compiler path. - Owner-private local operations lookup resource and dependency-closure receipt. ### Gate - Identical inputs produce byte-identical manifests and canonical digests. - Identical audience projections and layout policies produce identical semantic geography, anchor, route, HLOD, collision, and navigation digests. - Growth within reserved cells preserves unaffected anchors; capacity overflow repacks only the smallest deterministic ancestor and emits an exact relocation set. - Required roads, rails, conduits, junctions, sockets, collision, and navigation meet clearance and connectivity rules or compilation fails. - Every dependency resolves. - Public closure contains no private resource. - Invalid publication leaves the prior bake active. - Missing proof, failed law, exceeded bound, counterexample, version mismatch, CPU parity failure, WGSL parity failure, or unsupported device closes the optimization gate and produces baseline output with identical semantics. - Root Algebra cannot authorize actions, classify disclosure, discover hidden topology, choose a CSE branch, change Storylet eligibility, or mutate a published bake. - The local operations lookup is closed over one private Realm and contains no public shell, refinement, presence, rendezvous, bridge, Traveler, or foreign-Realm dependency. ### Exclusions No live OS observations or networking. ### Rollback boundary Discard generated bakes without changing the `.proasset` source. ## M2: grounded Engine and local operations foundation ### Scope - Implement `VirtualRealmEntry` and flat runtime peers. - Implement the composition-root-injected `RealmEngineAdapter` and `RealmStateFirstPresentationAdapter` without globals, module probing, service locators, Playground imports, or compatibility fallbacks. - Verify and load one static bake. - Implement grounded first-person traversal, collision, interaction, baseline lighting, spatial audio, and device recovery. - Implement the explicitly entered Local Operations View and minimap over a static private bake, with bounded isometric/eagle-eye framing and no live zone mutation. ### Deliverables - Dedicated Realm scene. - First-person controller. - Local operator policy store, local-only projector, operations camera controller, minimap projector, and zone selection store. - Static and dynamic stores. - ECS synchronization. - Geometry, lighting, effects, and audio presentation. - Device-loss recovery barrier. - State-First source registration, frame measurements, lifecycle-generation fencing, and idempotent detach/disposal evidence. ### Gate - No camera path exists outside grounded first-person traversal and the bounded owner-private local Operations View. The operations controller cannot traverse, orbit freely, follow a Traveler, or frame another Realm. - Stairs, slopes, doors, head clearance, and interaction pass. - Runtime imports no RealmForge UI. - Runtime imports no Playground source or presentation asset; the shipping bundle contains no demo camera, WGSL, UI text, identifiers, loader globals, or authored graph topology. - Missing or incompatible Engine APIs fail closed as unavailable presentation and cannot silently retain a native mode while claiming State-First behavior. - Source registration, cancellation at every await boundary, double disposal, device loss, and restart leave no stale source, GPU resource, pointer lock, listener, or presentation decision. - Device recovery rebuilds resources exactly once without duplicate entities. - Static operations entry requires current local authority and exact Realm/bake/layout binding; connected-Cityform, public-shell, presence, rendezvous, bridge, and Traveler records are structurally unaddressable. ### Exclusions No live OS data, Code Matter reveal, or multiplayer. ### Rollback boundary The static bake remains independently viewable after runtime module rollback. ## M3: local living city, Code Matter, and local Storylets ### Scope - Add boot, filesystem, process, IPC, syscall, permission, storage, and network observation ports. - Add CSE-backed causal/authority adapters, audience disclosure projection, historical-witness projection, and authoritative source-to-observation correlation through injected ports. - Add explicit boot, filesystem, process, IPC, syscall, permission, storage, network, and Code Matter projectors plus RealmDelta reduction. - Add structural source-generation detection, bounded coalescing, the cross-root bake request and activation protocol, ordered observation buffering, full reprojection, atomic activation, and pre-commit rollback. - Add the GPU glyph renderer and local reveal vault. - Add orientation, inspection, ambient truth, operational proposal, incident, and recovery Storylets. - Add coverage and provenance surfaces. - Add authorized local dynamic overlays, minimap updates, and the local-zone management proposal adapter using the existing generic authority and observation chain. ### Deliverables - Stable local geography with real live activity. - One fully cited boot-to-process-to-syscall-to-IPC-to-storage/network route sequence using only normalized observations and immutable deltas. - Local sealed, structured, and revealed Code Matter. - Read-only action path. - Deterministic local Storylet catalog and lifecycle. - Storylet Chronicle records and side-effect-free replay foundation. - Controlled automatic local-private topology refresh with explicit activation receipts. - Owner-private canonical and rejected-history witnesses with explicit temporal, assertion, provenance, evidence-quality, disclosure, retention, and expiry fields. - Live owner-private zone status, alert thresholds, visibility proposals, rebake requests, and authoritative reconciliation in both first-person and Operations View surfaces. ### Gate - Exact source reveal verifies byte for byte. - No gameplay or Storylet mutation authority exists. - Estimated metrics remain labeled. - Decorative effects cannot be mistaken for telemetry. - Every boot phase, syscall route, IPC path, storage operation, and network path cites its exact observation chain; missing or denied evidence remains sealed, absent, or stopped rather than inferred. - Identical Storylet inputs produce identical semantic timelines. - A failed or stale topology candidate leaves the prior bake active, disposes staged resources, and loses no ordered observations. - Concurrent observations remain unordered without explicit causal parents, and rendering order cannot synthesize a happens-before edge. - Selecting, rendering, or retaining a branch cannot commit it; only the owning authority's receipt and terminal observation can drive completed-success presentation. - Map selection and camera focus remain presentation-only; a zone proposal cannot present completion before its generic authority receipt and terminal authoritative observation. ### Exclusions No public shell publication or peer arrival. ### Rollback boundary Observation adapters can disable individually while the static city remains usable. ## M4: public shell and privacy boundary ### Scope - Implement independent public compilation, shell verification, cache, expiry, presence controls, hostile-content quotas, and public Storylet compilation. - Add secret sentinels, network-capture inspection, and public noninterference tests. - Add operator-view noninterference tests proving connected/public state cannot enter or perturb the local-only map for identical local inputs. ### Deliverables - Signed `PublicRealmShell`. - Safe shipped archetype registry. - Public presence controls. - Public shell and Storylet cache. - Privacy evidence. ### Gate - Private-only changes do not alter public manifests, canonical semantic-scene digests, or public Storylet timelines. Reference pixels remain within the frozen regression tolerance profile. - Network capture contains no private path, count, topology, process data, plaintext hash, or hidden eligibility fact. - Malicious manifests cannot execute or exhaust bounded resources. - Local operator snapshots and minimaps never enter public manifests, publication timing, public Storylets, or network transport. ### Exclusions No authenticated Traveler or bridge. ### Rollback boundary Public presence can disable without affecting local private Realm use. ## M5: SecureMesh Exchange ### Scope - Add SecureMesh observation, destination board, public identity verification, mutual presence consent, `PresenceSessionV1`, Cityform visibility, safe Traveler appearance, station-only authenticated Traveler arrival, host-authoritative movement, route presentation, and station Storylets. ### Deliverables - Station state reducer. - Presence verifier. - Presence-session reducer with consent, expiry, disconnect, identity-revocation, and monotonic epoch handling. - Public shell verifier and cache. - Traveler appearance verifier, presence-grant reducer, movement-intent port, host movement authority, and authoritative pose projector. - Direct and relay presentation. - Arrival, degradation, denial, disconnect, and departure Storylets. ### Gate - No Traveler appears before identity and mutual consent. - A Traveler can arrive at the station with an active PresenceSession and no RendezvousFrame or bridge. - Consent withdrawal, session expiry, disconnect, or identity revocation advances or closes the presence epoch, removes the Traveler and protected interaction, and cannot leave a stale host-authoritative pose active. - Visitor movement intents cannot self-assert position through host collision, navigation, gates, or presence scope. - No presentation event grants authority. - Every station state matches real transport state. - A closed or dormant runtime never appears falsely online. - Authenticated peers, remote shells, and station-arrival Travelers remain absent from the Local Operations View and minimap; only the local station landmark and content-free local boundary status may remain. ### Exclusions No Cityform approach or bridge traversal. ### Rollback boundary SecureMesh remains operational through its existing non-Realm surfaces. ## M6: Cityform rendezvous and deterministic docking ### Scope - Freeze and certify the V1 hierarchical-coordinate, camera-relative GPU, floating-origin rebase, precision, pose interpolation, and bridge-endpoint quantization policy before enabling approach. - Add signed virtual RealmPose, federated RendezvousFrames, Cityform approach, directional grants, bridge recipes, digests, epochs, revocation, reconnect, and shared docking Storylets. ### Deliverables - Rendezvous and pose contracts. - Coordinate-rebase and numeric-precision receipts across rendering, culling, collision, navigation, picking, audio, Chronicle, and bridge compilation. - Docking protocol. - Deterministic bridge compiler. - Epoch-aware bridge reducer. - Multiplayer Storylet synchronization. - Revocation cleanup. ### Gate - Both clients produce the same canonical bridge recipe digest. - Rebase at the maximum certified separation changes no semantic pose, collision result, pick identity, audio source relationship, Storylet state, or bridge digest. - Digest or version disagreement fails closed. - A track appears only after active directional authority. - Revocation rejects protected traffic before protected presentation remains interactive. - Cityforms cannot separate while traversal remains open. - Shared Storylet clients agree on recipe, phase, epoch, and completion. - Docking, RendezvousFrame, bridge, remote Cityform, and remote Traveler changes leave byte-identical local operator snapshots for identical declared local inputs. ### Exclusions No private refinement delivery or permanent global coordinates. ### Rollback boundary Station-only authenticated presence remains available if docking disables. ## M7: certification and release slice ### Scope - Complete HLOD, streaming stress validation, visual baselines, network fault injection, long-session resource testing, accessibility, security, privacy, Storylet replay, and documentation. M7 reruns the already required M6 coordinate suite under release load; it does not introduce the coordinate policy after docking exists. ### Deliverables - Release candidate vertical slice. - Performance and visual evidence. - Security and privacy receipts. - Accessibility report. - Architecture import checks. - Operational documentation. ### Gate - The approved 60 Hz target passes on reference hardware. - GPU memory and resource counts plateau under repeated streaming. - Public/private isolation passes. - First-person legibility passes at supported resolutions and DPRs. - Operations camera, minimap, zone selection, semantic mirror, owner-private indicator, transition comfort, and connected-content isolation pass at supported resolutions and DPRs. - Reduced motion, high contrast, keyboard/gamepad, captions, and semantic mirror pass. - Device loss during arrival or bridge state creates no duplicate entity. - Exclusion evidence confirms that only explicit exclusion assertions name The First Shard and no source, test, documentation content, design, scan result, or dependency from it exists in the Realm package. ### Exclusions All features listed in the deferred scope remain excluded from V1. ### Rollback boundary Each optional presentation tier can disable independently while preserving authoritative state and the baseline renderer. ## Deferred roadmap - Capability-scoped remote interior refinements. - Remote exact-source reveal after irreversible-disclosure review. - Multi-city and group rendezvous. - MLS-style group epochs. - Permanent global spatial authority. - User-supplied remote visual assets under a separate sandbox contract. - Zero-knowledge correspondence proofs. - Native whole-PC adapters. - External network visualizations such as ICP. - VR support. - Any remote, shared, spectator, fleet, group, or connected-Cityform overview; V1 Operations View is exactly one local owner and one local Cityform. ## Approval model Every milestone requires: 1. Contract approval. 2. Implementation approval. 3. Test evidence. 4. Security and privacy review where authority or disclosure changes. 5. Documentation update. 6. Session Memory update. Passing a milestone authorizes the next milestone's planning. It does not silently authorize deferred features. ## See also - [The Virtual Realm](index.md) - [Architecture and ownership](architecture.md) - [Playground clean-room foundations](playground-clean-room-foundations.md) - [Contract catalog](contracts.md) - [Security and privacy](security-privacy.md) - [Certification plan](certification-plan.md)