# Contract: Git Submodule Integration

Version: 1.0

Правила для проектов, использующих git submodules (shared libraries, viewers, bible, tooling).

Применяется в: `bee` (internal/chart/, bible/), `chart`, `logpile/internal/chart/`, `PriceForge`.

## Основное правило

**Embedded submodules — read-only с точки зрения host-проекта.**

## Запрещено

- Реализовывать project-specific поведение путём редактирования кода submodule.
- Вносить в submodule изменения, специфичные для одного host-проекта.
- Держать в submodule локальные неотправленные коммиты как часть feature host-проекта.

## Разрешено

- Обновлять указатель submodule на upstream-коммит после merge там.
- Если нужна новая возможность в submodule — предложить и влить её в upstream как generic-изменение, затем подтянуть через обновление указателя.

## Когда нужны новые данные

Если host-проект нуждается в новых данных, которые должен отображать submodule-viewer:

1. Производить, нормализовывать и сериализовывать новые данные в самом host-проекте.
2. Обновить JSON-контракт (например, `bible-local/docs/hardware-ingest-contract.md`), чтобы viewer мог читать их из стандартного snapshot.
3. Предложить поддержку нового поля в upstream viewer как generic-изменение.

## Почему

Конкретный провал: попытка добавить telemetry storage в `bee` через редактирование `internal/chart/` создала coupling shared viewer с одним host-проектом и риск скрытых регрессий в других проектах, использующих тот же `chart`.

## Документирование интеграции

В `bible-local/` host-проекта должен быть явный контракт:
- Какие данные ожидает submodule на входе.
- Как host-проект их производит (какой модуль/файл).
- Текущий upstream commit/tag submodule.