---
title: Virtual Realm Architecture and Ownership
description: Flat peer modules, application composition roots, authority boundaries, local operations, records, stores, and dependency rules for The Virtual Realm.
audience: architects and implementers
updated: 2026-08-13
status: approved planning baseline
---

# Virtual Realm Architecture and Ownership

The Virtual Realm uses flat peer services with explicit, versioned contracts. Hierarchical world data remains a graph of stable IDs and edges. It never becomes recursively owned module state.

## Source-of-truth ownership

| Owner | Owns | Must never own |
| --- | --- | --- |
| RealmForge | Geography, visual grammar, materials, lighting intent, collision, navigation, station layout, bridge sockets, LOD rules, projection bindings, disclosure rules, and authored Storylet definitions | Live files, processes, peers, permissions, source bytes, or traffic |
| WebGPU OS | Filesystem, storage, processes, IPC, identities, capabilities, source bytes, and live metrics | Geometry, materials, or world composition |
| Virtual Realm runtime | Verified bake loading, ephemeral projections, ECS synchronization, grounded first-person play, owner-private local operations presentation, rendering, audio, and interaction requests | Editing RealmForge documents, granting permissions, exposing connected Cityforms in local operations, or becoming network authority |
| SecureMesh | Discovery, authentication, transport, routing, and content delivery | Station presentation or world rendering |
| Kernel and Realm Shield | Authorization, confinement, quotas, audit, and revocation | Trusting visible scenery as enforcement |
| Storylets | Deterministic presentation, explanation, proposals, waiting, and privacy-scoped replay records | Fabricating truth, direct system mutation, or authority grants |

## Composition roots

The architecture has one composition root for each independently started application.

### `RealmForgeBakeEntry`

`RealmForgeBakeEntry` receives RealmForge document services and compiler adapters. It constructs bake peers, orders pure compilation, publishes immutable artifacts, and disposes its resources. It never creates the live runtime.

### `VirtualRealmEntry`

`VirtualRealmEntry` receives Engine and WebGPU OS ports. It constructs runtime, projection, Storylet, and SecureMesh presentation peers. It controls startup and shutdown. It never imports RealmForge UI, modeler sessions, preview handles, or mutable document stores.

The composition roots may share contracts. They never instantiate or import one another.

### Clean-room Engine boundary

`VirtualRealmEntry` may receive selected public CSE/URC and State-First functions from the Engine namespace. It must validate and wrap them in Realm-owned adapters. It may not import any module under `tests/playground/`, resolve the Engine through globals or path probing, or adopt a demo fallback. The normative source-to-frame flow, exact adapter surface, lifecycle generation rules, truth-plane matrix, and audited source ledger are frozen in [Playground clean-room foundations](playground-clean-room-foundations.md).

The CSE-backed adapter supplies authority and causal-order evidence but does not replace the owning WebGPU OS, kernel, or SecureMesh service. The State-First adapter consumes `RealmDynamicStore` snapshots and returns presentation decisions but cannot create semantic state. Root Algebra remains an optional proof-gated M1 compiler optimization and is prohibited from runtime authority, disclosure, topology discovery, or post-publication bake mutation.

## Planned physical layout

Concern folders are namespaces only. They do not imply parent-child service ownership, automatic construction, or privileged inward imports.

```text
webgpu-os/apps/realmforge/virtual-realm/
  RealmForgeBakeEntry.js
  authoring/       thin RealmForge document and Classic Editor adapters
  compilers/       pure peer compilers, one responsibility per module
  publication/     closure, validation, receipts, immutable publication

webgpu-os/apps/the-virtual-realm/
  index.js         side-effect-free app export
  VirtualRealmEntry.js
  contracts/       one versioned contract per module
  observation/     narrow WebGPU OS and Realm Network ports
  projection/      pure domain projectors and delta reducer
  runtime/         stores, ECS synchronization, interaction, lifecycle
  code-matter/     local source port, vault, nonce, tokens, line stream, leases, private atlas
  rendering/       geometry, materials, glyphs, lighting, effects, visor
  experience/      first-person, local operations, minimap, audio, accessibility, presentation
  station/         SecureMesh state, public shells, rendezvous, bridges
  storylets/       catalog, scheduling, episodes, proposals, replay
  security/        validation, audience filtering, epochs, cleanup
  telemetry/       sanitized measurements and release evidence

tests/virtual-realm/
  contracts/
  bake/
  projection/
  code-matter/
  storylets/
  station/
  rendering/
  security/
  accessibility/
```

