Core API on Rekeeply Spec

Модель исполнения

Mon, 01 Jan 0001 00:00:00 +0000

Модель исполнения#

Режимы исполнения#

embedded (по умолчанию): core выполняется в одном процессе с клиентским приложением для минимальной задержки.
service: core выполняется как локальный отдельный процесс и доступен клиентам через локальный IPC-канал.
remote: клиент подключается к удаленному backend core по защищенному сетевому каналу.

Общие правила#

одна и та же доменная логика core;
обязательная аутентификация;
одна активная сессия привязана к одному аккаунту;
операции в контексте библиотеки работают только с одной активной базой;
клиент обращается к core-контракту, а не к файлу БД напрямую.

Жизненный цикл сессии#

init: первичная инициализация локального vault и создание первой базы;
unlock: аутентификация пользователя и открытие рабочей сессии;
active: выполнение команд в контексте активной сессии (library-scoped или account-scoped);
switch-library: явная смена активной базы внутри сессии;
auto-lock: автоматическая блокировка по таймауту неактивности;
manual lock/logout: ручная блокировка или завершение сессии.

Модель синхронизации (верхний уровень)#

локальная база является источником пользовательской работы по умолчанию;
синхронизация выполняется асинхронно и не блокирует пользовательские операции;
синхронизация поддерживает как данные уровня библиотеки, так и данные уровня аккаунта;
при оффлайне core продолжает работать, синхронизация откладывается;
конфликты разрешаются детерминированной политикой (уточняется отдельным разделом);
передача данных для sync выполняется только по защищенному каналу.

Граница аутентификации

Mon, 01 Jan 0001 00:00:00 +0000

Граница аутентификации#

правила аутентификации определяет core;
проверку учетных данных и выпуск сессии выполняет core;
клиент только передает аутентификационные данные в core-контракт и хранит клиентские артефакты сессии;
доступ к данным без активной валидной сессии запрещен.

Модель аккаунта

Mon, 01 Jan 0001 00:00:00 +0000

Модель аккаунта#

Контракт#

Реализация core ДОЛЖНА включать Account как доменную сущность первого класса.
Один аккаунт ДОЛЖЕН владеть нулем или более библиотек; каждая библиотека ДОЛЖНА принадлежать ровно одному аккаунту.
Одна активная сессия ДОЛЖНА быть привязана ровно к одному аккаунту.
Операции в контексте библиотеки в одной активной сессии ДОЛЖНЫ работать ровно с одной активной библиотекой.

Атрибуты аккаунта#

id ДОЛЖЕН существовать и ДОЛЖЕН быть неизменяемым.
status ДОЛЖЕН существовать и задавать границу блокировки (locked/unlocked или эквивалент).
security_policy_ref ДОЛЖЕН существовать и НЕ ДОЛЖЕН содержать секреты в открытом виде.
default_library_id МОЖЕТ присутствовать; если задан, он ДОЛЖЕН ссылаться на библиотеку того же аккаунта.
Дополнительные метаданные МОГУТ присутствовать и являются implementation-defined.

Жизненный цикл#

init ДОЛЖЕН создавать ровно один локальный аккаунт в новом vault.
Повторный init для инициализированного vault ДОЛЖЕН отклоняться, если не запущен явный reset/force flow.
Runtime-состояния ДОЛЖНЫ быть эквивалентны uninitialized -> locked -> unlocked -> locked.

Правила сессии и доступа#

После unlock сессия ДОЛЖНА быть привязана к одному account_id.
Операции уровня Raw МОГУТ выполняться без выбора активной библиотеки.
Cross-account операции в одной активной сессии ДОЛЖНЫ отклоняться.
Операции записи в доменные сущности ДОЛЖНЫ отклоняться, пока сессия заблокирована.
Операции export/import ДОЛЖНЫ выполняться в контексте активного аккаунта.

Что не входит в модель аккаунта#

Нет требований по email/username/avatar.
Нет требований по OAuth или social identity.
Нет client/device UI-настроек в core-схеме аккаунта.

Формат переноса библиотеки

Mon, 01 Jan 0001 00:00:00 +0000

Формат переноса библиотеки#

Baseline#

Экспорт/импорт библиотеки ДОЛЖЕН использовать расширение *.rkl.
Контейнер *.rkl ДОЛЖЕН использовать tar.zst.
Текстовые датасеты внутри *.rkl ДОЛЖНЫ использовать кодировку UTF-8.
Базовый scope экспорта библиотеки включает только данные уровня библиотеки.
Данные Raw исключаются из baseline scope экспорта/импорта библиотеки.
Пакет переноса ДОЛЖЕН включать manifest-метаданные, версию формата и данные целостности.

