Composition Rewrite Service Spec

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

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

  • переписать composition через previewable patch set;

  • не выполнять blind overwrite;

  • отделить AI suggestion от фактического apply.

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

  • GUI rewrite workflow;

  • composition authoring flow.

Не-цели:

  • structural redesign composition;

  • hidden persistence side effects вне explicit apply;

  • automatic approval.

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

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

  • CompositionBlockRewriteViewModel

  • composition rewrite dialog

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

  • ICompositionBlockRewriter

  • provider API

  • engine preview/apply logic

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

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

  • Engine.PreviewCompositionBlockRewrite(const CompositionBlockRewriteRequest&)

  • Engine.ApplyCompositionBlockRewrite(const CompositionBlockRewritePreview&)

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

Preview input использует CompositionBlockRewriteRequest

Поля:

  • source_composition_id

  • optional source_version

  • instruction

  • preserve_language

  • preserve_placeholders

Preview context, который engine собирает дополнительно, включает:

  • block_id

  • type

  • language

  • description

  • defaults

  • tags

  • templ

Важно:

  • context строится только по blocks, реально присутствующим в выбранной композиции;

  • повторные ссылки на один и тот же блок не должны порождать дубликаты в context.

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

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

  • CompositionBlockRewritePreview

  • AppliedCompositionBlockRewriteResult

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

  • исходная composition identity;

  • исходная version;

  • список BlockRewritePatch.

Содержимое apply result:

  • новая composition identity/version;

  • список реально переписанных блоков.

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

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

  • preview должен оставаться inspectable для caller;

  • apply зависит только от approved preview;

  • storage mutation происходит только в explicit apply path;

  • patches могут модифицировать только существующие blocks из selected composition;

  • duplicate patches по block_id недопустимы;

  • placeholder-preservation обязателен до публикации rewritten blocks.

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

Приоритеты:

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

  • user instruction задаёт desired rewrite;

  • preservation rules являются частью prompt policy;

  • engine добавляет domain-level validation before apply.

8. Ошибки и retry policy

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

  • no rewriter configured;

  • invalid composition version;

  • source composition not found;

  • provider/transport errors;

  • duplicate patch ids;

  • patch references block not present in source composition;

  • placeholder violations.

Retry policy:

  • provider retries - outside core service contract;

  • apply retry не должен скрывать доменные ошибки preview/patch validation.

9. Routing и quality policy

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

  • использует один configured rewriter path;

  • не публикует confidence score;

  • preview quality and preservation behavior acting as practical routing gate.

Главный safety gate:

  • human review before apply.

10. Edge cases и fallback behavior

Основные edge cases:

  • no rewriter configured Explicit error.

  • too aggressive rewrite Пользователь не применяет preview и переходит к manual editing.

  • ambiguous patch set Fallback to manual composition editing.

  • empty patch set Apply не должен выполнять unnecessary mutation.

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

Upstream:

Downstream: