breakshaft/COMMUTATIVITY_DESIGN.md

Масштабное проектирование: Решение проблемы некоммутативных преобразований в breakshaft

Содержание

1. Постановка проблемы
2. Анализ текущей ситуации
3. Варианты решений
4. Сравнительная таблица
5. Рекомендации

---

1. Постановка проблемы

1.1. Что такое некоммутативность в breakshaft?

Некоммутативное преобразование — ситуация, когда существует несколько путей преобразования типов, дающих разные результаты.

Пример:

@repo.mark_injector()
def int_to_a_v1(i: int) -> A:
    return A(i * 10)      # Путь 1: A(420) из int=42

@repo.mark_injector()
def int_to_a_v2(i: int) -> A:
    return A(i + 100)     # Путь 2: A(142) из int=42

def consumer(dep: A) -> int:
    return dep.a

# Два пути дают разные результаты: 420 vs 142

1.2. Почему это проблема?

Аспект	Проблема
Детерминизм	Один и тот же код может давать разные результаты
Отладка	Сложно понять, какой путь был выбран
Предсказуемость	Поведение зависит от внутреннего порядка обхода графа
Тестирование	Тесты могут проходить/падать недетерминированно

1.3. Где возникает в коде?

src/breakshaft/
├── graph_walker.py
│   ├── generate_callgraph()      # Построение графа
│   ├── explode_callgraph_branches() # Комбинаторный взрыв вариантов
│   └── filter_exploded_callgraph_branch() # Фильтрация (выбор пути)
└── convertor.py
    └── get_callseq()             # Проверка force_commutative

Критическое место — filter_exploded_callgraph_branch():

• Использует эвристики для выбора пути
• Порядок обхода не гарантирован
• При force_commutative=True выбрасывает ошибку если >1 пути

---

2. Анализ текущей ситуации

2.1. Текущий алгоритм выбора пути

# graph_walker.py: filter_exploded_callgraph_branch()

# Эвристики (применяются последовательно):
template_metrics = [
    lambda x: len(x.consumed_from_types),  # 1. Максимум потреблённых типов
    lambda x: x.consumed_cumsum,           # 2. Максимум кумулятивного потребления
    lambda x: -x.invokes,                  # 3. Минимум вызовов
]

# Если после фильтрации >1 варианта:
if len(variants) > 1:
    # Сортировка по имени функции (недетерминировано!)
    variants.sort(key=lambda x: universal_qualname(x.injector.fn))

2.2. Проблемы текущей реализации

Проблема	Описание	Влияние
P1. Недетерминированная сортировка	universal_qualname() не гарантирует порядок	Разные результаты на разных машинах
P2. Эвристики не семантические	Выбор по метрикам графа, не по логике	Может выбрать "неправильный" путь
P3. Комбинаторный взрыв	explode_callgraph_branches() генерирует все варианты	O(n!) сложность
P4. Нет кэширования	Граф пересчитывается каждый раз	Усугубляет P3
P5. Нет явного приоритета	Все инжекторы равны	Невозможно указать "предпочтительный" путь

2.3. Статистика (из тестов)

test_performance_many_injectors: 20 инжекторов → ~0.5 сек
test_performance_many_injectors: 50 инжекторов → TIMEOUT (комбинаторный взрыв)

---

3. Варианты решений

Вариант 1: Явные приоритеты инжекторов

Описание

Добавить параметр priority к mark_injector(). При выборе пути предпочитать инжекторы с высшим приоритетом.

Реализация

# Использование
@repo.mark_injector(priority=10)  # Высокий приоритет
def int_to_a_preferred(i: int) -> A:
    return A(i * 10)

@repo.mark_injector(priority=1)   # Низкий приоритет
def int_to_a_fallback(i: int) -> A:
    return A(i + 100)

# Изменения в моделях
@dataclass(frozen=True)
class ConversionPoint:
    fn: Callable
    injects: type
    # ...
    priority: int = 0  # Новый параметр
    
# Изменения в graph_walker.py
def filter_exploded_callgraph_branch(variants, priority_injectors=None):
    # Сортировка по приоритету
    variants.sort(key=lambda x: -x.injector.priority)

Сильные стороны

+	Описание
Контроль	Разработчик явно указывает предпочтения
Детерминизм	Приоритеты дают однозначный выбор
Гибкость	Можно менять приоритеты без изменения кода
Обратная совместимость	priority=0 по умолчанию не ломает существующий код

Слабые стороны

-	Описание
Сложность API	Новый параметр для изучения
Конфликты приоритетов	Одинаковые приоритеты → снова недетерминизм
Не решает комбинаторный взрыв	Всё ещё генерируются все варианты
Субъективность	Приоритеты могут быть произвольными

Оценка сложности

• Код: ~50 строк изменений
• Тесты: ~10 новых тестов
• Риск: Низкий

