Core API on Rekeeply Spec

Execution Model

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

Execution Model#

Execution Modes#

embedded (default): core runs in the same process as a client application for minimum latency.
service: core runs as a separate local process and is accessed by clients via local IPC.
remote: client connects to a remote core backend over a secure network channel.

Common Rules#

same core domain logic;
authentication is mandatory;
one active session is bound to one account;
library-scoped operations work with only one active library;
clients use the core contract, not direct DB file access.

Session Lifecycle#

init: initial local vault setup and first library creation;
unlock: user authentication and opening a working session;
active: command execution in active session context (library-scoped or account-scoped);
switch-library: explicit active library switch inside a session;
auto-lock: automatic lock on inactivity timeout;
manual lock/logout: explicit lock or session termination.

Sync Model (High-Level)#

local DB is the default source of user operations;
synchronization is asynchronous and does not block user actions;
synchronization supports both library-scoped data and account-scoped data;
in offline mode, core continues to operate and sync is deferred;
conflicts are resolved by a deterministic policy (defined in a separate section);
sync data transfer must use a secure channel.

Authentication Boundary

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

Authentication Boundary#

authentication rules are defined by core;
credential validation and session issuance are performed by core;
clients only submit auth data through the core contract and store client-side session artifacts;
data access without an active valid session is forbidden.

Account Model

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

Account Model#

Contract#

Core implementations MUST include Account as a first-class domain entity.
One account MUST own zero or more libraries; each library MUST belong to exactly one account.
One active session MUST be bound to exactly one account.
Library-scoped operations in one active session MUST operate on exactly one active library.

Account Attributes#

id MUST exist and MUST be immutable.
status MUST exist and represent lock boundary (locked/unlocked or equivalent).
security_policy_ref MUST exist and MUST NOT contain plaintext secrets.
default_library_id MAY exist; when present it MUST reference a library owned by the same account.
Additional metadata MAY exist and is implementation-defined.

Lifecycle#

init MUST create exactly one local account in a new vault.
Repeated init on an initialized vault MUST be rejected unless an explicit reset/force flow is used.
Runtime state machine MUST be equivalent to uninitialized -> locked -> unlocked -> locked.

Session and Access Rules#

After unlock, session context MUST be bound to one account_id.
Raw-scoped operations MAY run without selecting an active library.
Cross-account operations in one active session MUST be rejected.
Write operations on domain entities MUST be rejected while session is locked.
Export/import operations MUST run in the active account context.

Non-Goals#

No email/username/avatar requirements.
No OAuth or social identity requirements.
No client/device UI settings in core account schema.

Library Transfer Format

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

Library Transfer Format#

Baseline#

Library export/import MUST use the *.rkl file extension.
*.rkl container MUST use tar.zst.
Text datasets inside *.rkl MUST use UTF-8 encoding.
Baseline library export scope includes library-scoped data only.
Raw data is excluded from baseline library export/import scope.
Transfer package MUST include manifest metadata, format version, and integrity data.

Package Structure 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)

Manifest Baseline#

manifest.json MUST include: format, version, encoding, container, exported_at, library, datasets, integrity.
format MUST be rkl.
encoding MUST be utf-8.
container MUST be tar.zst.
library MUST include id and name.
datasets MUST include dataset path and checksum for each included dataset.
integrity MUST include checksum algorithm and manifest checksum.

Dataset Baselines#

library.json MUST include id, name, icon.
taxonomy.json MUST include type/subtype taxonomy and field schema definitions.
content.ndjson rows MUST include id, type, status, created_at, updated_at, status_changed_at.
tags.json MUST include tag metadata.
tag_links.ndjson rows MUST include content_id, tag_id.

Taxonomy Transfer Rule#

Taxonomy MUST travel with library during export/import.
Taxonomy scope includes: content types, content subtypes, field schema definitions, tags, and tag-content links.
Import MUST restore taxonomy before or together with content datasets so content references remain valid.

Dataset Note#

Library transfer SHOULD support attachment datasets (attachment metadata and content links).

Attachment Dataset Baseline#

Attachment metadata dataset file name: attachments.ndjson.
Each attachment row MUST include: id, content_id, uri.
Optional attachment row fields: name, mime, size, created_at.
content_id in attachments.ndjson MUST reference an existing content entry.

Validation and Safety Rules#

Import MUST reject package if any required dataset is missing.
Import MUST reject package if any dataset checksum validation fails.
Import MUST reject path traversal entries (../, absolute paths, or equivalent unsafe archive paths).
Import MUST validate schema and references before final commit.
Import MUST be atomic: on critical validation error, no partial final state is committed.

Import Order Baseline#

Validate package container and manifest integrity first.
Restore library metadata (library.json).
Restore taxonomy datasets before content datasets.
Restore content datasets.
Restore tags and tag-content links.
Restore attachments.ndjson after content datasets.
Run final referential validation and commit import atomically.

Settings Model

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

Settings Model#

Scope Groups#

account-scoped
library-scoped

Library-Scoped Settings#

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

Account-Scoped Settings#

default_library_id (optional)
last_active_library_restore (boolean, default true)
auto_lock_timeout_minutes (integer, default 15, 0 means disabled)
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, used for sync_mode=auto)
export_compression_enabled (boolean, default true)
backup_enabled (boolean, default false)
backup_interval_hours (integer, default 24, used when backup is enabled)
backup_retention_count (integer, default 10)
timezone (text, default system timezone)
locale (text, default account locale or client/system fallback)

Fallback Rules#

If default_library_id is invalid or removed, fallback is last_active when available, otherwise explicit library selection.