---
title: Virtual Realm RealmForge Bake Pipeline
description: Deterministic authoring, compilation, audience separation, dependency closure, publication, and runtime loading for RealmVisualBake artifacts.
audience: RealmForge developers, technical artists, architects, and security reviewers
updated: 2026-08-13
status: approved planning baseline
---

# Virtual Realm RealmForge Bake Pipeline

RealmForge is the authoring and compilation foundation for The Virtual Realm. It creates stable geography and presentation rules, then publishes immutable runtime artifacts. It never becomes the live world's authority.

## Authoring responsibilities

RealmForge authors:

- District and building grammars.
- Root Spine and SecureMesh Exchange layouts.
- Road, rail, bridge, gate, and portal sockets.
- Code Matter forms and glyph styling.
- Materials and semantic visual states.
- Lighting and atmosphere intent.
- Collision and navigation surfaces.
- Spatial audio and reverb zones.
- HLOD and public-shell archetypes.
- Projection bindings between semantic IDs and observation types.
- Disclosure classifications for every resource and field.
- Declarative Storylet graphs and their stable presentation anchors.

RealmForge does not author current process activity, current network peers, current permissions, or current source bytes. Those facts enter through WebGPU OS observation ports.

## Existing RealmForge foundations

`.proasset` v2 already distinguishes `authored`, `baked`, and `external-pinned` resources and validates explicit references (Source: `webgpu-os/apps/realmforge/document/constants.js`; `webgpu-os/apps/realmforge/document/validation/ProAssetV2Validation.js`).

`computeDocumentContentHash()` and `buildDocumentSnapshot()` provide sorted semantic identity independent of incidental paths and timestamps (Source: `webgpu-os/apps/realmforge/document/hash/RealmForgeContentHash.js`). The revision repository binds immutable trees, entry points, resource hashes, previous commits, and exact binaries (Source: `webgpu-os/apps/realmforge/document/repository/RealmForgeRevisionRepository.js`).

`AssemblyCompiler` derives geometry from semantic ForgeSource structures and Engine primitive generators (Source: `webgpu-os/apps/realmforge/modeler/compile/AssemblyCompiler.js`). The SystemGraph compiler validates phases, cycles, fan-in, rates, and deterministic compiler output (Source: `webgpu-os/apps/realmforge/modeler/system-graph/RealmForgeSystemGraphCompiler.js`). The material resolver binds a pinned catalog and produces stable resolution hashes (Source: `webgpu-os/apps/realmforge/material/RealmForgeMaterialResolver.js`).

These systems provide the foundation. They do not yet define a complete Cityform bake, audience separation, city-scale HLOD, or bridge attachment contract.

## Deterministic spatialization policy

`RealmTopologyCompiler` does not choose an arbitrary force layout. Every bake manifest binds `RealmSpatialLayoutPolicyV1`, whose exact compiler, numeric policy, input projection, and output digest make the city's geography reproducible.

### Coordinate frame and Root Spine

- Each audience-specific Cityform has a local right-handed metre coordinate frame.
- The Root Spine occupies the positive local Z axis from the origin. The SecureMesh Exchange receives the first fixed landmark cell beside the origin.
- Top-level territories attach to alternating Root Spine sides in canonical `(territoryKind, stableAudienceId)` order.
- The shipped Particle Realms public city reserves fixed landmark territories for Engine, Editor, Plauna, AGI, and WebGPU OS. Personal private roots use the same grammar without leaking into that public layout.
- Territory entries, transit stops, public gates, vertical datum, street widths, clearance classes, and bridge sockets lie on a quantized layout grid fixed by policy.

### Containment layout

1. Normalize the audience projection into typed nodes and edges.
2. Reject ambiguous containment. Every ordinary node has at most one containment parent; mounts and aliases use explicit non-owning edges.
3. Compute stable bottom-up weight from bucketed descendant count, authorized size class, semantic importance, and fixed minimum area. Exact private byte size never enters public layout.
4. Sort siblings by stable audience ID, never discovery order or current activity.
5. Assign each territory and district a deterministic rectangular macro-cell along the Root Spine.
6. Subdivide each macro-cell with a fixed-point slice-and-dice treemap whose axis alternates by depth and whose split arithmetic uses the bound integer layout grid.
7. Reserve deterministic growth cells and bounded slack after every sibling band. New children consume their parent's reserved cells in stable-ID order before any localized repack.
8. Represent shallow hierarchy as districts and parcels. Beyond the policy depth or node-count threshold, aggregate descendants into HLOD blocks with stable aggregate IDs, summarized bounds, count and weight buckets, and explicit partial or sealed state.
9. Compile buildings and Code Matter anchors inside parcels from semantic archetype, bucketed weight, minimum traversal clearance, and authored landmark overrides.