---

Вариант 2: Именованные пути (Named Paths)

Описание

Разработчик явно именовывает пути преобразования и выбирает их по имени.

Реализация

# Регистрация именованных путей
@repo.mark_path(name="multiply")
def int_to_a_mult(i: int) -> A:
    return A(i * 10)

@repo.mark_path(name="add")
def int_to_a_add(i: int) -> A:
    return A(i + 100)

# Выбор пути при использовании
fn = repo.get_conversion(
    (int,),
    consumer,
    path_preference="multiply"  # Явный выбор пути
)

# Или глобальная настройка
repo.set_path_preference("multiply")

Сильные стороны

+	Описание
Полный контроль	Разработчик всегда выбирает путь
Читаемость	Код явно показывает какой путь используется
Документированность	Имена путей служат документацией
Тестируемость	Можно тестировать разные пути явно

Слабые стороны

-	Описание
Бойлерплейт	Нужно именовать каждый путь
Сложность	Управление именами в больших проектах
Конфликты имён	Нужна проверка уникальности
Не решает комбинаторный взрыв	Генерация всех вариантов остаётся

Оценка сложности

• Код: ~150 строк изменений
• Тесты: ~15 новых тестов
• Риск: Средний

---

Вариант 3: Стратегии выбора пути (Path Selection Strategies)

Описание

Встроенные стратегии выбора пути с возможностью расширения.

Реализация

from breakshaft import PathStrategy

# Встроенные стратегии:
# - SHORTEST: кратчайший путь (минимум вызовов)
# - LONGEST: длиннейший путь (максимум преобразований)
# - FIRST: первый найденный (быстро, недетерминировано)
# - EXPLICIT: только явные пути (ошибка если несколько)
# - CUSTOM: пользовательская функция

fn = repo.get_conversion(
    (int,),
    consumer,
    path_strategy=PathStrategy.SHORTEST  # или PathStrategy.LONGEST
)

# Пользовательская стратегия
def my_strategy(paths: list[Path]) -> Path:
    # Логика выбора
    return min(paths, key=lambda p: p.complexity)

fn = repo.get_conversion(
    (int,),
    consumer,
    path_strategy=PathStrategy.CUSTOM(my_strategy)
)

Сильные стороны

+	Описание
Гибкость	Разные стратегии для разных случаев
Расширяемость	Пользовательские стратегии
Явность	Стратегия видна в коде вызова
Переиспользование	Стратегии можно переиспользовать

Слабые стороны

-	Описание
Сложность API	5+ стратегий для изучения
Не решает комбинаторный взрыв	Стратегия применяется после генерации
Производительность	Некоторые стратегии дорогие

Оценка сложности

• Код: ~200 строк изменений
• Тесты: ~20 новых тестов
• Риск: Средний

---

Вариант 4: Ограничение глубины графа (Depth Limiting)

Описание

Ограничить максимальную глубину/сложность графа преобразований.

Реализация

repo = ConvRepo(
    max_depth=5,           # Максимум 5 преобразований в цепочке
    max_branches=10,       # Максимум ветвей в узле
    max_total_paths=100    # Максимум путей для рассмотрения
)

# Или при вызове
fn = repo.get_conversion(
    (int,),
    consumer,
    max_depth=3  # Переопределение для конкретного вызова
)

Сильные стороны

+	Описание
Защита от взрыва	Гарантированная верхняя граница сложности
Производительность	Предсказуемое время выполнения
Простота	Один параметр для настройки

Слабые стороны

-	Описание
Ограничения	Может отсечь валидные пути
Не детерминизм	Не решает проблему выбора пути
Настройка	Нужно подбирать значения

Оценка сложности

• Код: ~80 строк изменений
• Тесты: ~8 новых тестов
• Риск: Низкий

---

Вариант 5: Кэширование графов (Graph Caching)

Описание

Кэшировать построенные графы преобразований для повторного использования.

Реализация

from breakshaft import LRUCache, PersistentCache

# Кэш в памяти (LRU)
repo = ConvRepo(cache=LRUCache(max_size=1000))

# Персистентный кэш (на диске)
repo = ConvRepo(cache=PersistentCache(path=".breakshaft_cache"))

# Декоратор для кэширования
@repo.cached
def get_converter(from_types, to_type):
    return repo.get_conversion(from_types, to_type)

Сильные стороны

+	Описание
Производительность	Повторные вызовы мгновенные
Масштабируемость	Работает с большим числом инжекторов
Прозрачность	Кэш прозрачен для пользователя

Слабые стороны

-	Описание
Память	Кэш потребляет память
Инвалидация	Сложность при изменении инжекторов
Не решает выбор пути	Кэширует выбранный путь, но не детерминирует выбор

Оценка сложности