The implementation may split a concern folder when file count requires it, but it cannot introduce a nested runtime composition root, a manager tree, or a barrel module that secretly constructs peers. Cross-concern calls go through injected ports and immutable contracts.

## Dependency rules

1. A peer module never constructs another peer module.
2. A peer module never imports another peer's concrete implementation.
3. The composition root injects every concrete dependency.
4. A module consumes typed ports and immutable records.
5. A module exposes narrow lifecycle methods such as `start()`, `snapshot()`, `subscribe(listener)`, `apply(record)`, and `dispose()` only where its role needs them.
6. No service locator, global manager, singleton registry, or omnipotent event bus coordinates the Realm.
7. Runtime entities refer to other entities by stable IDs.
8. Filesystem hierarchy uses graph edges such as `parentId`, `contains`, and `mounts` rather than recursively owned objects.
9. Bake, observation, projection, Storylet, station, bridge, reveal, presentation, and telemetry channels remain distinct.
10. The renderer imports no WebGPU OS driver. WebGPU OS adapters import no renderer.
11. Production modules import no Playground demo, wrapper, WGSL, UI, camera, loader, or fallback code.
12. Engine capability is injected into `VirtualRealmEntry`; no peer reads `window.PE`, another loader global, or a mutable ambient module cache.
13. Presentation order cannot create a causal edge, and a State-First representation decision cannot change semantic existence, authority, disclosure, topology, collision, or navigation.
14. The grounded first-person and owner-private local operations controllers are separate flat peers. Only first person traverses; the operations controller consumes a structurally local-only snapshot and never imports station or remote-world state.

## Contract modules

Each contract lives in its own module. The architecture does not create one large `RealmContracts` file.

