---
title: RealmForge v2 Workbench
description: Build reusable assets and product-level construction assemblies in the source-authoritative RealmForge v2 workbench.
audience: asset authors, simulation developers, AI-tool integrators, and security reviewers
updated: 2026-09-03
---

# RealmForge v2 Workbench

RealmForge is the default WebGPU OS workbench for `.proasset` 2.0.0 assets. Its
template-first workflow builds furniture, vehicles, characters, and buildings
from reusable semantic parts. It also combines an editable SystemGraph,
Engine-backed preview adapters, guarded AI operations, and trusted artifact
publication. This guide is for asset authors, simulation developers,
AI-tool integrators, and security reviewers. (Sources:
`webgpu-os/apps/realmforge/manifest.json`;
`webgpu-os/apps/realmforge/factory.js`;
`webgpu-os/apps/realmforge/document/constants.js`.)

## Open the v2 workbench

Launch **RealmForge** from the WebGPU OS app catalog. A true first launch creates
`/user/projects/realmforge/getting-started.proasset` from `Room.ChairDemo` and
enters the Modeler workbench. RealmForge restores a verified active document on
later launches. A recovery state takes precedence and opens the Recovery view.
(Source: `webgpu-os/apps/realmforge/factory.js`.)

Asset Home is an explicit library surface, not a first-launch gate. Select
**Library** in the workbench to create another asset, open a v2 asset, reopen a
recent asset, or preview a v1 migration. New and migrated documents enter the
Modeler only after their durable root reopens with the expected semantic
content hash. There is no v1 authoring workbench in the launch path. (Sources:
`webgpu-os/apps/realmforge/factory.js`;
`webgpu-os/apps/realmforge/modeler/ui/ModelerPanel.js`;
`webgpu-os/apps/realmforge/ui/RealmForgeStartView.js`;
`webgpu-os/apps/realmforge/document/lifecycle/RealmForgeActiveDocument.js`.)

## Author a `.proasset` 2.0.0 document

RealmForge v2 uses `realmforge.proasset` with version `2.0.0`. The root manifest
references versioned resources by stable IDs, hashes, logical paths, authority,
and explicit entry points. Supported entry points are `assembly`,
`systemGraph`, and `defaultScenario`. Resource authority is one of `authored`,
`baked`, or `external-pinned`. (Sources:
`webgpu-os/apps/realmforge/document/constants.js`;
`webgpu-os/apps/realmforge/document/validation/ProAssetV2Validation.js`.)

Create a basic asset:

1. Open RealmForge. A first launch enters the integrated Getting Started
   workbench; a later launch restores the verified active asset.
2. Select **Library** when you want a different starting point. Asset Home
   immediately previews the first usable template in the same browsing
   workspace.
3. Browse or search until the integrated preview shows the desired starting
   point. Accept or edit the generated asset name and canonical slug.
4. Select **Use as New Asset**. RealmForge prepares and validates the candidate
   before publishing a root.
5. Edit ForgeSource, resource properties, or SystemGraph nodes in the Modeler.
6. Save. RealmForge serializes the semantic transaction, publishes resources,
   then publishes the root manifest last.

Document changes pass through one queued `RealmForgeDocumentStore`. Content
hashing excludes incidental timestamps and logical paths while retaining
resource identity, entry points, semantic JSON, and binary hashes. Persistent
history records forward and inverse transactions, so undo and redo survive a
reload. (Sources:
`webgpu-os/apps/realmforge/document/store/RealmForgeDocumentStore.js`;
`webgpu-os/apps/realmforge/document/hash/RealmForgeContentHash.js`;
`webgpu-os/apps/realmforge/document/history/RealmForgePersistentHistoryContracts.js`.)

Verified recipes do not replace `.proasset` authority. They bind four separate
immutable roots around it: `designRoot` identifies the selected design,
`evidenceRoot` identifies measurements and attestations, and `releaseRoot`
binds the exact design, evidence, dependencies, tools, policies, and validation
receipts. Runtime checkpoints remain transient unless an explicit evidence
capture records them. Resolution is ordered from the source snapshot through
approved corrections, selected configuration, instance overrides, compiled
projections, and finally transient runtime state. Derived or runtime facts
cannot promote themselves into design, regulatory, or as-built truth.
(Sources:
`webgpu-os/apps/realmforge/verified/RealmForgeVerifiedRecipeContracts.js`;
`webgpu-os/apps/realmforge/verified/RealmForgeEvidenceContracts.js`;
`webgpu-os/apps/realmforge/verified/RealmForgeLayerContracts.js`;
`webgpu-os/apps/realmforge/verified/RealmForgeReleaseContracts.js`.)

Verified capabilities enter the workbench through one source-bound rollout
registry. Its eleven phase flags default to off. Enabling a phase requires a
passed gate receipt bound to the exact source revision, source content hash,
runtime `planHash`, and rollout revision. Asset Home, Studio facets, and direct
template/package actions all re-authorize against the current binding, so a
stale or mismatched request fails closed instead of bypassing the gate. Legacy
compatibility cards and the Getting Started asset remain available, and a flag
change never migrates a saved document. (Sources:
`webgpu-os/apps/realmforge/rollout/RealmForgeVerifiedRealityRollout.js`;
`webgpu-os/apps/realmforge/catalog/RealmForgeLibraryEntryFacade.js`;
`webgpu-os/apps/realmforge/modeler/session/ModelerSession.js`.)

