# Spatial Specialist

**specialist_id:** `spatial`  
**trigger_gates:** `has_spatial_relation`

---

## Responsibility

The spatial specialist adds location, containment, direction, proximity, and topology constraints to objects. It attaches SpatialFacets to entities and events with spatial dimension, and emits spatial constraints between objects.

---

## Manifest

```
declared_facet_kinds:
  - spatial

declared_constraint_types:
  - inside
  - outside
  - adjacent
  - above
  - below
  - north_of
  - south_of
  - east_of
  - west_of
  - near
  - far
  - at_location
  - between
  - on_path

budget_caps:
  max_objects_proposed:     4
  max_facets_emitted:       8
  max_constraints_emitted: 12
  max_merges:               0
  max_splits:               0
```

---

## Output: SpatialFacet

Attach to objects with a spatial dimension (entities, events, states, code objects with file location).

```
SpatialFacet fields used:
  - location_label:    string (natural language location)
  - coordinates:       {x, y, z} if numeric coords available
  - containment_refs:  constraint IDs for inside/outside relations
  - reference_frame:   coordinate system or reference object
```

---

## Output: Constraints

### `inside(A, B)`

Object A is contained within object B. Example: `inside(book, shelf)`, `inside(Alice, building)`.

### `adjacent(A, B)`

A and B are next to each other without containment.

### `at_location(A, L)`

Object A is at named location L. L should be a canonical object of kind `entity` (a place).

### `between(A, B, C)`

Object A is between objects B and C.

### Directional constraints

`north_of`, `south_of`, `east_of`, `west_of`, `above`, `below` — all take two argument_refs in the form `(subject, reference)`.

### `near(A, B)` / `far(A, B)`

Relative proximity. Strength is always `soft` since "near" is inherently vague without a defined scale.

---

## Reference frame handling

Spatial constraints are only meaningful relative to a reference frame. When no frame is explicit in the input, use `"world"` as the default frame label.

```
SpatialFacet.reference_frame:
  - "world"       -- global geographic frame (default when unspecified)
  - "local"       -- relative to a locally established reference
  - "{object_id}" -- relative to a specific object in WorldState
```

---

## Contract test requirements

- Given `Alice is in the kitchen`, must emit `at_location(E_alice, O_kitchen)` or `inside(E_alice, O_kitchen)`
- Given `The box is on the shelf`, must emit `above(O_box, O_shelf)` or `on(O_box, O_shelf)`
- Must not emit temporal or quantity constraints
- All spatial facets must have `location_label` set
- All emitted constraints must have `source_module: spatial`