| Contract | Purpose |
| --- | --- |
| `AudienceClassContract` | Exact owner, public, refinement, rendezvous, bridge, replay, or preview audience |
| `DisclosureClassContract` | Local, public, refinement, forbidden, construct, or historical export classification |
| `ProvenanceClassContract` | Authored, observed, derived, or construct lineage |
| `EvidenceQualityContract` | Exact, measured, computed, estimated, unknown, or not-applicable quality |
| `AvailabilityStateContract` | Available, sealed, denied, partial, or absent access state |
| `FreshnessStateContract` | Current, stale, expired, or unknown freshness |
| `TemporalModeContract` | Live, historical, or preview time context |
| `AssertionStateContract` | Confirmed, proposed, or hypothetical assertion status |
| `ResourceReferenceContract` | Audience-scoped resource identity, content locator, length, kind, and dependencies |
| `RealmSafeTextContract` | Normalized non-executable remote names, signs, labels, captions, and anti-spoof metadata |
| `SignatureEnvelopeContract` | External signer, algorithm, audience, policy, lifetime, nonce, digest, and signature binding |
| `RealmScanScopeContract` | Pre-enumeration allow roots, opaque hard-deny subtrees, canonical containment, link policy, and operation limits |
| `RealmSourceSnapshotContract` | Immutable authorized compiler input, source generations, relationships, coverage, and scan scope |
| `RealmCoverageReceiptContract` | Requested, granted, denied, omitted, truncated, cancelled, freshness, and per-domain evidence-quality classification |
| `RealmAudienceSourceProjectionContract` | Independently authorized private, public, or refinement compiler input created before topology compilation |
| `RealmSpatialLayoutPolicyContract` | Root Spine, parcel subdivision, growth, HLOD, routing, clearance, incremental stability, and numeric identity |
| `RealmSpatialLayoutReceiptContract` | Node-to-cell and anchor map, routes, HLOD, relocation, collision, navigation, and deterministic layout evidence |
| `RealmTopologyNodeContract` | Stable audience-scoped semantic nodes |
| `RealmTopologyEdgeContract` | Typed containment, dependency, invocation, mount, route, guard, and attachment edges |
| `RealmGeometryResourceContract` | Bounded authored or compiled geometry resource |
| `RealmMaterialBindingContract` | Audience-safe material intent and binding |
| `RealmLightingIntentContract` | Semantic structural and activity-light intent |
| `RealmCollisionResourceContract` | Conservative collision solids and clearance evidence |
| `RealmNavigationResourceContract` | Walkable surfaces, portals, doors, and route links |
| `RealmSocketResourceContract` | Station, gate, bridge, refinement, and attachment sockets |
| `RealmLodResourceContract` | Far, mid, near, inspection, and HLOD records |
| `RealmProjectionBindingContract` | Semantic observation and delta bindings to stable anchors |
| `RealmGlyphStyleContract` | Sealed, structured, revealed, public, private, and historical glyph styles |
| `RealmAudioZoneContract` | Spatial emitters, reverb, occlusion, captions, and semantic audio zones |
| `RealmVisualBakeManifestContract` | Immutable package root, source projection, layout, compilers, closure, Storylets, compatibility, and signature |
| `RealmDependencyClosureContract` | Exact audience-specific sorted transitive resource closure and budgets |
| `RealmBakeReceiptContract` | Determinism, provenance, compatibility, privacy, validation, and publication evidence |
| `RealmTopologyChangeSetContract` | Bounded source-generation changes and deterministic coalescing boundary |
| `RealmBakeRequestContract` | Cross-root request for one fresh audience-specific immutable bake |
| `RealmBakeActivationOfferContract` | Verified candidate manifest, watermarks, compatibility, anchors, and budgets |
| `RealmBakeActivationReceiptContract` | Atomic prepare, commit, reject, cancel, or pre-commit rollback evidence |
| `PublicRealmShellManifestContract` | Strict signed public appearance, safe archetypes and text, expiry, and resource limits |
| `RealmAccessRefinementContract` | Audience, capability, expiry, epoch, and protected resource envelope |
| `RealmObservationContract` | Normalized source-owned facts independent of presentation geography |
| `RealmObservationSnapshotContract` | Source schemas, generations, watermarks, facts, omissions, and freshness |
| `RealmMetricValueContract` | Units, quality, sampling, quantization, and bounded metric evidence |
| `RealmFilesystemObservationContract` | Filesystem object, mount, move, revision, and coverage payloads without ambient paths |
| `RealmProcessObservationContract` | Process lifecycle and quality-labeled metric payloads |
| `RealmIpcObservationContract` | IPC channel topology and aggregate traffic without message content |
| `RealmSyscallObservationContract` | Post-kernel invocation lifecycle, authority receipt, result, safe metrics, and reason without arguments or payloads |
| `RealmStorageObservationContract` | Store lifecycle, usage, capacity, pressure, and operation-class payloads |
| `RealmPermissionObservationContract` | Authority decisions, policy revisions, expiry, revocation, and safe reason codes |
| `RealmNetworkObservationContract` | Authenticated route state and aggregate metrics without addresses or packets |
| `RealmStationObservationContract` | Discovery, identity, consent, safe text, shell, arrival, docking, epoch, and departure stages |
| `RealmCodeMatterObservationContract` | Descriptor, state, lease, chunk, expiry, and revocation events without plaintext |
| `RealmBootObservationContract` | Boot phases, service readiness, dependencies, degradation, and safe failure state |
| `RealmDeltaContract` | Immutable bake- and anchor-bound runtime projection change |
| `RealmEntityDeltaContract` | Runtime entity activation, update, staleness, absence, and deactivation |
| `RealmRouteDeltaContract` | Proposed, open, degraded, closed, or revoked route presentation |
| `RealmGateDeltaContract` | Locked, pending, granted, denied, expired, or revoked gate presentation |
| `RealmTrafficDeltaContract` | Bounded traffic presentation from cited metrics |
| `RealmStructureDeltaContract` | Stable-geometry activity, fracture, recovery, and availability presentation |
| `RealmCodeDeltaContract` | Lease-backed sealed, structured, and revealed Code Matter transition |
| `RealmPresentationDeltaContract` | Reversible presentation-command attachment, update, and removal |
| `RealmActionProposalContract` | Powerless typed interaction or Storylet request with idempotency and expected state |
| `RealmActionAuthorityReceiptContract` | Kernel or Realm Network allow or deny result bound to action, object, policy, and active epochs |
| `RealmActionResultContract` | Authoritative result observation that permits completed-success presentation |
| `CodeMatterDescriptorContract` | Audience-safe source object, metadata policy, revision, state, glyph, and capability binding |
| `CodeMatterVaultKeyEpochContract` | Non-secret local vault key identity, epoch, IV policy, status, and wrapping reference |
| `VaultNonceAllocationReceiptContract` | Atomic durable per-key IV-counter reservation and crash-recovery evidence |
| `CodeRevealLeaseContract` | Object, revision, authority, visible range, active epochs, and expiry |
| `CodeMatterChunkContract` | Lease-bound exact ranges, encryption envelope, IV receipt, commitment, and private digest |
| `PresenceBeaconContract` | Signed rate-limited public identity reference, shell, protocols, intent, and expiry |
| `PresenceSessionContract` | Authenticated identities, mutual consent, safe shells, station scope, policy, expiry, and epoch |
| `RealmPoseContract` | Signed public Cityform pose inside a virtual or rendezvous frame |
| `TravelerAppearanceManifestContract` | Safe shipped-archetype Traveler appearance, safe name, expiry, and identity binding |
| `TravelerPresenceGrantContract` | Authentication, mutual consent, host scope, presence epoch, and conditional rendezvous or bridge scope |
| `TravelerMovementIntentContract` | Visitor locomotion request consumed by host collision, navigation, gate, and presence authority |
| `TravelerPoseContract` | Host-authoritative ordered bounded locomotion projection and correction |
| `RendezvousFrameContract` | Temporary federated coordinate frame, participants, interpolation, lifetime, and signatures |
| `DockingOfferContract` | Directional gates, route, action, active presence and rendezvous epochs, transcript, versions, offer and proposed-generation nonces, expiry, and signature |
| `DockingGrantContract` | Exact offer binding, strict directional capability intersection, scope, limits, transcript, policy, capability epoch, generation-nonce digest, and prospective bridge epoch |
| `BridgeRecipeContract` | Canonical endpoints, coordinates, safe archetypes, compiler, clearance, traversal, and epoch |
| `BridgeDigestContract` | Signed canonical semantic bridge-output agreement |
| `BridgeEpochContract` | Active grants, participants, keys, policy, start, end, and Chronicle generation |
| `RealmLogicalClockTickContract` | Logical tick, scope, term, participant set, and hash-linked shared timing |
| `RealmDeterministicRandomStreamContract` | Exact PCG semantic stream, purpose separation, draw index, and selection policy |
| `RealmStoryletCatalogContract` | Canonically ordered audience catalog, safe text, limits, policy, closure, and signature |
| `RealmStoryletInputSnapshotContract` | Audience-filtered canonical facts, watermarks, logical time, metric hysteresis, participants, policy, and active epochs |
| `RealmStoryletPolicyContract` | Trusted category, priority, presentation-channel, work, and safety ceilings |
| `RealmStoryletCoordinatorLeaseContract` | Mutually signed coordinator term, failover barrier, participant set, and split-brain evidence |
| `RealmStoryletDefinitionContract` | Declarative triggers, predicates, phases, scopes, proposals, safe text, and policies |
| `RealmStoryletDecisionContract` | Canonical candidate set, input snapshot, clock, random draw, tie-break, selection, and ordered zero-or-more proposal digests |
| `RealmStoryletProposalContract` | Bounded presentation or action-kind proposal, truth reference, termination, reversibility, and dependencies |
| `RealmStoryletActionCorrelationContract` | Storylet proposal and decision references correlated to the one generic Realm action and authority-receipt path |
| `RealmStoryletInstanceRecipeContract` | Shared definition, participants, clock, random stream, policy, channel reservations, and active epochs |
| `RealmStoryletInstanceHeadContract` | Persisted outer scheduler state, reservations, episode reference, coordination, interruption, recovery, and cleanup obligations |
| `RealmStoryletEpisodeHeadContract` | Data-only revisioned episode head bound to recipe, bake, policy, clock, and active epochs |
| `RealmStoryletPersistenceReceiptContract` | External encrypted compare-and-swap storage or restore evidence for an instance or episode head |
| `RealmPresentationCommandContract` | Typed reversible non-authoritative light, audio, particle, sign, actor, glyph, route, and visor command |
| `RealmChronicleEventContract` | Signed privacy-scoped semantic history with provenance, claim axes, parents, epochs, and receipts |
| `LocalOperatorViewPolicyContract` | Owner-private local Realm, approved first-person/isometric/eagle-eye modes, camera bounds, minimap limits, zone actions, and no-authority interaction rules |
| `LocalOperatorViewSnapshotContract` | Current authority-bound local view, private bake/layout, camera, admitted local cells/anchors/zones, and exact connected-content exclusion receipt |
| `LocalCityMinimapSnapshotContract` | Referentially closed local zones, routes, landmarks, bounds, cells, and exact connected-content exclusion receipt |
| `LocalZoneManagementProposalContract` | Powerless local-zone visibility, alert-threshold, or rebake request bound to the current operator view and authority preconditions |

