# AGENTS.md

## Проектные договоренности

### Публичное API библиотек

- Предпочтителен `non-null` подход.
- Там, где значение живет в Gradle Provider API, возвращается `Provider<T>` (не `null`).
- Там, где lookup синхронный, возвращается `Optional<T>` (не `null`).
- `find*` рассматривается как синоним legacy `get*` (поиск без `fail-fast`).
- `require*` это `find*` + `fail-fast` с понятной ошибкой в месте вызова.
- Для нового API предпочтительны формы `find/require`; новые `get*` по возможности не добавлять.

## Identity-first modeling

Prefer an **identity-first** split between:

- **identity objects** used for discovery and selection
- **stateful/materialized objects** obtained through separate API calls

### Rules

- Objects intended for replayable observation (`all(...)`, similar collection APIs) should be **identity objects**.
- Identity objects must be:
  - cheap to create
  - effectively immutable
  - limited to identity and cheap selection metadata
- Heavy, computed, provider-based, or runtime-bound state must be resolved separately.
- Aggregate content should be accessed through dedicated lookup/materialization APIs.
- Eager observation of identity is acceptable.
- Eager observation of computed state is not.

### Do not

- Do not store heavy computed state inside identity objects.
- Do not store runtime references to foreign domains inside identity objects.
- Do not use custom events when replayable identity registries plus on-demand lookup are sufficient.

### Rule of thumb

**Identity objects contain selection metadata.
Aggregate content is obtained separately, on demand.**