# ADR-0004: Ранняя валидация и явные fallback-политики

**Дата**: 2026-08-26
**Статус**: Принято

## Контекст

Ошибки Typst часто проявляются во время layout далеко от места, где пользователь передал неверное значение. Для бизнес-документа особенно опасны тихие fallback: неверная компания, отсутствующая сторона, незаметно пропавшая подпись или citation, не попавшая в список источников.

При этом распространяемый шаблон должен компилироваться без реальных подписей и печатей. Они поставляются отдельным ZIP; PowerShell task проверяет и извлекает архив, после чего запускает `main.typ` с явным `sys.inputs`. Typst 0.15 не предоставляет проверки существования файла без попытки загрузки.

## Рассматриваемые варианты

1. **Полагаться только на diagnostics Typst** — мало кода, но сообщения не отражают доменный путь поля.
2. **Всегда аварийно завершаться при любом отсутствующем ресурсе** — строго, но шаблон нельзя удобно распространять без подписей.
3. **Валидировать domain до layout и явно моделировать необязательные ресурсы** — больше контрактов, зато ошибки предсказуемы.

## Решение

Выбрали **раннюю profile-specific валидацию**. Каждая ошибка называет профиль, путь поля, фактическое значение и ожидаемое ограничение.

Для подписи, печати и необязательных изображений поддерживаются политики:

- `hide` — не показывать ресурс и не резервировать место;
- `placeholder` — показать безопасную графическую заглушку: круг для печати или крест для подписи;
- `reserve-space` — оставить место для ручной подписи или печати.

Политика применяется только если поле равно `none`. Если поле содержит путь, но файл отсутствует, сборка завершается ошибкой.

## Последствия

**Становится проще**: распространение шаблона, поиск причины ошибки и тестирование негативных сценариев.

**Становится сложнее**: каждый профиль обязан определить required/optional поля и defaults.

**Закрывает дверь на**: молчаливое игнорирование неверно указанного пути к производственному ресурсу.