### Relationship route layers

Containment determines parcels and walkable local streets. Non-containment relationships never change ownership or parcel placement.

| Edge layer | Spatial treatment |
| --- | --- |
| Import and dependency | Non-traversable utility ducts routed through a deterministic service graph |
| Invocation, syscall, and event | Guarded local road, lift, or conduit overlays anchored to real endpoints |
| IPC | Traversable or visible internal streets only when the projection policy grants that affordance |
| Network | Station platforms, rail lines, ports, and horizon gates; never local IPC streets |
| RealmLink and bridge | Temporary epoch-bound sockets and bridge geometry outside stable containment layout |

- Directed relationships retain direction through lane, pulse, sign, and accessibility metadata.
- Strongly connected components are condensed into canonical route clusters for routing only; original nodes and edge directions remain inspectable.
- Parallel edges aggregate by registered relationship class and metric bucket at far LOD, then expand near the Traveler.
- Cross-links use deterministic orthogonal A* over a quantized routing grid with canonical neighbor order, fixed turn and crossing costs, reserved service layers, maximum search bounds, and stable tie-breaking.
- Road, rail, building, station, bridge-socket, vertical, and service-conduit clearance classes are hard constraints. An unsatisfied required route fails compilation; an optional route receives an explicit omitted receipt rather than intersecting geometry.
- Grade-separated crossings use policy-selected bridges or tunnels. At-grade intersections receive deterministic junction records, collision, navigation, signs, and visibility envelopes.

### Incremental stability

- Unchanged stable IDs retain territory, macro-cell, parcel, entrance, and landmark anchors while their reserved growth budget can absorb the change.
- Activity metrics never alter geography.
- A source rename that preserves authoritative object identity preserves the spatial anchor.
- A move between containment parents changes only the lowest layout region whose capacity cannot satisfy both old and new placements.
- When local capacity is exhausted, the compiler chooses the smallest deterministic ancestor that can repack, emits an explicit relocation set, and preserves all anchors outside that subtree.
- The bake activation protocol exposes old-to-new transition-anchor mappings and never interpolates collision or navigation between incompatible layouts.
- A policy or compiler version change is a new geography epoch and cannot masquerade as an incremental update.

### Audience independence

Private, public, and refinement topology compilers receive separate `RealmAudienceSourceProjectionV1` inputs and separate ID namespaces. They run the entire spatialization algorithm independently. Public form uses only explicit public weights, public archetypes, public reserved-growth policy, and public source revisions. No private coordinate, cell, tree depth, weight, route, cache entry, topology digest, or relocation set seeds a public or refinement layout.

An AccessRefinement overlays only at public refinement sockets declared in both the base shell and scoped projection. Its hidden internal layout is compiled independently inside the granted refinement envelope and does not reveal the corresponding private layout.

### Collision, navigation, and HLOD outputs

The compiler derives conservative collision solids, walkable navigation surfaces, portal and door links, route clearances, streaming cells, occlusion groups, semantic HLOD clusters, interaction anchors, audio zones, and public refinement sockets from the same quantized spatial records. These outputs have separate content IDs and validation receipts but cannot disagree on bounds, coordinate policy, or stable anchor identity.

## Classic Editor and Plauna adapter audit

The Classic Editor remains a source and preview adapter, not a second Realm authoring authority.

Useful existing boundaries include:

- `SceneManager.prepareSceneForImport()` validates and migrates before mutation, while serialization and deserialization cover hierarchy, imported models, render state, lighting, physics, audio, navigation, and bake references. A Realm scene adapter can wrap these records without exposing the Editor object graph.
- `AssetRegistry` catalogs texture, model, point-cloud, audio, script, prefab, scene, shader, data, and font records and provides bounded load entry points.
- `ModelImporter` already parses OBJ, PLY, STL, GLB, and glTF and resolves PBR materials, embedded textures, skeletons, morphs, and animations.
- `Viewport` provides proven camera, depth, picking, labels, bloom, tonemap, warm-up, and device-recovery precedents.
- Plauna provides design tokens, hybrid DOM and GPU surfaces, typography primitives, widgets, transitions, and reduced-motion hooks.

The adapter must also close these audited gaps:

- The asset catalog advertises FBX while the current model importer rejects FBX. Realm authoring supports only formats with a verified importer or an explicit trusted conversion receipt.
- Existing project export collection recognizes fewer resource fields than scene serialization. Realm dependency closure replaces that heuristic and must include imported meshes, embedded textures, materials, fonts, audio, Storylet assets, and every external resource.
- Scene resource discovery currently uses property-name heuristics for some UUID references. Realm contracts require typed resource handles.
- Object URLs need explicit owners and revocation. Mesh, texture, atlas, audio, listener, observer, and GPU resource lifetimes require disposal evidence.
- Current scene and registry writes do not establish the immutable publish-last transaction required for a Realm bake. The Realm publisher writes resources first and the root manifest last.
- `EditorApp` and `Viewport` are large coupled application modules. Realm runtime and compilers wrap narrow contracts rather than importing the whole Editor as a service locator.
- Existing draggable overlays and DOM listeners are prototypes, not certified Realm visor or accessibility surfaces.
- Existing fonts and text utilities do not provide the required complete MSDF atlas, fallback, shaping, protected-page, reveal-lease, eviction, and recovery lifecycle.
- Existing visual fixtures are useful precedents but do not replace the required viewport/DPR, contrast, privacy, and final-frame regression matrix.
- Existing assets require provenance, license, and disclosure review before inclusion in a public shell.

The flat authoring adapter peers are `RealmAssetCatalog`, `RealmEditorSceneAdapter`, `RealmForgeMaterialPreviewAdapter`, `RealmForgeTypographyPreviewAdapter`, `RealmForgeVisorPreviewAdapter`, `RealmForgeAccessibilityPreviewAdapter`, and `RealmVisualQA`. The shipping runtime separately owns `RealmMaterialSystem`, `RealmTypography`, `RealmVisorOverlay`, and `RealmAccessibilityProjection`. Only the appropriate application composition root binds either set to concrete Editor, Engine, or Plauna services.

## Artifact model

The existing `.proasset` document remains the authoring authority. A separate runtime schema avoids overloading its current `assembly`, `systemGraph`, and `defaultScenario` entry points.

### `RealmVisualBakeManifestV1`

`RealmVisualBake` is the immutable package. `PrivateRealmBake`, `PublicRealmShell`, and `AccessRefinement` are its three artifact variants. Every package is rooted by one `RealmVisualBakeManifestV1`, which binds:

- Bake format and semantic version.
- Variant identity.
- Audience-specific source projection revision and digest. The private receipt may retain the exact local document revision; transported manifests never expose a private-document digest.
- Topology hash.
- Disclosure-policy hash.
- Compiler, adapter, primitive-generator, and numeric-policy versions.
- Coordinate units and precision policy.
- Material-resolution hashes.
- Storylet catalog digest.
- Canonical dependency-closure hash.
- Renderer compatibility contract.
- Resource records and content IDs.
- Publisher identity and expiry where applicable, plus an external `SignatureEnvelopeV1` computed only after the manifest digest.

Seeded randomness alone does not prove deterministic output. The root binds every compiler and generator version that can alter results.

### Flat resources

The runtime consumes independent resources connected by stable IDs:

- `topology.realm`
- `geometry.realm`
- `material.realm`
- `lighting.realm`
- `collision.realm`
- `navigation.realm`
- `socket.realm`
- `lod.realm`
- `projection-binding.realm`
- `glyph-style.realm`
- `storylet-catalog.realm`
- `dependency-closure.realm`

Relationships such as containment, inheritance, attachment, routes, and parenthood remain graph edges. Runtime ownership remains flat.

`bake-receipt.realm` is deliberately not a bake resource. `RealmBakeReceiptV1` is external publication evidence created only after the manifest digest exists. It may be stored beside a publication, but the manifest, resource list, and dependency closure never reference or walk it.

## Audience source projections

Audience separation happens before topology, geometry, Storylet, or dependency compilation. `RealmAudienceSourceProjectionV1` is the only input accepted by an audience bake job.

- The `private` projection is built from the exact locally authorized `RealmSourceSnapshotV1` and remains local.
- The `public-shell` projection is built only from an explicit public appearance document, shipped public archetypes, public identity inputs, and public policy. The projection builder cannot read the private snapshot, private document digest, private counts, private timing, or private identifiers.
- An `access-refinement` projection is built in an isolated capability-scoped job from only the exact authorized resource scope, audience, policy, expiry, and epoch. It never receives the rest of the private snapshot.

All three jobs can use the same verified compiler implementations, but they share no topology, geometry, Storylet catalog, intermediate cache key, source digest, dependency closure, or output manifest. Cross-audience compiler caches are forbidden unless the cached input is itself a shipped public resource with the same public content ID.

## Compilation pipeline

```mermaid
flowchart TB
  privateSource[Authorized private snapshot] --> privateProjection[Private audience source projection]
  publicSource[Explicit public appearance inputs] --> publicProjection[Public audience source projection]
  refinementSource[Capability-scoped authorized inputs] --> refinementProjection[Refinement audience source projection]

  privateProjection --> privateCompile[Independent private compiler pipeline]
  publicProjection --> publicCompile[Independent public compiler pipeline]
  refinementProjection --> refinementCompile[Independent refinement compiler pipeline]

  privateCompile --> privateClosure[Private dependency closure and validation]
  publicCompile --> publicClosure[Public dependency closure and noninterference validation]
  refinementCompile --> refinementClosure[Refinement dependency closure and scope validation]

  privateClosure --> privatePublish[Immutable private publication]
  publicClosure --> publicPublish[Signed public publication]
  refinementClosure --> refinementPublish[Encrypted signed refinement publication]
```

The pipeline performs these stages:

1. Capture the private authorized `RealmSourceSnapshotV1` and `RealmCoverageReceiptV1` locally.
2. Build three separate `RealmAudienceSourceProjectionV1` inputs from their independently authorized source providers. The public provider cannot read private input.
3. Validate disclosure policy, audience namespace, source provenance, resource limits, and capability scope before any compiler runs.
4. Run separate topology compilers for private, public, and each refinement audience.
5. In each job, compile geometry, materials, lighting, collision, navigation, sockets, glyph style, LODs, projection bindings, and authored audio from only that job's topology.
6. In each job, compile declarative Storylet definitions and stable anchors from only that job's source projection.
7. Assemble each variant using only records produced in its own job and shipped public resources.
8. Compute a separate transitive dependency closure for each variant.
9. Reject missing, unlabeled, forbidden, cross-audience, ambient, unreachable, or foreign-job dependencies.
10. Validate determinism, schema limits, renderer compatibility, accessibility metadata, provenance, audience policy, and public noninterference.
11. Publish immutable resources first and the audience-specific root manifest last.

## Independent audience variants

### `PrivateRealmBake`

The private bake may contain exact authorized local topology, private labels and paths where policy permits them, projection bindings, Code Matter descriptors, local commitments, opaque vault object references, stable process and service anchors, and granted-mount topology. It stays local by default and never implies write authority.

The immutable bake never contains plaintext source bytes, decrypted chunks, reusable reveal leases, cryptographic keys, capability secrets, or live process state. Exact source stays in the authority-gated Code Matter vault and streams only through visible-chunk leases. Ordinary source edits can update the Code Matter descriptor and skin without rebaking stable geography; only structural topology or authored-form changes request a new bake.

The private compiler also emits a bounded local operations lookup resource containing canonical local zone, anchor, cell, landmark, route, and map-HLOD references. It is a dependency of the `PrivateRealmBake`, has its own content ID and closure, and is the only static source accepted by `LocalOperatorViewProjector` and `LocalCityMinimapProjector`. It contains no plaintext source bytes and does not create a fourth audience variant.

