Account API (feature/account/api)

A small, feature‑agnostic API for representing accounts by identity only. It provides:

• Strongly‑typed account identifiers (AccountId)
• A minimal Account interface (identity only)
• A unified account sentinel for aggregated views

This module intentionally avoids feature‑specific fields (like email addresses). Mail, calendar, sync, etc. should attach their own capability models keyed by AccountId.

Core concepts

• Account: Marker interface for an account, identified solely by AccountId.
• AccountId: A concrete identifier for an account (extends BaseUuidIdentifier). Prefer this over raw strings.
• AccountIdFactory: Utility for creating/parsing AccountId values.
• UnifiedAccountId: Reserved AccountId (UUID nil) used to represent the virtual “Unified” scope across accounts.
  • AccountId.isUnified: Shorthand check for unified account id.
  • AccountId.requireReal(): Throws if called with the unified ID. Use in repositories/mutation paths.

Usage

Create a new AccountId or parse an existing one:

val id = AccountIdFactory.create()            // new random AccountId
val parsed = AccountIdFactory.of(rawString)   // parse from persisted value

Detect and guard against the unified account in write paths:

fun AccountId.requireReal(): AccountId // throws IllegalStateException for unified

if (id.isUnified) {
    // route to unified UI/aggregation services instead of repositories
}

Design guidelines

• Keep Account minimal (identity only). Do not add mail/calendar/sync fields here.
• Feature modules should define their own models keyed by AccountId.
• Do not persist data for UnifiedAccountId. Compute unified profiles/labels in UI where needed.
• Prefer strong types (AccountId) over raw strings for safety and consistency.

Related modules and types

• BaseIdentifier<T>: Generic base for identifiers (core/architecture/api)