The required fields and validation sequence are normative in the [contract catalog](contracts.md).

## RealmForge bake peers

The RealmForge application composes these peers:

- `RealmSourceAdapter`
- `RealmScanScopeVerifier`
- `RealmDisclosurePolicy`
- `RealmAudienceSourceProjectionBuilder`
- `RealmAudienceSourceProjectionValidator`
- `RealmAssetCatalog`
- `RealmEditorSceneAdapter`
- `RealmForgeMaterialPreviewAdapter`
- `RealmForgeTypographyPreviewAdapter`
- `RealmForgeVisorPreviewAdapter`
- `RealmForgeAccessibilityPreviewAdapter`
- `RealmTopologyCompiler`
- `RealmGeometryCompiler`
- `RealmMaterialCompiler`
- `RealmLightingCompiler`
- `RealmCollisionCompiler`
- `RealmNavigationCompiler`
- `RealmGlyphStyleCompiler`
- `RealmSocketCompiler`
- `RealmLodCompiler`
- `RealmProjectionBindingCompiler`
- `RealmAudienceBakeAssembler`
- `RealmDependencyClosure`
- `RealmStoryletAuthoringAdapter`
- `RealmStoryletCompiler`
- `RealmStoryletDependencyClosure`
- `RealmStoryletValidator`
- `RealmBakeValidator`
- `RealmBakePublisher`
- `RealmVisualQA`

