AIDB Runtime and Storage Canon

Статус

Статус: Stage 5 runtime and storage canon draft.

Дата: 2026-05-20.

Этот документ фиксирует каноническую структуру runtime и storage boundary в проекте AIDB.

Документ не описывает реализацию кода.

1. Назначение

Этот canon закрывает:

• где живет runtime;
• где живет live runtime state;
• где живут workers и scheduled jobs;
• где живут upload/download handlers;
• границу между system/runtime и children;
• правило, когда создается папка в children;
• правило, когда достаточно записи в базе;
• границу между базой, children, uploads и runtime state;
• правило, что база данных одна.

2. Главный принцип

В AIDB нужно разделять четыре разные зоны:

1. база;
2. children;
3. uploads;
4. runtime state.

Они не являются одним и тем же.

База хранит структурную правду.

children хранит постоянный файловый инвентарь владельца.

uploads хранят тяжелые файлы и вложения.

Runtime state хранит живое техническое состояние обработки, которое не должно становиться второй базой бизнеса.

3. Каноническая runtime-структура

system/runtime/
  contracts/
  modules/
  workers/
  schedulers/
  storage/
  transfers/
  shared/

Это каноническая верхнеуровневая структура runtime-зоны AIDB.

4. Что живет в system/runtime/

system/runtime/ хранит системную runtime-сторону проекта:

• runtime contracts;
• module runtime rules;
• workers;
• scheduled jobs;
• background processing logic;
• upload/download orchestration;
• transfer helpers;
• runtime-side shared helpers.

system/runtime/ не хранит:

• client-owned documents;
• storefront pages владельца;
• постоянные business files;
• structural business truth.

5. Runtime contracts

Путь:

system/runtime/contracts/

Здесь фиксируются:

• общие runtime boundaries;
• background job rules;
• retry rules;
• lease/lock expectations;
• processing lifecycle;
• file movement rules;
• runtime/storage safety rules.

Если runtime contract нужен конкретному домену, он может дублироваться или уточняться в:

system/runtime/modules/<domain>/

6. Workers

Путь:

system/runtime/workers/

Workers закрывают:

• background processing;
• async proposal handling;
• import/export processing;
• preview generation;
• file processing;
• delivery/retry flows;
• heavy async tasks.

Worker не должен становиться hidden API module.

Если worker реализует доменную логику, у него должен быть явный runtime contract и связь с backend module.

7. Scheduled jobs

Путь:

system/runtime/schedulers/

Здесь живут:

• cron-like jobs;
• retention jobs;
• stale runtime cleanup;
• retry scheduling;
• deferred publication jobs, если они нужны;
• periodic sync or recheck flows.

Scheduled job не должен хранить business truth только в своем temp state.

8. Upload/download and transfer handling

Путь:

• system/runtime/storage/
• system/runtime/transfers/

storage/ закрывает:

• upload orchestration;
• download orchestration;
• file policy;
• storage adapters;
• size/type rules;
• access mediation.

transfers/ закрывает:

• import flows;
• export flows;
• file movement between safe zones;
• staging rules;
• handoff of generated files.

Нельзя смешивать upload temp area с permanent owner documents.

9. Live runtime state

Live runtime state - это техническое состояние живой обработки.

Примеры:

• job leases;
• queue cursors;
• processing locks;
• temporary generation artifacts;
• import/export sessions;
• retry counters;
• preview build state;
• non-business cache.

Live runtime state не должен использоваться как постоянная business truth.

Если значение критично для истории, права, заказа, relation, publication или commercial proposal, оно должно жить в базе.

10. system/runtime и children boundary

Разделение такое:

system/runtime

Хранит:

• движок обработки;
• общие workers;
• schedulers;
• системные runtime contracts;
• общую file processing orchestration.

children/.../runtime/

Хранит:

• owner-bound runtime state;
• локальные processing results;
• локальные generated artifacts;
• локальный cache;
• локальные import/export leftovers, если они принадлежат конкретному владельцу;
• локальные preview/build results конкретной сущности.

Если runtime state относится к конкретному владельцу, он должен быть отделен от общей системной runtime-зоны.

11. Когда создается папка в children

Папка в children создается, если сущность имеет хотя бы одно из этого:

• свои документы;
• свои каталоги;
• свои storefront pages;
• свои uploads;
• свой локальный runtime state;
• свой local operational inventory;
• свои generated files, которые принадлежат владельцу.

Это уже утверждено для:

• business_center - всегда;
• business_level - всегда;
• digital_space - всегда;
• installed business_contour - когда есть локальный инвентарь;
• installed app - когда есть локальные файлы или runtime.

12. Когда достаточно записи в базе

Только записи в базе достаточно, если сущность или установка означает:

• логическую активацию;
• relation without local files;
• role/rights assignment;
• metadata linkage;
• status change;
• proposal/request/order structural record;
• visibility flag;
• pricing rule;
• publication metadata без локальных owner files.

Если локального файлового или runtime инвентаря нет, отдельная папка не обязательна.

13. Что хранится в базе

В базе хранится структурная правда:

• users;
• employees;
• roles;
• RBAC assignments;
• business-center / business-level / digital-space / contour / app records;
• cards как структурные сущности;
• commercial proposals;
• client requests;
• publications;
• intercompany relations;
• commission rules and events;
• orders and statuses;
• lifecycle and visibility states;
• subscriptions, tariffs and limits;
• job metadata, если оно критично для истории и контроля;
• links between source card, proposal, publication and order.

База данных одна.

Запрещено создавать отдельную базу на каждый модуль.

14. Что хранится в children

В children хранится owner-bound постоянный файловый инвентарь:

• documents;
• catalogs;
• storefront pages;
• uploaded files;
• media;
• exports;
• imports;
• signed files;
• relation files;
• proposal attachments;
• local generated files, если они принадлежат владельцу.

children не заменяет базу и не заменяет системный runtime.

15. Что относится к runtime state

Runtime state - это:

• processing state;
• queue state;
• temporary orchestration state;
• technical retries;
• progress state;
• temporary generated results;
• cache and lock artifacts.

Runtime state не должен использоваться для хранения:

• финальных relation rules;
• финальных цен;
• финальных orders;
• финальных rights;
• финальных publication records.

16. Uploads boundary

Uploads должны быть отдельной подзоной внутри владельца или установленной сущности.

Uploads не смешиваются:

• с documents;
• с catalogs;
• с storefront pages;
• с runtime temp;
• с backend contracts.

Быстрорастущие файловые зоны должны быть отдельными по умолчанию.

17. One database rule

В AIDB база одна.

Модульность достигается не через many-databases, а через:

• domain boundaries;
• ownership boundaries;
• key-based separation;
• runtime contracts;
• storage separation.

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

• отдельную базу для Shell;
• отдельную базу для AppMarket;
• отдельную базу для personal-cabinet;
• отдельную базу для business contours;
• отдельную базу для storefront.

18. Что нельзя делать

Запрещено:

• хранить business truth в runtime temp files;
• превращать children/ в вторую базу;
• смешивать permanent documents и runtime temp в одной зоне;
• создавать папку в children только потому, что модуль существует в системе;
• хранить uploads в одном общем global dump;
• создавать отдельную базу на каждый модуль;
• хранить критические связи только в файловом виде без записи в базе.

19. Что не входит в этот документ

Этот document не фиксирует:

• конкретный database engine;
• конкретный queue engine;
• конкретный object storage provider;
• конкретный background framework;
• backup implementation;
• disaster recovery implementation;
• deployment/runtime infrastructure.

Эти зоны закрываются позже отдельными technical decisions.

20. Критерий готовности

Runtime/storage архитектура считается закрытой для Stage 5, если:

• system/runtime/ имеет каноническую map;
• workers, schedulers, storage и transfers разведены;
• live runtime state отделен от business truth;
• связь system/runtime и children/.../runtime/ зафиксирована;
• правило создания папок в children повторно закреплено;
• база, children, uploads и runtime state не смешиваются;
• правило одной базы зафиксировано;
• developer не должен сам придумывать storage boundary с нуля.