> ## 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={null}
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={null}
{
  "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 21 spatial tools. A type existing in `protocol.ts` does not mean a matching agent tool is registered, or that every surface implements it.

## 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     |

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.