`RealmBakePublisher` publishes supplied validated results. It contains no compiler or disclosure logic.

## WebGPU OS observation peers

WebGPU OS ports translate privileged services into bounded observations. They do not decide geometry or presentation.

- `BootObservationPort`
- `ProcessObservationPort`
- `FilesystemObservationPort`
- `StorageObservationPort`
- `IpcObservationPort`
- `SyscallObservationPort`
- `PermissionObservationPort`
- `NetworkObservationPort`
- `RealmIdentityPort`
- `RealmLinkPort`
- `ChroniclePort`
- `RealmContentPort`
- `BackgroundLifecyclePort`

Each observation port must provide sanitized immutable snapshots and ordered subscriptions. Raw paths or identities never leave the port when the requested audience lacks authority. `FilesystemObservationPort` owns hierarchy and mount facts while `StorageObservationPort` owns capacity, pressure, and operation-class facts; both receive the same canonical injected VFS/storage source generation and de-duplicate a source event before publication. `RealmContentPort` resolves only verified content-addressed bake, public-shell, and Realm resource records. It cannot request source bytes; exact local source ranges belong exclusively to `CodeMatterSourcePort`.

## Live projection peers

- `FilesystemProjector`
- `ProcessProjector`
- `BootProjector`
- `StorageProjector`
- `IpcProjector`
- `SyscallProjector`
- `PermissionProjector`
- `NetworkProjector`
- `CodeMatterProjector`
- `ProjectionDeltaReducer`
- `RealmTopologyChangeDetector`
- `RealmBakeRequestPort`
- `RealmObservationBuffer`
- `RealmReprojectionService`
- `RealmBakeTransitionReducer`
- `RealmDisclosureProjector`
- `RealmHistoricalWitnessProjector`