• Код: ~250 строк изменений
• Тесты: ~25 новых тестов
• Риск: Высокий (состояние, гонки)

---

Вариант 6: Статический анализ графа (Static Graph Analysis)

Описание

Анализировать граф на этапе регистрации инжекторов, обнаруживать проблемы заранее.

Реализация

# Предварительный анализ
repo = ConvRepo(validate_on_register=True)

@repo.mark_injector()
def int_to_a_v1(i: int) -> A:
    return A(i * 10)

@repo.mark_injector()
def int_to_a_v2(i: int) -> A:
    return A(i + 100)  # Warning: Ambiguous path detected!

# Явная валидация
warnings = repo.validate()
for w in warnings:
    print(f"Warning: {w}")
# Warning: Ambiguous path for A: 2 injectors found

# Разрешение конфликта
repo.resolve_ambiguity(A, preferred=int_to_a_v1)

Сильные стороны

+	Описание
Раннее обнаружение	Ошибки на этапе регистрации
Документированность	Явное разрешение конфликтов
Безопасность	Невозможно создать неоднозначность

Слабые стороны

-	Описание
Сложность	Анализ графа дорог
Жёсткость	Может быть слишком ограничительно
Не решает комбинаторный взрыв	Анализ добавляет overhead

Оценка сложности

• Код: ~300 строк изменений
• Тесты: ~30 новых тестов
• Риск: Высокий

---

Вариант 7: Версионирование путей (Path Versioning)

Описание

Каждый путь имеет версию, можно выбирать конкретную версию.

Реализация

@repo.mark_injector(version="1.0")
def int_to_a(i: int) -> A:
    return A(i * 10)

@repo.mark_injector(version="2.0")  # Новая версия
def int_to_a(i: int) -> A:
    return A(i + 100)

# Выбор версии
fn = repo.get_conversion(
    (int,),
    consumer,
    path_version="1.0"  # Использовать старую версию
)

# Или диапазон
fn = repo.get_conversion(
    (int,),
    consumer,
    path_version=">=1.0,<3.0"
)

Сильные стороны

+	Описание
Эволюция	Плавный переход между версиями
Совместимость	Старый код продолжает работать
Контроль	Явный выбор версии

Слабые стороны

-	Описание
Сложность	Управление версиями
Бойлерплейт	Версии для каждого пути
Не решает комбинаторный взрыв	Все версии генерируются

Оценка сложности

• Код: ~200 строк изменений
• Тесты: ~20 новых тестов
• Риск: Средний

---

Вариант 8: Комбинированный подход (Hybrid Solution)

Описание

Комбинация нескольких подходов для максимального эффекта.

Реализация

repo = ConvRepo(
    # Приоритеты по умолчанию
    default_priority=0,
    
    # Кэширование
    cache=LRUCache(max_size=500),
    
    # Ограничения
    max_depth=10,
    max_total_paths=1000,
    
    # Стратегия по умолчанию
    default_strategy=PathStrategy.SHORTEST,
    
    # Валидация
    validate_on_register=True,
)

# Гибкое переопределение
fn = repo.get_conversion(
    (int,),
    consumer,
    priority_override={int_to_a_v1: 10},  # Приоритет для конкретных
    strategy=PathStrategy.EXPLICIT,
    cache_key="my_custom_key"
)

Сильные стороны

+	Описание
Максимальная гибкость	Все инструменты доступны
Масштабируемость	Работает с большими графами
Контроль	Полный контроль над поведением

Слабые стороны

-	Описание
Сложность	Много параметров для настройки
Обучение	Крутая кривая обучения
Риск ошибок	Неправильная конфигурация

Оценка сложности

• Код: ~500 строк изменений
• Тесты: ~50 новых тестов
• Риск: Высокий

---

Вариант 9: Декларативное описание графа (Declarative Graph)

Описание

Полностью декларативное описание путей преобразования вместо автоматического вывода.

Реализация

# Декларативное описание
repo.define_graph({
    "paths": [
        {
            "name": "multiply_path",
            "steps": [
                {"from": int, "to": A, "using": int_to_a_mult},
                {"from": A, "to": B, "using": a_to_b},
            ],
            "priority": 10
        },
        {
            "name": "add_path",
            "steps": [
                {"from": int, "to": A, "using": int_to_a_add},
            ],
            "priority": 1
        }
    ]
})

# Выбор пути по имени
fn = repo.get_conversion(
    (int,),
    consumer,
    path_name="multiply_path"
)

Сильные стороны

+	Описание
Полный контроль	Явное описание всех путей
Детерминизм	Никакой неявной логики
Документированность	Граф виден в коде
Нет комбинаторного взрыва	Только явные пути

Слабые стороны

-	Описание
Бойлерплейт	Много кода для описания
Потеря автоматизма	Нет автоматического вывода путей
Сложность поддержки	Изменение графа требует правки описания