## Navigate the Modeler

The Modeler owns one semantic document and projects it into coordinated views.
Workspace layout, Focus Mode, and selection stay separate from semantic
history. The default shell keeps a searchable Add/Structure browser, a dominant
viewport, one contextual inspector, and a collapsed AI Echo prompt. Utility
surfaces remain closed until the user requests them. (Sources:
`webgpu-os/apps/realmforge/modeler/ui/ModelerPanel.js`;
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeWorkbench.js`;
`webgpu-os/apps/realmforge/modeler/workspace/RealmForgeWorkspaceContracts.js`.)

| Mode | Purpose |
| --- | --- |
| Build | Assemble parts, edit parameters, and inspect compatible sockets. |
| Construct | Generate product-level patterns, inspect the BOM, and play the construction plan. This mode appears only for construction content. |
| Animate | Edit and preview animation when a rig or animation resource exists. |
| Simulate | Run supported physical or behavioral resources. |
| Review | Inspect validation, revisions, provenance, BOMs, and exports. |
| Advanced | Open SystemGraph, source evidence, and developer diagnostics. |

The mode resolver derives availability from document resources. Focus Mode
dims unrelated installed pieces and exposes compatible unoccupied sockets. It
does not write a semantic transaction. Large construction hierarchies group
content by storey, system, element, pattern, and product. Individual pieces
load only for an expanded page, search result, selection, or damage state.
(Sources:
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeModeAvailability.js`;
`webgpu-os/apps/realmforge/modeler/viewport/RealmForgeSemanticFocusProjection.js`;
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeConstructionHierarchyProjection.js`.)

The **Project** control opens one searchable project navigator inside the 3D
viewport. Its virtualized rows can select semantic parts and resources while
assembled, exploded, and isolate presentations keep the complete asset in
spatial context. Search, scrolling, callout placement, input focus, and
presentation transforms remain workspace state; they never enter ForgeSource
or document history. The viewport uses the shared Engine render-surface path,
and a semantic DOM mirror preserves keyboard and assistive-technology access.
(Sources:
`webgpu-os/apps/realmforge/modeler/viewport/RealmForgeViewportProjectNavigator.js`;
`webgpu-os/apps/realmforge/modeler/viewport/ModelerViewport.js`;
`webgpu-os/apps/realmforge/modeler/ui/ModelerPanel.js`.)

Asset compilation publishes ordered, monotonic loading checkpoints instead of
blocking the shell until the complete projection exists. The viewport can
reveal completed batches with its optional energy-print presentation while
identity and document authority remain unchanged. Each stage emits structured
counts and duration data to the browser console. **Copy Diagnostic** produces
one bounded, redacted report containing renderer, batching, loading, and
last-good state without copying source bytes or user content. (Sources:
`webgpu-os/apps/realmforge/modeler/session/RealmForgeLoadProgress.js`;
`webgpu-os/apps/realmforge/modeler/session/ModelerSession.js`;
`webgpu-os/apps/realmforge/modeler/ui/ModelerPanel.js`.)

The responsive shell keeps stable pane ownership while changing full,
overlay, and compact-tab presentation modes. Keyboard focus, reduced motion,
and hidden-pane availability are expressed through semantic DOM and ARIA
state. (Sources:
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeWorkbench.js`;
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeWorkbenchStyles.js`.)

## Start from Asset Home

Asset Home is a thumbnail-first library. Search can cross labels, categories,
capabilities, sockets, parameters, and supported actions. The nine primary
categories are Examples, Furniture, Vehicles, Characters, Construction
Materials, Stock Products, Construction Patterns, Assemblies, and Buildings.
The legacy flipper, tree, and crate remain available as compatibility
templates. (Sources:
`webgpu-os/apps/realmforge/catalog/RealmForgeLibraryEntryFacade.js`;
`webgpu-os/apps/realmforge/ui/RealmForgeStartView.js`;
`webgpu-os/apps/realmforge/ui/RealmForgeTemplateThumbnail.js`.)

Asset Home selects the first usable template by default and renders its version,
parameters, capabilities, sockets, readiness, generated thumbnail, and primary
action in one persistent preview pane. Selecting another card updates that pane
without navigation or document mutation. At widths below 900 pixels the same
preview becomes an inline region instead of a separate route. RealmForge also
generates an editable name and canonical slug from the selected template, so
**Use as New Asset** can proceed directly. Insert into Current Asset uses the
guarded package or construction template transaction when that entry supports
insertion. (Sources:
`webgpu-os/apps/realmforge/catalog/RealmForgeLibraryEntryFacade.js`;
`webgpu-os/apps/realmforge/ui/RealmForgeStartView.js`;
`webgpu-os/apps/realmforge/ui/RealmForgeAppStyles.js`;
`webgpu-os/apps/realmforge/packages/RealmForgePackageCompiler.js`;
`webgpu-os/apps/realmforge/construction/RealmForgeConstructionDocumentProjection.js`.)

## Compose reusable packages

RealmForge uses content-addressed `realmforge.module-package@1.0.0` and
`realmforge.template-package@1.0.0` records. Module packages own reusable parts,
slots, resources, parameters, and one-level variants. Template packages pin
their dependencies and compose module instances, bindings, attachments, and an
optional SystemGraph. An upgrade requires a separate preview and apply step.
(Sources:
`webgpu-os/apps/realmforge/packages/RealmForgePackageContracts.js`;
`webgpu-os/apps/realmforge/packages/RealmForgePackageRegistry.js`.)

Compilation expands one package through one guarded document transaction.
Generated resources retain `assembly.module-instance` provenance. Variant
resolution applies the base, then one named variant, then instance overrides.
Variant-of-variant chains fail validation. (Sources:
`webgpu-os/apps/realmforge/packages/RealmForgePackageCompiler.js`;
`webgpu-os/apps/realmforge/modeler/session/ModelerSession.js`.)

The verified runtime compiler resolves packages and document resources into one
immutable `RecipeRuntimePlan`. Its projections share one interface network,
compact semantic instance set, stable picking map, semantic connectivity,
rigid-cluster graph, moving-constraint graph, renderer batches, physics plan,
domain solvers, procedures, BOM, and validation targets. A single `planHash`
binds those projections. Plans are capability-keyed caches, not editable
authority. Domain-pack manifests register bounded schema, adapter, solver,
export, and test surfaces without allowing package JavaScript or creating a
second global registry. (Sources:
`webgpu-os/apps/realmforge/modeler/runtime-plan/RealmForgeInterfaceNetwork.js`;
`webgpu-os/apps/realmforge/modeler/runtime-plan/RealmForgeInterfaceNetworkAdapters.js`;
`webgpu-os/apps/realmforge/modeler/runtime-plan/RealmForgeSemanticInstanceSet.js`;
`webgpu-os/apps/realmforge/modeler/runtime-plan/RealmForgeDomainPackManifest.js`;
`webgpu-os/apps/realmforge/modeler/runtime-plan/RealmForgeRecipeRuntimePlan.js`.)

## Describe recipe asset anatomy

Reviewed modular recipes use a shared component anatomy. It prevents a recipe
from flattening primary solids, mechanisms, connection media, accessories, and
appearance into an ambiguous parts list.

| Role | Requirement | Meaning |
| --- | --- | --- |
| `body` | Required | Closed solids that establish shape, mass, support, collision, and stable identity. |
| `interface` | Required | Sockets, holes, contact patches, insertion volumes, clearance envelopes, and replacement boundaries. |
| `functional` | Derived | Mechanisms, rigs, sensors, storage, and other capability-bearing systems. |
| `connector` | Derived | Fasteners, mortar, adhesive, weld, bearings, and other explicit joint products. |
| `attachment` | Optional | Replaceable accessories mounted through declared interfaces. |
| `finish` | Optional | Coatings, upholstery, glazing, and appearance overlays that preserve physical-material evidence. |
| `decorative` | Optional | Trim, badges, moldings, and seams that cannot satisfy physical readiness. |
| `behavior` | Derived | Animation, physics, vehicle, Life, interaction, or construction-task bindings. |

`Derived` means that the role becomes necessary when the requested capability
introduces it. It does not authorize a recipe to invent a connector or missing
evidence. The registry validates each role and includes the anatomy in both the
recipe resource and its AI Echo prompt fragment. (Sources:
`webgpu-os/apps/realmforge/recipes/ToolRecipeRegistry.js`;
`webgpu-os/apps/realmforge/recipes/RealmForgeRecipes.js`;
`webgpu-os/apps/realmforge/modeler/ui/ModelerPanel.js`.)

## Separate materials, products, and instances

A construction material describes a substance and its sourced properties. A
stock product describes reusable geometry made from that material. An instance
is one installed brick, board, sheet, connector, or other piece. RealmForge
does not infer engineering values from appearance presets. Missing evidence
blocks only readiness that needs that evidence. (Sources:
`engine/assets/material/composite/ConstructionCompositeMaterialCatalog.js`;
`webgpu-os/apps/realmforge/material/RealmForgeMaterialContracts.js`;
`webgpu-os/apps/realmforge/construction/ConstructionStockProducts.js`.)

Use **New Material** to create an overlay from a catalog substance. Appearance
changes and unsourced values remain visibly authored estimates. Use **New Stock
Product** to choose its form, metric dimensions, tolerances, material,
orientation, cut behavior, collider, and canonical sockets. Both workflows
commit through one guarded history transaction. (Sources:
`webgpu-os/apps/realmforge/modeler/ui/RealmForgeMaterialStockAuthoring.js`;
`webgpu-os/apps/realmforge/modeler/session/ModelerSession.js`.)

Procedural finish resources generate content-addressed, tileable base-colour,
normal, metallic, roughness, and occlusion maps from registered deterministic
generators. A finish overlay references a physical material; it never copies
or completes missing physical evidence. The viewport binds generated normal
maps through its shared material projection. (Sources:
`engine/assets/material/procedural/ProceduralPbrTexture.js`;
`webgpu-os/apps/realmforge/material/RealmForgeProceduralPbr.js`;
`webgpu-os/apps/realmforge/modeler/viewport/ModelerViewport.js`.)

Repeated fired-clay and mineral products also receive a stable per-instance
tint and roughness offset from their semantic identity. This appearance-only
variation keeps brick and mortar from looking cloned without changing
dimensions, contact, mass, sourced material evidence, batch membership, or draw
count. The same stable ID reproduces the same finish after reload. (Source:
`webgpu-os/apps/realmforge/modeler/viewport/ModelerViewport.js`.)

Expanded stock products can declare box, sphere, capsule, and convex-envelope
colliders. They can also declare sourced net volume and mass, running-clearance
envelopes, tool-gated insertion volumes, and named physical slots. The runtime
uses net volume for density-derived mass instead of treating every collider
envelope as solid material. (Sources:
`webgpu-os/apps/realmforge/construction/ConstructionResources.js`;
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeConstructionPresetPhysics.js`.)

ForgeSource is not limited to cuboids. Its registered primitive set includes
box, tapered box, sphere, cylinder, hollow cylinder, cone, capsule, torus, and
plane. `tapered-box` adds `topWidth`, `frontInset`, and `rearInset` while keeping
deterministic geometry keys and validated positive profiles. Compilation and
runtime projection reuse registered production geometry generators instead of
accepting package-supplied JavaScript. (Sources:
`webgpu-os/apps/realmforge/modeler/lang/ForgeSource.js`;
`webgpu-os/apps/realmforge/modeler/compile/AssemblyCompiler.js`;
`webgpu-os/apps/realmforge/modeler/adapters/RealmForgeCoreAdapterRuntime.js`.)

## Build and play construction assemblies

`assembly.modular@1.0.0` stores compact logical product instances and joins.
Stable IDs derive from pattern identity, role, and logical coordinates instead
of loop order. Pattern resources cover running and stack masonry bonds, stud
walls, joist grids, rafter runs, sheet grids, and beam grids. Openings generate
the affected cuts and framing instead of acting as viewport-only holes.
(Sources:
`webgpu-os/apps/realmforge/construction/ConstructionResources.js`;
`webgpu-os/apps/realmforge/construction/ConstructionPatterns.js`.)

Construct mode plays the same deterministic task plan that `Human.Basic` can
consume. Tasks express stock requirements, dependencies, placement frames,
capabilities, connections, and temporary support. The BOM reports counts,
lengths, areas, volumes, resolved masses, waste, product and material hashes,
and one deterministic result hash. (Sources:
`webgpu-os/apps/realmforge/construction/runtime/ConstructionPlanPlayback.js`;
`webgpu-os/apps/realmforge/construction/runtime/ConstructionPlanBridge.js`;
`webgpu-os/apps/realmforge/modeler/character/RealmForgeHumanContracts.js`.)

Installed pieces keep semantic identity while rendering in prototype batches.
Construction joins form adaptive connectivity islands. Added joins merge
islands. Removed joins recompute only the affected region. Detached regions
project to one compound dynamic body when the public physics capability is
available. (Sources:
`webgpu-os/apps/realmforge/construction/runtime/ConstructionInstanceBatchPlan.js`;
`webgpu-os/apps/realmforge/construction/runtime/ConstructionIslandGraph.js`;
`webgpu-os/apps/realmforge/construction/runtime/ConstructionPhysicsProjection.js`.)

Large deterministic house generation runs in a dedicated module worker while
the shell continues to paint measured loading stages and accept input. The
worker imports the pure construction transaction boundary rather than the
physics-dependent document projection. Its release closure is audited exactly:
a missing dependency, an unreviewed extra dependency, or changed module bytes
fails packaging and origin verification. This keeps the construction worker
small and prevents the protected simulation implementation from entering its
dependency graph. (Sources:
`webgpu-os/apps/realmforge/construction/RealmForgeConstructionGenerationWorker.js`;
`webgpu-os/apps/realmforge/construction/RealmForgeConstructionGenerationClient.js`;
`webgpu-os/apps/realmforge/construction/RealmForgeConstructionDocumentTransaction.js`;
`bundler/site.py`; `bundler/origin_verifier.py`.)

Mesh, Voxel, SDF, and Nexel views consume the same stable semantic instance IDs and
prototype batches. Geometry is interleaved and validated once per prototype,
selection changes use uniforms instead of rewriting instance buffers, and
frame uniforms are uploaded as one slab. Strict cuboid voxel products use an
analytic projection; unsupported topology falls back without changing semantic
authority. The SDF view uses the public Engine `SDFBakeCompute` path to bake one
bounded `r32float` distance volume per geometry prototype, then raymarches all
matching instances in one prototype/material batch. SDF requires an initialized
WebGPU viewport, supports 16 to 40 cells per axis and at most 256 prototypes,
and fails closed to the last-good renderer. It derives material factors but does
not project UV textures. Projection caches are invalidated by content and
renderer state, so switching renderers does not regenerate unchanged products.
(Sources:
`webgpu-os/apps/realmforge/modeler/viewport/ModelerViewport.js`;
`webgpu-os/apps/realmforge/modeler/viewport/RealmForgeModularAssemblyViewportModel.js`;
`webgpu-os/apps/realmforge/modeler/viewport/RealmForgeVoxelViewportProjection.js`;
`webgpu-os/apps/realmforge/modeler/viewport/RealmForgeSDFViewportRenderer.js`.)

