Explanation: The Project Graph

The Project Graph is the authoritative model of a project's worlds and resources. It is the durable, versioned, transactional heart of the engine: when you create an entity, attach a component, write a script, import an asset, or define a data store, you are adding a resource to the Project Graph. Everything you see in the editor, the renderer, the timeline, and the ontology view is a projection of this one model.

This page explains what the graph is, why a world in it is a persistent stateful environment rather than merely a renderable scene, and how change reaches it without ever bypassing the engine's single mutation authority.

What the Project Graph is

The Project Graph owns the durable world model: objects and resources, state, relationships, actions, scripts, workflows, policies, events, versions, and projections. From the platform ontology control-plane plan, the graph already carries "authoritative transactional edits, idempotency, revisions, resource versions, snapshots, and typed resource evaluation" — it is the right place the engine extends, not something to route around.

Resources live in the graph under resource kinds. The canonical project-graph verbs in the Action Catalog name them directly: worlds, entities, components, prefabs, scripts, assets, UI panels, and data stores. Each project.<kind>.create / .update / .delete verb is the surface over one resource kind:

• project.world.create — worlds (persistent environments).
• project.entity.create and project.entity.component.set — entities and their ECS component attachments.
• project.prefab.create — reusable entity templates.
• project.script.create and project.script.patch.apply — behavior resources (Script IR).
• project.asset.create — project assets, including spatial captures.
• project.ui_panel.create and project.data_store.create — UI and durable state resources.

The full, canonical list of verbs — with owners, exposure flags, and the HTTP/MCP/SDK surfaces they map to — is the generated Action Catalog. This page never restates that table.

Worlds are persistent stateful environments, not scenes

The most consequential idea in the Project Graph is its definition of a world. The ontology plan states the rule plainly:

World      = persistent stateful environment
Projection = one way to inspect or operate that environment

A world is not required to be a renderable 3D scene. The renderer is one projection, not the authority. A camera, spawn point, terrain, renderable entity, physics body, or scene exists only when a world declares a spatial projection that needs it. Valid worlds in the v1 ontology include spatial environments as well as abstract workflow worlds, simulations, digital twins, admin/UI systems, state machines, and spatial-and-operational worlds that mix both.

Treating a world as "just a scene" leads to false assumptions that the engine explicitly rejects:

• that drawing equals working — a scene can render while no player can spawn, possess an entity, or move (see Playability Proofs);
• that the client can edit freely — it cannot; edits are authoritative transactions, not local mutations (see Backend Authority);
• that nothing persists — the graph is durable and versioned; edits persist, and a world can be operated, inspected, replayed, and migrated, not just drawn.

Because the world is the authority and rendering is a projection, the engine forbids fabricating fake renderable scaffolding just to satisfy old "every world is 3D" assumptions. A world declares the projections it needs; the spatial projection is optional.

Projections are not the authority

Several surfaces read the Project Graph and present it. None of them owns it:

• the 3D renderer — for worlds with a spatial projection;
• the editor / inspector — the authoring view of resources and component fields;
• the timeline / replay — the execution and change history;
• the ontology graph — resources and relationships as a navigable graph;
• API / MCP tools and the AI context packet — machine-facing projections.

Each is one way to inspect or operate the environment. Editing a projection is really editing the underlying graph resource through a canonical action; the projection then re-derives from authoritative state. This is the same projection discipline that governs Script IR and its source/visual views: one canonical model, many views, no view that is secretly a second source of truth.

Resource kinds, revisions, and versions

The graph distinguishes several layers of identity and change, and keeping them separate is what makes the model safe to evolve:

• Resource kind — the type of a resource (world, entity, component, script, asset, prefab, UI panel, data store). Resource kinds are a closed, versioned enum; adding one is contract work across the snapshot schema, event types, operations, repository mapping, and generated clients, not an ad hoc field.
• Resource version — a per-resource version that advances as a resource's content changes (for example a script's IR version), giving each resource a stable lineage.
• Graph revision — a monotonic revision of the whole Project Graph. Transactions apply at a revision and advance it, which is how the engine detects conflicts and orders change. Mutation receipts record project_graph_revision_before and project_graph_revision_after, so every applied change is anchored to exact coordinates.

Resources also carry facets — identity, editor, and domain-specific facets — and worlds declare optional projections (spatial, workflow, UI, timeline, ontology). Facets and projections are how a single resource model serves many surfaces without any one surface owning the schema.

Transactions, idempotency, and receipts

Change reaches the graph as transactions, never as direct writes. A transaction is the unit of atomic, validated mutation: it applies at a known graph revision, is checked against the canonical schema, and either lands as a coherent whole or is rejected with a structured diagnostic.

• One authority. The canonical authority is the Project Graph service; the internal project.transaction.apply verb is workflow-exposed only, so no normal UI/AI/SDK surface hand-builds transactions. Creators and agents use the higher-level project.<kind>.* verbs and Script Semantic Patch, which the backend composes into transactions.
• Idempotency. Retry-sensitive mutations carry idempotency keys so a retried command does not double-apply and a mismatched retry is detected — the Stripe-style retry semantics the engine targets for normal mutating paths.
• Receipts. Applied mutations emit receipts with before/after coordinates. Script edits, for example, produce semantic-patch receipts recording revision-before/after, script-version-before/after, IR fingerprints, and the catalog hashes in force at authoring time — a Palantir-style inspectable audit trail linked from the execution timeline.

How you change it

You never write the graph directly. Changes apply through canonical actions in the project-graph domain (creating or updating a resource, setting a component on an entity, applying a script semantic patch), each of which the backend resolves into a validated transaction at a known revision. This is exactly what keeps a single mutation authority intact — see Backend Authority. The same path serves the human UI, MCP, the SDK, and AI, so no surface can mutate the world in a way another surface could not audit or reproduce.

How this is enforced

The Project Graph as control plane is the platform.ontology.control_plane row in the v1 feature ledger. Its claim is that "Project Graph, Action Catalog, Capability Registry, Workflow IR, Platform Catalog, and generated projections form one backend-authoritative platform control plane," and its required proof classes include schema, generated-docs, mutation-authority, version-coverage, and independent-audit. Like every row in the ledger today, it is unaccepted: the graph model is the engine's canonical design, and its proven-end-to-end status tracks the ledger rather than this prose.

Source

The authoritative world/resource model and the abstract-worlds projection rule come from docs/architecture/platform-ontology-control-plane-final-plan.md (Abstract Worlds And Projection Boundaries, Data Model Direction) and the v1 engine closure context dump. Canonical verbs: the generated Action Catalog.

Related

• Explanation: Backend Authority — why the graph has exactly one mutation authority.
• Explanation: Script IR and GessaScript — behavior resources in the graph and how they are authored.
• Explanation: Playability Proofs — why graph presence is not runtime proof.
• How-To: Edit Components — editing component resources through canonical authoring.

Status: stable explanation page for engine v1. The Project Graph model is real and canonical; its end-to-end proven status tracks the v1 readiness ledger, where the platform.ontology.control_plane row is currently unaccepted.