ADR: Python и C++ как first-class runtime surfaces

1. Статус и назначение

Статус: принято.

Этот ADR теперь фиксирует только верхнеуровневое архитектурное решение. Подробное описание capability вынесено в function-level набор:

Такой split сделан намеренно, потому что тема C++ / Python local / remote затрагивает не только архитектурный выбор, но и product scope, service contracts, release order и parity review.

2. Контекст

В проекте уже существует canonical implementation на C++:

  • domain model;

  • lifecycle Draft / Published;

  • deterministic render.

При этом целевая product model предполагает:

  • first-class local access из C++;

  • first-class local access из Python;

  • отдельную remote boundary через Prompt Server;

  • future remote clients как для C++, так и для Python.

3. Принятое решение

Принято следующее:

  • C++ engine остаётся canonical implementation;

  • source of truth живёт в engine/domain semantics, а не в language wrapper;

  • C++ local и Python local рассматриваются как first-class local surfaces;

  • C++ remote и Python remote рассматриваются как first-class remote surfaces;

  • parity оценивается по capability и semantics внутри boundary;

  • различия между local и remote допускаются как intentional boundary difference.

4. Почему это лучше альтернатив

Этот подход лучше, чем:

  • делать Python только thin client к server;

  • делать Python главным источником API-истины;

  • держать всю тему только в одном архитектурном ADR.

Причина:

  • сохраняется canonical роль C++;

  • Python не становится вторичным;

  • Prompt Server не деформируется под FFI convenience;

  • detailed contracts живут в function-level pipeline, где им и место.

5. Последствия

Положительные:

  • архитектурный уровень стал короче и чище;

  • capability описана детальнее в отдельном наборе документов;

  • легче проводить release review и parity review.

Компромиссы:

  • нужно поддерживать согласованность между архитектурным уровнем и function docs;

  • planned status должен оставаться честным до появления реализации.

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

Отрицательные:

  • выше стоимость API design;

  • выше риск частичного расхождения между wrappers, если не держать discipline.

8. Что это означает practically

На ближайшую перспективу это означает:

  • Prompt Server docs должны говорить не только про Python client, но и про dual-language remote access;

  • отдельный future document должен описать local bindings strategy;

  • parity нужно валидировать по capability matrix, а не только по названию методов.

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