Composition Rewrite System Design

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

Composition Rewrite реализует patch-oriented AI workflow для controlled переписывания существующих блоков внутри композиции. Вместо слепой замены текста система сначала создаёт preview, а только потом по явному approve выпускает новые версии блоков и новую версию композиции.

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

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

  • preview generation;

  • apply over approved preview;

  • block-preserving rewrite;

  • versioned publication of changed blocks and composition.

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

  • hidden mutation of composition;

  • structural rewrite;

  • automatic apply;

  • добавление новых блоков через эту capability.

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

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

  • разделять preview и apply;

  • работать через отдельный rewriter contract;

  • собирать rewrite context из уникальных blocks композиции;

  • проверять placeholders до публикации;

  • использовать обычный block/composition versioning workflow.

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

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

  • CompositionBlockRewriteViewModel Управляет instruction, preview, apply и статусами в UI.

  • CompositionBlockRewriteRequest Описывает исходную композицию, версию и пользовательскую инструкцию.

  • ICompositionBlockRewriter Порт для preview-based AI rewrite.

  • OpenAiCompatibleCompositionBlockRewriter Конкретная provider implementation.

  • tf::Engine Собирает rewrite context, валидирует preview, применяет approved patches и публикует новые версии.

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

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

  • CompositionRewriteContextBlock

  • CompositionBlockRewriteContext

  • BlockRewritePatch

  • CompositionBlockRewritePreview

  • AppliedCompositionBlockRewriteResult

Ключевые свойства patch model:

  • patch ссылается на существующий block_id;

  • меняются только ограниченные поля;

  • composition structure не является частью patch contract.

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

Diagram

Шаги:

  1. Пользователь выбирает composition и пишет instruction.

  2. GUI вызывает preview.

  3. Engine загружает composition и уникальные referenced blocks.

  4. Rewriter возвращает patch preview.

  5. Пользователь review-ит summary.

  6. По явному apply engine публикует новые версии блоков и новую версию композиции.

7. Validation и guardrails

Ключевые guardrails:

  • preview невозможен без выбранной composition и непустой инструкции;

  • duplicate patches по block_id отклоняются;

  • patch не может ссылаться на блок, которого нет в source composition;

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

  • composition structure не меняется.

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

При ошибке provider:

  • source composition остаётся неизменной;

  • preview не создаётся.

При ошибке apply:

  • пользователь получает explicit error;

  • нет hidden overwrite already reviewed source assets.

Если preview пустой:

  • apply либо не требуется, либо возвращает исходную composition version без structural mutation.

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

Функция:

  • explicit и review-driven;

  • опирается на quality user instruction;

  • чувствительна к понятности preview summary;

  • интегрируется с существующим versioning и publish lifecycle.

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

Upstream:

Downstream: