> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# The spatial contract

> How events and structured actions connect an Entity, gateway, shell runtime, and surface.

The spatial protocol separates **intent** from **rendering**. An agent requests a semantic action; the shell resolves that action into its model, animations, voice, and scene.

## Canonical Entity path

```mermaid theme={"theme":"github-light-default"}
sequenceDiagram
    participant S as WebXR surface
    participant G as AR gateway
    participant E as Python Entity bridge
    S->>G: Surface event and capability context
    G->>E: Authenticated Entity input
    E->>E: Retrieve context, reason, call tools
    E-->>G: Speech, activity, spatial actions
    G-->>S: Protocol actions
    S->>S: Render with shell assets
```

The browser connects to the spatial gateway over WebSocket. The `ngram_entity` binding connects that gateway to the Python Entity bridge. Keep those two connections distinct when diagnosing a failed session.

## Message envelope

Protocol messages include a `type`, Unix-millisecond `timestamp`, and `sessionId`. For example:

```json theme={"theme":"github-light-default"}
{
  "type": "action:gesture",
  "timestamp": 1788796800000,
  "sessionId": "example-session",
  "gesture": "wave"
}
```

Session identifiers correlate actions with a live surface. They are not the Entity's persistent identity or a canonical person identifier.

## Tool schema and wire schema are different

The Python tool uses `ar_spawn_object` and snake-case parameters such as `object_id`. The protocol action uses `action:spawn_object` and `objectId`. The adapter performs that translation.

The TypeScript protocol defines more message types than the canonical Entity's 23 spatial tools. A type existing in `protocol.ts` does not mean a matching agent tool is registered, or that every surface implements it.

## Creation results and artifacts

`ar_world` dispatches `action:world` with a command and payload. The connected surface returns a correlated structured result to the waiting tool call. World edits use the versioned `ngram.world/1` document, validated operation batches, request IDs, and optional revision checks. Human grabs lock transforms until release.

Blender uses the existing execution RPC route with action `blender`. Its persistent process emits publish checkpoints; the Python tool delivers project/revision information to the connected surface while waiting for the edit to finish. The surface fetches immutable GLB artifacts through the gateway's configured Entity bridge, keeping backend credentials on the server.

Local creation programs and physics run beside the renderer. Their frames and events do not become automatic model turns. See [Blender](/spatial/blender) and [Programs](/spatial/programs).

## Streaming and cancellation

The bridge can deliver activity, speech, and spatial actions during a turn. The surface's `event:cancel_turn` and recognized direct stop speech cancel active spatial work. A queued action is a delivery attempt; verify important visible outcomes in the surface.

Cancellation applies to active work. It does not undo an already completed external tool action or shut down the Entity worker.

## Extension points

Use the shipped interfaces as the basis for a custom binding:

| Source                                                   | Responsibility                                              |
| -------------------------------------------------------- | ----------------------------------------------------------- |
| `ngramAR/packages/core/src/protocol.ts`                  | Event and action types                                      |
| `ngramAR/packages/core/src/types.ts`                     | Shell, capability, and shared types                         |
| `ngramAR/packages/bindings/src/`                         | Binding implementations                                     |
| `ngramAR/packages/gateway/src/`                          | Session routing and server-side providers                   |
| `ngram/ngram_ar/bridge_server.py`                        | Python Entity bridge and turn control                       |
| `ngram/ngram_ar/spatial_tools.py`                        | Canonical Entity spatial tool schemas                       |
| `ngramAR/packages/core/src/world-contract.ts`            | Versioned creation schema and limits                        |
| `ngramAR/packages/surface-webxr/src/creation-service.ts` | Creation commands, local persistence, and program lifecycle |
| `ngram/ngram_ar/blender_tools.py`                        | Execution-host authoring and preview delivery               |
| `ngram/presence/tools/blender_runtime.py`                | Persistent Blender processes and published artifacts        |

These paths refer to the [application repository](https://github.com/ngramspatial/ngram), not the documentation checkout. Keep identity ownership, person mapping, authentication, capability reporting, cancellation, and reconnect behavior explicit in a new adapter.