The runtime keeps semantic connectivity, rigid clusters, and moving
constraints separate. Fixed joins union only rigid regions. Runtime-policy
slots create public revolute constraints for swivels and wheels. Directly
constrained bodies suppress pair collision; a failed constraint rebuilds the
affected topology so detached bodies collide again. Bounded broadphase and
OBB/SAT review report required contact, permitted insertion, running-clearance
violations, and forbidden solid overlap. Readiness reports gravity, contact,
articulation, and sourced load-failure evidence separately. (Sources:
`webgpu-os/apps/realmforge/construction/runtime/ConstructionArticulationProjection.js`;
`webgpu-os/apps/realmforge/construction/runtime/ConstructionCollisionValidation.js`;
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeConstructionPresetPhysics.js`.)

The collision review is also the strict solid detector for installed products.
A bounded sweep-and-prune broadphase feeds a 15-axis OBB/SAT narrowphase. Solid
overlap fails unless exact joint and slot evidence classifies it as fastener
insertion, cast-in embedment, or an authored press fit. Insertion methods
require an explicit connector instance. Wood-to-wood welds fail, and mortar or
adhesive joins require an explicit material reference. Missing contact frames,
medium geometry, joint methods, or endpoint evidence remain diagnostics rather
than implicit permission. (Source:
`webgpu-os/apps/realmforge/construction/runtime/ConstructionCollisionValidation.js`.)

Validated mortar, adhesive, and weld joins can render as derived, filled
connection-media geometry. Standard, close, and high masonry detail project
the exact mortar gap with a distinct concave, V, grapevine, or flush filled
mesh. Pinned bond patterns restore joints compacted out of the fixed runtime
graph, while first-class weep vents keep their intentional head-joint openings
clear. Each proxy has a stable presentation ID, picks back to its semantic
connection, and joins a prototype batch by medium kind, shape, and tooling
profile. The cache does not add products, assembly instances, joins, or BOM
lines. Exact geometry that cannot be derived produces a visible diagnostic
instead of a guessed fill.
(Sources:
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeMortarDetailProjection.js`;
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeConnectionMediumProjection.js`.)

The optional structural result is a **Structural gameplay preview**. It uses
the public Engine structural solver, preserves authored mass and capacity
evidence, and fails closed when required evidence is missing. It is heuristic
and is not an engineering analysis. (Source:
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeStructuralGameplayProjection.js`.)

## Use the starter templates

The construction catalog includes `Chair.Basic` 1.1, `Chair.Office` 2.1,
`Room.ChairDemo`, `House.Small.Hybrid`, and `House.Small.LoadBearing`. The house
starters use a 6 by 8 metre footprint, 2.4 metre wall height, 30 degree gable
roof, one exterior door, and four windows. Bricks, boards, sheets, fasteners,
ties, openings, roof products, and other installed products remain separately
selectable. (Source:
`webgpu-os/apps/realmforge/construction/ConstructionExamples.js`.)

The immutable package registry retains `Chair.Office` 2.0, `Cart.Basic` 1.0,
and `Car.Sedan` 2.0 packages for exact saved references. Chair 2.1, Cart 1.1,
and Sedan 2.1 are additive pinned packages. Package versions never advance
implicitly. (Source:
`webgpu-os/apps/realmforge/packages/RealmForgeBuiltInPackages.js`.)

The broader library also includes `Cart.Basic` 1.1, `Car.Sedan` 2.1,
`Humanoid.Mannequin`, and `Human.Basic`. Vehicle rigs retain wheel, steering,
drive, braking, light, seat, and door roles. `Human.Basic` adds locomotion,
interaction sockets, sensors, inventory, carry capability, and bounded Life
state to the mannequin-derived actor. (Sources:
`webgpu-os/apps/realmforge/examples/RealmForgeMobilityCharacterExamples.js`;
`webgpu-os/apps/realmforge/modeler/vehicle/RealmForgeVehicleRigContracts.js`;
`webgpu-os/apps/realmforge/modeler/character/RealmForgeHumanContracts.js`.)

`Chair.Basic` compiles as one fixed gravity-ready cluster with fitted joinery.
`Chair.Office` remains one selectable asset while its seat, five caster forks,
and ten wheel cores retain explicit moving constraints. Its default 65 mm
twin-wheel casters expose a 50–80 mm range, separate glass-filled nylon cores
and polyurethane treads, running-clearance envelopes, press-fit stem evidence,
17 rigid clusters, and 16 public revolute constraints. `Cart.Basic` 1.1 uses a
profiled tapered chassis and bed, a capsule handle, reusable axle modules, and
four rotary wheel modules. `Car.Sedan` 2.1 uses a profiled tapered shell, hood,
trunk, and cabin while preserving its stable body and wheel-corner roles. Its
authoring basis is right-handed, Y-up, and +Z-forward; the Vehicle2 adapter
performs the basis conversion at the public physics boundary. The same
boundary configures and reads back PhysX Vehicle2 differential torque and
clutch-speed ratios before claiming exact FWD, RWD, or AWD readiness; a missing
ratio or validation method fails closed. (Sources:
`webgpu-os/apps/realmforge/construction/ConstructionExamples.js`;
`webgpu-os/apps/realmforge/examples/RealmForgeMobilityCharacterExamples.js`;
`webgpu-os/apps/realmforge/packages/RealmForgeBuiltInPackages.js`;
`engine/assets/vehicle/VehicleProfile.js`;
`engine/assets/vehicle/VehiclePublicRuntime.js`;
`engine/assets/vehicle/SedanProceduralModel.js`;
`webgpu-os/apps/realmforge/modeler/vehicle/RealmForgeVehicleRigContracts.js`.)

