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 the whole-graph revision before and after each change in their revision-before and revision-after fields, 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.