The local operations lookup never consumes `PublicRealmShell`, AccessRefinement, PresenceSession, RendezvousFrame, bridge, remote RealmPose, remote Traveler, or connected-Cityform input. Public and refinement compiler jobs cannot reference it. Runtime operations and minimap snapshots derive from this verified local lookup plus authorized owner-private deltas and admitted loaded cells; they never filter a mixed local/remote scene after compilation.

### `PublicRealmShell`

The public shell is a complete-looking public Cityform representation. It consumes only explicitly public inputs and safe owner-selected customization. It must not encode private file counts, sizes, names, types, adjacency, activity, ciphertext patterns, hashes, or update timing.

Public IDs are audience-scoped opaque IDs. They are not reusable private resource IDs. A signature proves what the owner published. It does not prove that the shell exactly reconstructs the private machine.

### `AccessRefinement`

An access refinement is independently compiled for one audience, capability set, expiry, and scope. It has its own dependency closure and encrypted content envelope. It cannot reference private resources outside the granted scope.

The first release defines this artifact contract but defers remote private-interior and exact-source refinement delivery.

## Disclosure classification

Every authored resource and source-derived field receives one classification:

- `local-private`
- `public-explicit`
- `capability-refined`
- `forbidden-export`
- `construct-only`
- `historical-reference`

Unlabeled content fails closed. The compiler never builds a private intermediate and filters it afterward. Post-hoc redaction risks retaining private topology, transitive dependencies, cache keys, digests, counts, and derived metadata.

The bake root binds the classification policy separately because current RealmForge document hashing intentionally excludes record authority. Geometry cannot be relabeled from private to public without changing policy evidence.

## Dependency closure

`RealmDependencyClosure` walks:

- `basedOn` relationships.
- Explicit resource references.
- Binary descriptors.
- Mesh and material records.
- Texture and atlas bindings.
- Shader and render-feature requirements.
- Collision, navigation, and socket records.
- Archetype and HLOD references.
- Storylet definitions, anchors, captions, audio, and presentation assets.
- Owner-private local operations lookup records used by the private bake only.
- Pre-manifest compiler identity records and immutable versioned compatibility profiles.

The closure sorts entries canonically and records the audience of every reachable resource. A public bake fails if any reachable record is private, unlabeled, capability-refined, or forbidden.

The walk explicitly excludes `RealmBakeReceiptV1`, signature envelopes, activation offers and receipts, validation reports produced after manifest digest, and any other transport or publication evidence whose preimage binds the manifest. Those records point to already computed content; content never points back to them.

## Runtime separation

`RealmBakeLoader` lives outside RealmForge. It receives only immutable bake contracts and Engine-facing adapters. It does not import:

- RealmForge UI.
- Document stores.
- Modeler sessions.
- Preview runtimes.
- Mutable native authoring handles.
- Classic Editor service objects.

Classic Editor scenes and asset catalogs may enter through explicit input adapters. They never become parallel Realm authorities.

## Publication and rollback

Publication writes immutable resources first and publishes the root manifest last. The mutable current pointer changes only after all resources and closures verify. Failed compilation or validation leaves the existing published root untouched.

Generated bakes are disposable. Rolling back a bake never mutates the `.proasset` source. A previous verified bake root can be reselected without rewriting its resources.

## Required gates

- Identical authorized inputs and compiler identities produce byte-identical manifests and canonical resource digests.
- Every reference resolves through the declared closure.
- Public output contains no private dependency reachability.
- Private-only changes leave byte-identical public manifests and canonical semantic-scene digests. Reference-renderer pixels stay within the frozen device, browser, driver, resolution, DPR, and tolerance profile; cross-GPU byte-identical raster output is not an authority requirement.
- Preview and runtime produce compatible source-ID, color, depth, and semantic anchor results.
- Every mesh, material, texture, glyph atlas, font, audio asset, Storylet asset, and shader requirement has provenance and a bounded lifetime owner.
- No mutable preview handle enters a bake.
- Invalid or incomplete publication leaves the prior root active.
- The private local operations lookup is referentially closed over local zones, anchors, cells, routes, landmarks, HLOD, and bounds and has no public, refinement, presence, rendezvous, bridge, Traveler, or foreign-Realm dependency.

## See also

- [Architecture and ownership](architecture.md)
- [Contract catalog](contracts.md)
- [Code Matter](code-matter.md)
- [Storylets](storylets.md)
- [Certification plan](certification-plan.md)