Both verified house projections include explicit 38 × 140 mm lumber, joist
hangers, rafter seats, truss clips, hurricane ties, angles, straps, blocking,
gussets, connector plates, matching nails and screws, and complete fascia,
soffit, gutter, and downpipe systems. Every roof coordinate resolves stable
compact connector and per-hole fastener identities with exact insertion
volumes and tool sets. Engineering, manufacturing, purchasing, installation,
service, and simulation BOM views derive from one pinned projection. Missing
connector capacities and jurisdiction evidence stay visibly unsupported; the
preflight never claims approval, compliance, or certification. (Sources:
`webgpu-os/apps/realmforge/construction/ConstructionStockProducts.js`;
`webgpu-os/apps/realmforge/construction/verified/RealmForgeVerifiedHousePhase8.js`;
`webgpu-os/apps/realmforge/construction/verified/RealmForgeVerifiedHouseSlice.js`.)

## Compile and simulate supported systems

Assembly compilation derives preview geometry from ForgeSource and shared
Engine primitives. SystemGraph compilation validates node types, typed ports,
rates, fan-in, cycles, resource bindings, and deterministic plan identity
before activation. A failed candidate leaves the previous compiled plan and
preview active. (Sources:
`webgpu-os/apps/realmforge/modeler/compile/AssemblyCompiler.js`;
`webgpu-os/apps/realmforge/modeler/system-graph/RealmForgeSystemGraphCompiler.js`;
`webgpu-os/apps/realmforge/modeler/runtime/RealmForgeRuntimeController.js`.)

RealmForge registers resource adapters for core assets, electrical systems,
reconstruction, rope, living growth, particles, MorphField, sensors,
telemetry, scenarios, cloth, soft bodies, wire systems, and audio patches.
Each adapter reports its actual capabilities. Unsupported activation,
snapshot, patch, bake, replay, GPU, or device operations fail explicitly; an
inspector-only resource never claims live runtime authority. (Sources:
`webgpu-os/apps/realmforge/modeler/adapters/RealmForgeAdapterRegistry.js`;
`webgpu-os/apps/realmforge/modeler/phase9/RealmForgePhase9ResourceAdapters.js`.)

The electronics domain pack reuses that same adapter and runtime-plan boundary
for boards, pads, vias, traces, zones, footprints, harness wires, splices,
shields, routed connections, bounded controller peripherals, and reduced-order
motors. Controller I/O is driven only by precompiled ForgeBehavior, uses a
seeded deterministic runtime, and crosses an explicit integer next-tick
feedback boundary rather than creating a hidden algebraic loop. Its validation separates
electrical-rule, physical-clearance, continuity, current, thermal, mechanical,
and evidence readiness. External comparison results can be attached as
evidence, but they do not become native simulation authority. (Sources:
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgeElectronicsDomainPack.js`;
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgeControllerIoContracts.js`;
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgePcbContracts.js`;
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgeHarnessContracts.js`;
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgeReducedMotorContracts.js`;
`webgpu-os/apps/realmforge/modeler/electronics/RealmForgeElectronicsValidation.js`.)

## Use guarded AI operations

RealmForge exposes read-only resources under `os.realmforge://` and registers
caller-scoped OS commands and tools. AI mutations use the same guarded session
transactions and persistent history as UI edits. The bridge checks the
expected document revision and content hash both before and after asynchronous
work. It does not expose JavaScript approval authority. (Sources:
`webgpu-os/apps/realmforge/modeler/ai/RealmForgePhase9AiCommandBridge.js`;
`webgpu-os/apps/realmforge/factory.js`;
`webgpu-os/apps/realmforge/modeler/script/RealmForgeJavaScriptApprovalRegistry.js`.)

Equivalent reconstruction edits now converge through the registered manual
`os.realmforge.resource.add` command and the command-backed AI
`applyTransaction` tool. They produce identical semantic operations, history
envelopes, resources, and deterministic content hashes. Route-owned provenance
remains deliberately distinct: the user and AI actors, transaction UUIDs, and
timestamps are not caller-selectable parity fields. Unknown provenance fields
are rejected by the closed AI mutation schema. (Sources:
`tests/realmforge/reconstruction-manual-ai-parity.test.js`;
`webgpu-os/apps/realmforge/modeler/ai/RealmForgePhase9AiCommandBridge.js`;
`webgpu-os/kernel/tools/ToolCallSchemaValidator.js`.)

RealmForge sends model execution to AI Echo. The first prompt for an asset opens
a linked AI Echo conversation under **RealmForge Contracts**. Later revisions
of the same asset continue that conversation. **New chat** creates another
linked conversation for the asset, while a different asset receives a separate
conversation. Durable AI Echo replies and run status return to RealmForge as
guarded events. A reply never applies a document mutation by itself. Both apps
use the neutral shared contract rather than importing each other. (Sources:
`webgpu-os/shared/realmforge-contracts/RealmForgeAIEchoContracts.js`;
`webgpu-os/apps/ai-echo/RealmForgeTaskHandoff.js` compatibility facade;
`webgpu-os/apps/ai-echo/factory.js`;
`webgpu-os/apps/realmforge/factory.js`.)

AI requests use `realmforge-ai-request-v1`. Reviewed proposals use
`realmforge-ai-proposal-v1` and bind the expected revision, content hash, and
`planHash`. Preview is read-only. Apply, Reject, and Revise remain explicit user
decisions. Apply executes one undoable `ModelerSession` transaction, and stale
proposals fail closed. (Source:
`webgpu-os/apps/realmforge/modeler/ai/RealmForgeAiProposalContracts.js`.)

Reviewed recipes are guidance, not capabilities. The current tool registry
must contain every referenced tool before a recipe can execute. Recipe access
does not grant file, script, storage, or simulation authority. (Sources:
`webgpu-os/apps/realmforge/recipes/ToolRecipeRegistry.js`;
`webgpu-os/apps/realmforge/recipes/RealmForgeRecipes.js`.)

Furniture, vehicle, roof, material, package, regeneration, validation, damage,
and repair recipes all begin with a non-mutating preview. A recipe preview
reports generated pieces, joins, rigid clusters, articulations, collisions,
BOM and mass deltas, performance cost, readiness, and affected stable IDs.
Only the normal guarded proposal path can apply the reviewed result. (Source:
`webgpu-os/apps/realmforge/recipes/RealmForgeRecipes.js`.)

## Publish artifacts with provenance

Exports capture their source from the active session instead of accepting a
caller-authored model or provenance record. RealmForge supports static mesh
artifacts, transform and skeletal/morph animation, topology bakes,
topology-changing frame sequences, telemetry traces, and checkpoints when the
selected source satisfies that mode's contract. (Sources:
`webgpu-os/apps/realmforge/export/RealmForgeSessionExport.js`;
`webgpu-os/apps/realmforge/export/RealmForgeArtifactExportPipeline.js`.)