Each projector consumes one normalized observation family and emits `RealmDelta` records. A projector cannot render, grant authority, or call a privileged service.

## Runtime peers

- `RealmBakeVerifier`
- `RealmBakeLoader`
- `RealmEngineAdapter`
- `RealmStateFirstPresentationAdapter`
- `RealmStaticStore`
- `RealmDynamicStore`
- `RealmEcsSynchronizer`
- `RealmGeometryRenderer`
- `RealmMaterialSystem`
- `RealmGlyphRenderer`
- `RealmTypography`
- `RealmLighting`
- `RealmEffects`
- `RealmAudio`
- `RealmVisorOverlay`
- `RealmAccessibilityProjection`
- `RealmFirstPersonController`
- `LocalOperatorViewPolicyStore`
- `LocalOperatorViewProjector`
- `LocalOperatorCameraController`
- `LocalCityMinimapProjector`
- `LocalZoneSelectionStore`
- `LocalZoneManagementActionAdapter`
- `RealmCollision`
- `RealmNavigation`
- `InteractionResolver`
- `ActionDispatcher`
- `RealmTelemetry`

`RealmStaticStore` contains verified immutable authored resources. `RealmDynamicStore` contains current deltas and temporary presentation state. Neither store may silently rewrite the other.

`LocalOperatorViewProjector` receives an explicit owner-private read port over the verified local static and dynamic stores. It accepts only the active private bake, spatial-layout receipt, current operator authority, and admitted local cells. It never imports or queries `SecureMeshPort`, `PublicShellCache`, PresenceSession, RendezvousFrame, bridge, or Traveler peers. The same closed snapshot feeds the operations camera, minimap, local selection, object-ID, accessibility, and telemetry surfaces. Connected content is therefore unaddressable rather than hidden after rendering.

`LocalZoneManagementActionAdapter` produces a generic powerless `RealmActionProposalV1` from an accepted local-zone proposal. It cannot dispatch, authorize, mutate a zone, start RealmForge, or claim completion. Existing `ActionDispatcher`, authority receipt, authoritative observation, and delta peers remain the only result path.

`RealmEngineAdapter` is constructed once from explicitly supplied public Engine functions and immutable enum/version values. It exposes only source registration, per-frame update, bounded measurement snapshot, and idempotent disposal. `RealmStateFirstPresentationAdapter` owns each detach handle. Missing exports, incompatible versions, invalid modes, absent bridges, or source-registration failure produce explicit unavailable presentation; they never fall back while claiming State-First operation.

## Local Code Matter peers

- `CodeMatterSourcePort`
- `CodeMatterVault`
- `CodeMatterVaultNonceAllocator`
- `CodeMatterTokenizer`
- `CodeMatterLineStreamer`
- `CodeRevealLeaseTracker`
- `CodeMatterPrivateAtlasAllocator`

`CodeMatterSourcePort` is the only peer that requests exact bytes from the current WebGPU OS content authority, and it does so only for the exact object, revision, byte range, and capability receipt. `CodeMatterVault` owns local encrypted chunk storage and key epochs, while `CodeMatterVaultNonceAllocator` exclusively owns durable IV allocation. `CodeMatterTokenizer` creates lossless revision-bound token and line records. `CodeMatterLineStreamer` emits only the visible authorized chunks named by `CodeRevealLeaseTracker`. `CodeMatterPrivateAtlasAllocator` owns bounded private glyph pages and their disposal. The glyph renderer consumes verified instances but never opens source, grants leases, allocates nonces, or owns vault keys.

All V1 Code Matter peers are local and have no SecureMesh, station, docking, or remote-publication dependency. Remote exact-source delivery remains deferred; `RefinementReceiver` cannot route content into these peers under the V1 contract.

## SecureMesh station peers

- `SecureMeshPort`
- `StationEventAdapter`
- `StationStateReducer`
- `PresenceSessionReducer`
- `PresenceVerifier`
- `PublicShellVerifier`
- `PublicShellCache`
- `DockingProtocol`
- `BridgeRecipeCompiler`
- `BridgeDigestVerifier`
- `BridgeStateReducer`
- `RefinementReceiver`
- `RoutePresentationProjector`
- `TravelerAppearanceVerifier`
- `TravelerPresenceReducer`
- `TravelerMovementIntentPort`
- `TravelerMovementAuthority`
- `TravelerPoseProjector`

