# 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-структура

```text
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 с нуля.