Publication writes to an immutable destination, verifies artifact bytes, and
accepts only the storage layer's exact atomic commit evidence. The final
receipt binds the source head, selected resources, graph or compiled plan,
adapter versions, settings, migration and script evidence, artifact hashes,
and provenance. The encrypted receipt store is an append-only discovery index;
it cannot turn a completed artifact publication into a different authority.
(Sources:
`webgpu-os/apps/realmforge/export/RealmForgeArtifactProvenance.js`;
`webgpu-os/apps/realmforge/export/RealmForgeReceiptContracts.js`;
`webgpu-os/apps/realmforge/export/EncryptedReceiptStore.js`.)

Construction `.proasset` exports preserve packages, stable instance IDs,
patterns, joins, plans, provenance, and BOMs. glTF export uses
`EXT_mesh_gpu_instancing` when the target supports it and writes stable mapping
and BOM sidecars. Shared-node or flattened fallbacks remain deterministic. OBJ
and STL are flattened compiled artifacts; export does not write one resource
file per installed brick. (Sources:
`webgpu-os/apps/realmforge/construction/export/ConstructionStructuredExport.js`;
`webgpu-os/apps/realmforge/export/GLBWriter.js`.)

A reviewed release manifest can be signed only after its roots, dependency
locks, validation receipts, limitations, and readiness are internally
consistent. The release publisher delegates signing to the existing OS
identity service and requires persistent signing by default. Signing does not
self-approve, self-pin, or make a publisher trusted. The trust adapter verifies
certificate chains, expiry, rotation, revocation, pinning, and exact manifest
bytes through the OS trust store. Private package libraries store only verified
immutable releases and require explicit dependency-upgrade previews. (Sources:
`webgpu-os/apps/realmforge/release/RealmForgeReleasePublisher.js`;
`webgpu-os/apps/realmforge/release/RealmForgeReleaseTrustAdapter.js`;
`webgpu-os/apps/realmforge/release/RealmForgePrivatePackageLibrary.js`.)

## Migrate v1 without changing the source

The v1 reader is retained only as an explicit migration path. Preview reads,
validates, fingerprints, and summarizes the v1 source without writing. A
migration requires explicit confirmation and a separate unoccupied v2
destination. It archives every exact v1 source byte under the new asset's
migration evidence, publishes a copy-on-write v2 root, reopens that root, and
checks the prepared content hash before activation. The original v1 path is
never the publication root. (Sources:
`webgpu-os/apps/realmforge/document/migration/RealmForgeV1Migration.js`;
`webgpu-os/apps/realmforge/document/migration/RealmForgeV1MigrationContracts.js`;
`webgpu-os/apps/realmforge/document/lifecycle/RealmForgeActiveDocument.js`.)

Migration evidence includes the source root hash, exact archive hashes, a
migration manifest, a migration receipt, and a reference stored in the v2
document extension. This evidence makes rollback and independent recovery of
the original v1 bytes possible without rewriting them. (Sources:
`webgpu-os/apps/realmforge/document/migration/RealmForgeV1Migration.js`;
`webgpu-os/apps/realmforge/document/repository/RealmForgeRevisionRepository.js`.)

## Import source evidence through the Source Gateway

The Source Gateway is a guarded inspect, normalize, source-lock, candidate,
preview-diff, and apply pipeline. It preserves the exact supplied bytes and
never fetches referenced URIs or executes source code. Byte, nesting, time,
record, geometry, URI, and license budgets are checked before a candidate can
enter a document transaction. Preview is pure, and Apply requires its exact
preview token. Unchanged reimport produces an empty semantic diff; corrections
either rebase deterministically or remain explicit orphans. (Sources:
`webgpu-os/apps/realmforge/import/RealmForgeSourceGatewayContracts.js`;
`webgpu-os/apps/realmforge/import/RealmForgeSourceGateway.js`.)

Browser-native mesh import remains available. Bounded semantic adapters cover
neutral Fusion bundles, an explicit AP242 subset, an IFC semantic subset, IDS
requirements, and KiCad schematic and board records in that order. Each adapter
records source mappings, unsupported records, and semantic loss. Raw Fusion
archives and unsupported CAD entities remain unavailable unless an isolated
optional converter supplies a neutral content-addressed bundle; they never
become a RealmForge launch dependency. (Source:
`webgpu-os/apps/realmforge/import/RealmForgeSourceGatewaySemanticAdapters.js`.)

## Recover safely

RealmForge publishes manifests last. A missing or corrupt head can fall back to
the last verified commit without overwriting evidence. External clean changes
reload; external dirty changes enter an explicit conflict workflow. Immediate
close waits for queued persistence, and unmount closes the active view,
adapters, audio ownership, receipt store, registration scopes, listeners,
timers, and GPU projections. (Sources:
`webgpu-os/apps/realmforge/document/repository/RealmForgeRevisionRepository.js`;
`webgpu-os/apps/realmforge/document/recovery/RealmForgeRecoveryRepository.js`;
`webgpu-os/apps/realmforge/document/lifecycle/RealmForgeActiveDocument.js`;
`webgpu-os/apps/realmforge/factory.js`.)

ForgeSource and SystemGraph recovery use independent immutable heads. Exact
invalid source bytes and compiler-rejected graph candidates with their
diagnostics survive immediate full app teardown and fresh reopen while the
last-good semantic revision, content hash, preview, graph plan, and history stay
active. Rejected graph bytes participate in external-conflict identity and are
rebased into Save As, Save Copy, or Keep Mine destinations. An
`applied-unsaved` graph sidecar is never copied or replayed when the destination
semantic snapshot already contains that accepted graph change. Candidate graph
and diagnostic payloads are bounded before recursive normalization, and final
external replacement binds the exact graph-draft hash as well as its revision
and state. (Sources:
`webgpu-os/apps/realmforge/document/draft/RealmForgeSystemGraphDraftContracts.js`;
`webgpu-os/apps/realmforge/document/draft/RealmForgeCompositeDraftPersistenceCoordinator.js`;
`webgpu-os/apps/realmforge/modeler/session/ModelerSession.js`;
`tests/realmforge/invalid-draft-reopen.acceptance.test.js`.)

## Verify a release

Run the repository tooling from the repository root:

```bash
python bundle_engine.py --target webgpu-os --dry-run --no-site
python add_spdx_headers.py
python scripts/verify_realmforge_phase10_release.py
```

After source and curated documentation stop changing, regenerate and validate
the documentation from `MD/`:

```bash
python MD/tools/extract_api.py webgpu-os
python MD/tools/build_docs.py
python MD/tools/build_llms.py
python MD/tools/validate_docs.py
```

The complete release additionally requires a source-bound browser receipt,
zero high or critical Security Doctor findings, the full WebGPU OS bundle, and
the cumulative RealmForge verifier. A dry bundle or isolated unit test is not
release evidence by itself. (Sources: `webgpu-os/kernel/SecurityDoctor.js`;
`bundle_engine.py`; `scripts/verify_realmforge_phase10_release.py`.)

## Current boundaries

- Device-dependent audio and GPU presentation state are reconstructable, not
  document authority.
- Unsupported adapter capabilities remain explicit failures.
- Structural gameplay previews are heuristic and are not engineering analyses.
- Missing sourced material properties remain missing; appearance never satisfies
  physical or structural readiness.
- Exact FWD, RWD, and AWD simulation requires the public PhysX Vehicle2
  differential ratio and axle-validation surface. Missing methods or rejected
  readback leave simulation unavailable rather than falling back silently.
- JavaScript execution requires separate user-owned approval and is never an
  AI capability.
- Topology-changing growth cannot be labeled as ordinary GLB animation.
- Receipt discovery is not artifact publication authority.

(Sources:
`webgpu-os/apps/realmforge/modeler/phase9/RealmForgePhase9ResourceAdapters.js`;
`webgpu-os/apps/realmforge/construction/runtime/RealmForgeStructuralGameplayProjection.js`;
`webgpu-os/apps/realmforge/material/RealmForgeMaterialContracts.js`;
`webgpu-os/apps/realmforge/modeler/script/RealmForgeJavaScriptApprovalRegistry.js`;
`webgpu-os/apps/realmforge/export/RealmForgeSessionExport.js`;
`webgpu-os/apps/realmforge/export/EncryptedReceiptStore.js`.)

## Genesis Ecology expansion (planned)

RealmForge will author product and factory genomes, parts, interfaces,
developmental grammars, regulation, homeostasis, reaction ecology, role and
cultural topology, constructive operations, and audience-safe world bindings.
Candidates remain data-only until compiled, evaluated, externally authorized,
and atomically activated. Verified assemblies can be recursively packaged as
immutable parts. This M2+ expansion uses a separate domain pack and package
generation and does not reopen the accepted Virtual Realm M0-M1C boundary. See
[RealmForge Genesis Ecology](realmforge-genesis-ecology.md).

## See also

- [WebGPU OS Architecture](architecture.md)
- [App Catalog](app-catalog.md)
- [Security and Trust Model](../concepts/security-model.md)
- [Schema Evolution](../concepts/schema-evolution.md)
- [RealmForge Genesis Ecology](realmforge-genesis-ecology.md)
- [Virtual Realm RealmForge Bake Pipeline](virtual-realm/realmforge-pipeline.md)