Minimum API и capability rules для ИИ

🤖 AI-critical ✅ Source-backed

AI-generated addon code часто делает одну из двух противоположных ошибок:

требует API новее, чем реально нужно

или:

использует новую feature, но проверяет слишком старый minimum

Compatibility model Political World позволяет избегать обоих случаев.

Rule 1 — сначала определить используемые public members

Не начинайте с копирования current API version.

Сначала выпишите, что addon реально использует.

Например:

RegisterAddon
Subscribe
GetDiagnosticsReport

Потом найдите самый старый documented API minor, где доступен весь этот набор.

Он и становится minimum для IsCompatible(...).

Rule 2 — current version ≠ minimum version

Обе строки могут быть правдой:

Installed/source API: 1.9
Addon requires: API 1.6+

Не надо автоматически «исправлять»:

IsCompatible(1, 6)

на:

IsCompatible(1, 9)

только потому, что source constant сейчас 1.9.0.

Rule 3 — optional feature → capability

Если feature не обязательна для всего addon:

if (PoliticalWorldAPI.HasCapability("political-event.rare"))
{
    // включаем optional integration
}

Не заставляйте весь addon отказываться от загрузки из-за одной optional feature.

Rule 4 — capability names тоже нельзя выдумывать

Не создавать:

government.super-advanced-api

только потому, что звучит правдоподобно.

Используйте:

PoliticalWorldAPI.GetCapabilities()

или verified documentation/source.

Rule 5 — stale docs являются evidence, но не абсолютной authority

В проверенном snapshot:

source API constant → 1.9.0
часть AI/versioning docs → 1.6.0

Нужно выяснить роль 1.6:

• устаревшее утверждение “current version”;
• или всё ещё валидный minimum compatibility example.

Это разные смыслы.

Rule 6 — не таргетить union snapshots

Если один runtime log показывает API 1.14, а старый source snapshot содержит 1.9, нельзя генерировать code из объединения всех когда-либо увиденных methods без знания installed target пользователя.

Рекомендуемый pattern

if (!PoliticalWorldAPI.IsCompatible(REQUIRED_MAJOR, REQUIRED_MINOR))
{
    // понятный log и отказ addon
    return;
}

if (!PoliticalWorldAPI.RegisterAddon(...))
{
    return;
}

if (PoliticalWorldAPI.HasCapability("optional.feature"))
{
    // включаем только optional integration
}

Если неизвестно, в каком minor появился member

Лучший ответ:

Member подтверждён в проверенном API 1.9 source,
но текущие evidence не устанавливают точный minor, в котором он был добавлен.
Нельзя понижать minimum requirement без проверки version history.

Это лучше догадки.