Оценка сложности

• Код: ~400 строк изменений
• Тесты: ~40 новых тестов
• Риск: Высокий (меняет парадигму)

---

Вариант 10: Машинное обучение для выбора пути (ML-Based Selection)

Описание

Использовать ML для предсказания "лучшего" пути на основе истории использования.

Реализация

from breakshaft import MLPathSelector

repo = ConvRepo(
    path_selector=MLPathSelector(
        training_data="usage_history.json",
        features=["execution_time", "memory_usage", "success_rate"]
    )
)

# ML выбирает путь на основе:
# - Истории успешных выполнений
# - Времени выполнения
# - Потребления памяти
# - Контекста (типы, размеры данных)

fn = repo.get_conversion((int,), consumer)
# Путь выбирается автоматически на основе модели

Сильные стороны

+	Описание
Адаптивность	Учится на использовании
Оптимизация	Выбирает эффективные пути
Автоматизм	Не требует ручной настройки

Слабые стороны

-	Описание
Сложность	ML модель + обучение
Непредсказуемость	ML может выбрать неожиданно
Зависимость от данных	Нужна история для обучения
Overhead	Предсказание модели

Оценка сложности

• Код: ~600 строк изменений
• Тесты: ~60 новых тестов
• Риск: Очень высокий

---

4. Сравнительная таблица

Вариант	Детерминизм	Производительность	Сложность	Обратная совместимость	Риск
1. Приоритеты	⭐⭐⭐⭐	⭐⭐⭐	⭐	⭐⭐⭐⭐⭐	Низкий
2. Именованные пути	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	Средний
3. Стратегии	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	Средний
4. Ограничение глубины	⭐⭐	⭐⭐⭐⭐⭐	⭐	⭐⭐⭐⭐⭐	Низкий
5. Кэширование	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	Высокий
6. Статический анализ	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	Высокий
7. Версионирование	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	Средний
8. Комбинированный	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	Высокий
9. Декларативный	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	Высокий
10. ML	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Очень высокий

Легенда:

• ⭐⭐⭐⭐⭐ — Отлично
• ⭐⭐⭐⭐ — Хорошо
• ⭐⭐⭐ — Удовлетворительно
• ⭐⭐ — Плохо
• ⭐ — Очень плохо

---

5. Рекомендации

5.1. Краткосрочные решения (быстрая победа)

Вариант 1 + Вариант 4: Приоритеты + Ограничение глубины

# Минимальные изменения для детерминизма
@repo.mark_injector(priority=10)
def preferred_converter(...): ...

repo = ConvRepo(max_depth=10)

Преимущества:

• ~130 строк кода
• Низкий риск
• Обратная совместимость
• Решает 80% проблем

5.2. Среднесрочные решения (баланс)

Вариант 3 + Вариант 5: Стратегии + Кэширование

repo = ConvRepo(
    cache=LRUCache(1000),
    default_strategy=PathStrategy.SHORTEST
)

Преимущества:

• Хорошая производительность
• Гибкость для пользователей
• Решает проблему комбинаторного взрыва

5.3. Долгосрочные решения (полное решение)

Вариант 8 (Комбинированный) с элементами Варианта 9

repo = HybridConvRepo(
    priorities=True,
    strategies=True,
    cache=True,
    validation=True,
    declarative_mode=False  # Опционально
)

Преимущества:

• Полное решение проблемы
• Масштабируемость
• Гибкость

5.4. Дорожная карта

Фаза 1 (2 недели):
├── Приоритеты инжекторов
├── Ограничение глубины
└── Тесты

Фаза 2 (4 недели):
├── Стратегии выбора пути
├── Базовое кэширование
└── Документация

Фаза 3 (6 недель):
├── Статический анализ
├── Продвинутое кэширование
├── Декларативный режим (опционально)
└── Полное тестирование

---

6. Заключение

6.1. Выводы

1. Нет серебряной пули — каждый вариант имеет компромиссы
2. Комбинированный подход даёт лучший результат
3. Начинать с простого — приоритеты + ограничения
4. Итеративное улучшение — добавлять функции постепенно

6.2. Риски

Риск	Вероятность	Влияние	Митигация
Ломает обратную совместимость	Низкая	Высокое	Поэтапное внедрение
Усложнение API	Средняя	Среднее	Хорошая документация
Производительность	Низкая	Высокое	Бенчмарки на каждом этапе
Комбинаторный взрыв	Средняя	Высокое	Ограничения + кэш

6.3. Следующие шаги

1. Выбрать подход для Фазы 1
2. Создать PR с приоритетами и ограничениями
3. Собрать фидбэк от пользователей
4. Итеративно улучшать

---

Документ создан для breakshaft v0.1.6 Дата: 2026-03-28