---
title: "Explanation: The Project Graph"
description: "The Project Graph as the authoritative world and resource model, worlds are persistent stateful environments, not just renderable scenes."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/explanation/project-graph/
---

# 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](backend-authority.md).

## 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](../../../architecture/platform-ontology-control-plane-final-plan.md), 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](../reference/action-catalog.md) 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.

{% generated-reference file="docs/spec/generated/action-catalog.md" label="Project Graph verbs (project-graph domain)" /%}

The full, canonical list of verbs (with owners, exposure flags, and the HTTP/MCP/SDK surfaces they map to) is the generated [Action Catalog](../../../spec/generated/action-catalog.md). 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:

```text
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](playability-proofs.md));
- that **the client can edit freely**: it cannot; edits are authoritative transactions, not local mutations (see [Backend Authority](backend-authority.md));
- 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](script-ir-and-gessascript.md): 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](script-ir-and-gessascript.md), 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.

{% warning severity="critical" title="Never write the graph directly" %}
There is no supported "raw graph write" for normal authoring. Frontend-only schemas, raw mutation fetches, and hand-built Project Graph transactions are hard anti-patterns in the v1 closure contract. Use the `project.<kind>.*` Action Catalog verbs and Script Semantic Patch; the backend turns intent into validated, versioned, idempotent transactions with receipts.
{% /warning %}

## 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](backend-authority.md). 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](../../../cycles/v1-engine-readiness-loop/FEATURE_LEDGER.json). 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`](../../../architecture/platform-ontology-control-plane-final-plan.md) (Abstract Worlds And Projection Boundaries, Data Model Direction) and the [v1 engine closure context dump](../../../architecture/v1-engine-closure-context-dump.md). Canonical verbs: the generated [Action Catalog](../../../spec/generated/action-catalog.md).

## Related

- [Explanation: Backend Authority](backend-authority.md): why the graph has exactly one mutation authority.
- [Explanation: Script IR and GessaScript](script-ir-and-gessascript.md): behavior resources in the graph and how they are authored.
- [Explanation: Playability Proofs](playability-proofs.md): why graph presence is not runtime proof.
- [How-To: Edit Components](../how-to/edit-components.md): 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`.