`StationEventAdapter` converts real SecureMesh events to typed station observations. It does not authenticate identities, open routes, grant capabilities, or render.

## Storylet peers

- `RealmStoryletCatalog`
- `RealmStoryletDefinitionValidator`
- `RealmStoryletTriggerEvaluator`
- `RealmStoryletCandidateIndex`
- `RealmStoryletScheduler`
- `RealmEpisodeRuntimePort`
- `RealmStoryletStateStore`
- `RealmStoryletPersistencePort`
- `RealmStoryletChronicleAdapter`
- `RealmStoryletProposalValidator`
- `RealmStoryletPresentationDispatcher`
- `RealmStoryletActionRequestPort`
- `RealmStoryletAuthorityPreconditionEvaluator`
- `RealmStoryletTruthReconciler`
- `RealmStoryletFailureCoordinator`
- `RealmStoryletMultiplayerSynchronizer`
- `RealmStoryletReplayReader`
- `RealmStoryletTelemetry`

The existing function-based `StoryletRuntime` remains useful for trusted authoring and local ambient integration, but it is an AI task-pipeline facade rather than a Realm world-state engine. The Virtual Realm uses the data-only episode pattern behind a narrow port, injects logical time and deterministic choice, and places proposal validation, authority, persistence, presentation, failure coordination, and Chronicle responsibilities in separate peers.

The composition root is the only module that connects those peers. The catalog does not own runtime state. The scheduler does not persist. Persistence does not evaluate triggers. Presentation does not authorize. The Storylet precondition evaluator only narrows eligibility and cannot issue authority receipts. Chronicle does not schedule. World projectors do not import or call Storylet modules.

## Interaction authority path

An interaction never calls an OS driver directly.

```mermaid
sequenceDiagram
  participant Traveler
  participant Resolver as InteractionResolver
  participant Dispatcher as ActionDispatcher
  participant Kernel as Kernel capability surface
  participant Projector as Domain projector
  participant World as Runtime presentation

  Traveler->>Resolver: interact with stable object ID
  Resolver->>Dispatcher: typed action proposal
  Dispatcher->>Kernel: capability-gated request
  Kernel-->>Dispatcher: confirmed success or denial
  Kernel-->>Projector: authoritative observation
  Projector-->>World: immutable RealmDelta
```

Visual changes that claim completion wait for the authoritative observation. A proposed operation may use an unmistakably provisional presentation while it waits.

## Explicit anti-patterns

- Do not extend `EngineBootstrap` into a Realm composition root.
- Do not add Realm-specific branches to the large `EntityMeshRenderer`, `VirtualGPU`, `StandardCameraController`, or `StandardInputController` modules.
- Do not create `RealmWorldManager`, `VirtualRealmManager`, `StoryletManager`, or another god object.
- Do not build a recursive `Realm -> City -> District -> Building -> File` ownership tree.
- Do not import RealmForge preview handles into the shipping runtime.
- Do not use the immersive desktop compositor as the world renderer.
- Do not use visual doors, tracks, or glyphs as security enforcement.
- Do not import `tests/playground/**` into production or release fixtures.
- Do not copy Playground WGSL, DOM/CSS, panel text, camera choreography, object placement, shader-generated graph topology, or animation constants.
- Do not ship orbit, director, detached-observatory, free-camera, debug-camera, analytic graph navigation, third-person Traveler, or any overview of a visited or connected Cityform. The independently authored bounded local Operations View is the sole non-first-person presentation and never controls traversal.
- Do not read Engine capability from `window.PE`, shared loader promises, asset-base globals, path-probing fallbacks, service locators, or another mutable global.
- Do not let a projection, belief, similarity score, rejected witness, Storylet, representation decision, or frame grant authority or claim completed success.

## See also

- [Contract catalog](contracts.md)
- [RealmForge bake pipeline](realmforge-pipeline.md)
- [World projection grammar](world-projection.md)
- [Local City Operations View](local-operator-view.md)
- [Storylets](storylets.md)
- [Playground clean-room foundations](playground-clean-room-foundations.md)
- [Security and privacy](security-privacy.md)