Normalization System Design

1. Краткое резюме

Normalization добавляет explicit semantic rewrite поверх deterministic render path. Архитектура разделяет:

  • canonical deterministic render;

  • text-level semantic rewrite;

  • block-preserving composition derivation.

Таким образом AI остаётся optional transformation layer, а не частью базового контракта рендеринга.

2. Контекст и границы

В области охвата:

  • text normalization;

  • composition normalization;

  • derived block publishing;

  • derived composition publishing;

  • explicit semantic style application.

Вне области охвата:

  • hidden rewrite in renderer;

  • automatic persistence of source assets;

  • неявное смешение normalized output с canonical render result.

3. Архитектурные требования

Функция должна:

  • требовать явного Normalize() вызова;

  • работать через engine contracts, а не только через GUI logic;

  • не переписывать source blocks и source compositions на месте;

  • сохранять placeholders при block normalization;

  • позволять reuse cached normalized assets.

4. Компоненты и интеграции

Основные компоненты:

  • RenderViewModel Инициирует text normalization над текущим raw snapshot и управляет stale-state.

  • CompositionsViewModel Инициирует composition normalization.

  • SemanticStyle Описывает желаемое semantic transformation policy.

  • INormalizer Переписывает произвольный текст.

  • IBlockNormalizer Переписывает block templates с сохранением structural constraints.

  • OpenAiCompatibleNormalizer Конкретная AI-реализация обоих интерфейсов.

  • tf::Engine Оркестрирует normalize calls, validation, derivation и reuse cached assets.

5. Контракты данных

Основные структуры:

  • SemanticStyle

  • BlockNormalizationRequest

  • NormalizedBlockData

  • CompositionNormalizationRequest

  • NormalizedCompositionResult

Ключевые свойства контрактов:

  • text normalization возвращает строку;

  • block normalization возвращает normalized template и optional metadata;

  • composition normalization возвращает идентичность производной композиции и список rewritten blocks.

6. Основные сценарии

6.1. Text normalization

Diagram

Особенности:

  • инициируется вручную;

  • работает поверх текущего snapshot;

  • результат может устаревать при изменении source snapshot.

6.2. Composition normalization

Diagram

Особенности:

  • source composition загружается из repository;

  • для каждого block ref создаётся или переиспользуется derived normalized block;

  • затем публикуется derived composition.

7. Guardrails и validation

Ключевые guardrails:

  • отсутствие normalizer приводит к explicit error;

  • empty semantic style отклоняется;

  • placeholder sets исходного и normalized block template сравниваются;

  • derived assets получают отдельную identity и tags;

  • reuse cached blocks/compositions опирается на fingerprint и normalization key.

8. Надёжность и деградация

При отсутствии AI:

  • render остаётся полностью работоспособным;

  • composition normalization не выполняется;

  • пользователь остаётся в deterministic workflow.

При ошибке provider:

  • source assets не меняются;

  • derived assets не публикуются частично как canonical replacements.

9. Операционные свойства

Функция:

  • explicit и optional;

  • порождает derived assets вместо inplace mutation;

  • требует ясного разграничения между Rendered и Normalized;

  • поддерживает кэширование по style/fingerprint.

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

Upstream:

Downstream: