Normalization Service Spec

1. Назначение и граница сервиса

Назначение функции:

  • применять semantic rewrite к тексту или композиции по явному запросу;

  • возвращать AI-derived result, не подменяя canonical render;

  • при composition normalization создавать производные артефакты, а не переписывать source state.

Потребители:

  • render UI;

  • composition UI;

  • потенциальные будущие authoring clients.

Не-цели:

  • implicit render-time rewrite;

  • direct mutation of source published state;

  • скрытая подмена deterministic output.

2. Потребители и зависимости

Потребители:

  • render workflow

  • composition workflow

Зависимости:

  • INormalizer

  • IBlockNormalizer

  • SemanticStyle

  • provider API

3. Методы и точки вызова

Основные методы:

  • Engine.Normalize(const std::string&, const SemanticStyle&)

  • Engine.NormalizeComposition(const CompositionNormalizationRequest&)

4. Входной контракт

Text normalization

Вход:

  • source text

  • SemanticStyle

Composition normalization

Вход: CompositionNormalizationRequest

Поля:

  • source_composition_id

  • optional source_version

  • SemanticStyle

  • optional target_composition_id

  • normalize_static_text

  • reuse_cached_blocks

Семантика:

  • SemanticStyle Явно задаёт желаемое semantic transformation policy.

  • normalize_static_text Разрешает переписывать static text fragments.

  • reuse_cached_blocks Разрешает повторно использовать уже созданные normalized derivatives.

5. Выходной контракт

Основные выходы:

  • normalized string

  • NormalizedCompositionResult

Содержимое NormalizedCompositionResult:

  • composition_id

  • composition_version

  • rewritten_blocks

Смысл выходов:

  • normalized string Это AI-derived preview/result для текста.

  • normalized composition result Это идентичность производной композиции и трассировка переписанных блоков.

6. Правила доменного контракта

Функция обязана соблюдать:

  • explicit style request обязателен;

  • отсутствие configured normalizer является ошибкой;

  • normalized text не является hidden canonical persistence;

  • composition normalization сохраняет composition structure;

  • placeholders в block templates должны сохраняться;

  • source composition и source blocks не перезаписываются напрямую.

7. Иерархия источников и prompt policy

Приоритеты:

  • source text/source composition - первичный контекст;

  • SemanticStyle определяет desired rewrite policy;

  • prompt assembly и provider-specific formatting живут в textfoundry_ai;

  • engine добавляет domain constraints и validation.

8. Ошибки и retry policy

Ошибки, которые должны явно возвращаться:

  • no normalizer configured;

  • empty style request;

  • provider/transport errors;

  • parsing errors;

  • placeholder preservation violations;

  • source composition not found.

Retry policy:

  • transport/provider retry может существовать вне доменного контракта;

  • persistence retry не должен скрывать доменные ошибки derivation workflow.

9. Routing и confidence policy

Текущая реализация:

  • использует configured normalizer path;

  • не публикует отдельный confidence score;

  • composition-level guardrails достигаются через validation и derivation policy.

10. Edge cases и fallback behavior

Основные edge cases:

  • no normalizer configured Explicit error, user stays on deterministic output.

  • unclear style request Провайдер может вернуть слабый результат, поэтому review остаётся обязательным.

  • provider unavailable Fallback - raw deterministic output и отказ от normalization.

  • placeholder mismatch Engine отклоняет normalized block и не публикует derived result.

11. Связанные документы

Upstream:

Downstream: