# Map Contract и статическая пространственная согласованность

- **Status:** `complete`
- **Outcome:** `pass`
- **Started:** 2026-07-25
- **Updated:** 2026-07-25
- **Research ID:** `2026-07-25-map-spatial-consistency`

## Проверяемый вопрос

Можно ли одним жанрово-нейтральным `MapContract` описать regions, locations и
направленные edges так, чтобы до запуска сессии обнаруживать битые ссылки и
недостижимые обязательные узлы, а во время исполнения детерминированно
проверять movement, travel cost, obstacles, line of sight, fog of war,
discovery и private locations?

## Почему решение нужно сейчас

LLM не имеет права перемещать персонажа через отсутствующую связь, раскрывать
скрытую локацию или обходить obstacle. Rules/state ядру нужен отдельный
authoritative spatial contract и projection boundary, не зависящие от текста
narration и жанра приключения.

## Scope

- `MapContract` для regions, locations, coordinates и node/edge topology.
- Directed/bidirectional movement, typed travel cost и obstacle requirements.
- Static reachability от start nodes до обязательных locations.
- Broken-reference validation для regions, endpoints, scenes, encounters и
  triggers.
- Discovery state, fog projection и private location authorization.
- Direct-edge line-of-sight check без утечки скрытых узлов.
- Оригинальный sci-fi comedy fixture, согласованный по IDs с тестовым
  adventure, но не являющийся product canon.

## Non-goals

- Tactical grid, continuous geometry, pathfinding around polygons or physics.
- Production authorization, persistence or multiplayer synchronization.
- Автоматическая генерация красивой карты.
- Выбор fantasy setting, ruleset или канонического приключения.
- Semantic проверка внешних scene/encounter/trigger definitions: validator
  получает только их authoritative ID index.

## Критерии успеха

Критерии зафиксированы до реализации prototype.

| ID | Обязательный критерий | Порог или ожидаемое поведение | Способ проверки |
|---|---|---|---|
| MC-01 | Валидный contract | Original sci-fi fixture даёт `0` validation issues | `node --test prototype/map.test.ts` |
| MC-02 | Broken references | Неизвестные region, endpoint, scene, encounter и trigger IDs отклоняются стабильными кодами | Негативные автотесты |
| MC-03 | Reachability | Каждый `requiredReachableLocationId` достижим из start nodes по потенциально проходимым directed edges | Graph validation + автотест |
| MC-04 | Movement | Edge direction, obstacle flags, authorization и travel cost проверяются до move | Автотест `evaluateMove` |
| MC-05 | Fog/privacy | Undiscovered и неразрешённые private nodes/edges отсутствуют в player projection | Две viewer projections |
| MC-06 | LOS | LOS существует только по разрешённому direct edge с `lineOfSight: clear` | Автотест |
| MC-07 | Content binding | Scene/encounter/trigger refs сверяются с переданным authoritative index | Негативный автотест |
| MC-08 | Non-canonical provenance | Fixture original, borrowed-IP-free и `isCanonical: false` | Автотест |

## Рабочие гипотезы

- **Hypothesis H-01:** adjacency graph с typed edges достаточен для первого
  vertical slice без tactical grid. Подтверждение: MC-03–MC-06.
- **Hypothesis H-02:** projection до narration предотвращает утечку private и
  hidden location IDs. Подтверждение: MC-05.
- **Hypothesis H-03:** opaque content IDs связывают карту с adventure без
  передачи map validator контроля над сюжетом. Подтверждение: MC-02 и MC-07.

## Материалы

- [Исследование и evidence log](RESEARCH.md)
- [Техническое решение и запуск](SOLUTION.md)
- [Проверка и итог](VALIDATION.md)
- [`prototype/`](prototype/) — исполнимый артефакт

## Итог

`pass`: directed topology обнаруживает broken refs и недостижимые required
nodes, movement применяет direction/obstacle/authorization/travel cost, а
projection не раскрывает hidden/private locations и edges. Suite: 6/6; demo:
0 issues. Основание: E-003–E-008.

## Ограничения

- Static reachability считает conditional obstacle потенциально проходимым; это
  не доказывает, что конкретная party получит нужный flag.
- Direct-edge LOS не моделирует углы, высоту или dynamic occlusion.
- Layout coordinates предназначены для отображения, а не для физики.
- Fixture не является канонической картой продукта.

## Следующее решение

Принять topology contract для первого rules/state replay. Grid/geometry study
создавать только если подтверждённый gameplay потребует continuous LOS,
tactical distance или collision.