Baseline структуры пакета#

manifest.json (required)
library.json (required)
taxonomy.json (required)
content.ndjson (required)
tags.json (required)
tag_links.ndjson (required)
attachments.ndjson (required)
progress.ndjson (optional)
notes.ndjson (optional)

Baseline manifest#

manifest.json ДОЛЖЕН включать: format, version, encoding, container, exported_at, library, datasets, integrity.
format ДОЛЖЕН быть rkl.
encoding ДОЛЖЕН быть utf-8.
container ДОЛЖЕН быть tar.zst.
library ДОЛЖЕН включать id и name.
datasets ДОЛЖЕН включать путь и checksum для каждого включенного датасета.
integrity ДОЛЖЕН включать алгоритм checksum и checksum manifest.

Baseline датасетов#

library.json ДОЛЖЕН включать id, name, icon.
taxonomy.json ДОЛЖЕН включать таксономию типов/подтипов и определения схем полей.
Строки content.ndjson ДОЛЖНЫ включать id, type, status, created_at, updated_at, status_changed_at.
tags.json ДОЛЖЕН включать метаданные тегов.
Строки tag_links.ndjson ДОЛЖНЫ включать content_id, tag_id.

Правило переноса таксономии#

Таксономия ДОЛЖНА переноситься вместе с библиотекой при export/import.
В scope таксономии входят: типы контента, подтипы контента, схемы полей, теги и связи тег-контент.
Импорт ДОЛЖЕН восстанавливать таксономию до или одновременно с контентными датасетами, чтобы ссылки контента оставались валидными.

Примечание по датасетам#

Формат переноса библиотеки ДОЛЖЕН поддерживать датасеты вложений (метаданные вложений и связи с контентом).

Baseline датасета вложений#

Имя файла датасета метаданных вложений: attachments.ndjson.
Каждая строка вложения ДОЛЖНА включать: id, content_id, uri.
Опциональные поля строки вложения: name, mime, size, created_at.
content_id в attachments.ndjson ДОЛЖЕН ссылаться на существующую запись контента.

Правила валидации и безопасности#

Импорт ДОЛЖЕН отклонять пакет при отсутствии любого required датасета.
Импорт ДОЛЖЕН отклонять пакет при ошибке checksum любого датасета.
Импорт ДОЛЖЕН отклонять небезопасные пути в архиве (../, абсолютные пути и эквиваленты path traversal).
Импорт ДОЛЖЕН валидировать схему и ссылки до финального commit.
Импорт ДОЛЖЕН быть атомарным: при критической ошибке валидации частичное финальное состояние не фиксируется.

Baseline порядка импорта#

Сначала выполняется проверка контейнера пакета и целостности manifest.
Затем восстанавливаются метаданные библиотеки (library.json).
Таксономия восстанавливается до контентных датасетов.
Затем восстанавливаются контентные датасеты.
Затем восстанавливаются теги и связи тег-контент.
attachments.ndjson восстанавливается после контентных датасетов.
После этого выполняется финальная проверка ссылочной целостности и атомарный commit импорта.

Модель настроек

Mon, 01 Jan 0001 00:00:00 +0000

Модель настроек#

Группы scope#

account-scoped
library-scoped

Настройки уровня библиотеки#

default_status_on_create (enum)
default_priority_on_create (enum|null, default null)
allow_parent_links (boolean, default true)
archived_visible_by_default (boolean)

Настройки уровня аккаунта#

default_library_id (optional)
last_active_library_restore (boolean, default true)
auto_lock_timeout_minutes (integer, default 15, 0 означает отключение)
require_unlock_on_start (boolean, default true)
sync_enabled (boolean, default false)
sync_mode (enum: manual|auto, default manual)
sync_interval_minutes (integer, default 15, используется при sync_mode=auto)
export_compression_enabled (boolean, default true)
backup_enabled (boolean, default false)
backup_interval_hours (integer, default 24, используется при включенном backup)
backup_retention_count (integer, default 10)
timezone (text, default системная таймзона)
locale (text, default locale аккаунта или fallback клиента/системы)

Правила fallback#

Если default_library_id невалиден или удален, fallback: last_active при наличии, иначе явный выбор библиотеки.