@meshline/sdk 0.0.0-stage → 0.1.0-alpha.1

package/src/client/account-operations.ts

@@ -0,0 +1,183 @@
+import { createAbortController } from '../runtime/abort.js';
+import type { AccountManager } from '../components/account.js';
+import type { DeviceManager } from '../components/device.js';
+import type { ProfileManager } from '../components/profile.js';
+import type { BackgroundFailure } from '../components/component.js';
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { validateRelayId } from '../identity/neo.js';
+import { accountDeviceStateCodec, authorizedDevice, certificateId, validateDeviceState, type AccountDeviceState, type AccountRoute } from '../models/identity.js';
+import { accountProfileCodec, validateProfile, type AccountProfile } from '../models/profile.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { canonicalJson, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { abortScope, throwIfAborted, type RuntimeClock } from '../runtime/clock.js';
+import type { MeshlineStore, RecordKey } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import type { RelayClientPool } from '../transport/pool.js';
+import { RelayError } from '../transport/relay-error.js';
+
+export interface AccountEstablishmentOptions { readonly relayId?: string; readonly certificateValiditySeconds?: number; readonly routeValiditySeconds?: number }
+export interface AccountRecoveryOptions extends AccountEstablishmentOptions { readonly previousDeviceState?: AccountDeviceState; readonly deviceStateRevision?: number; readonly routeRevision?: number }
+export interface AccountOperationsOptions {
+    readonly store: MeshlineStore; readonly pool: RelayClientPool; readonly account: AccountManager; readonly device: DeviceManager; readonly profile: ProfileManager;
+    readonly context: NetworkContext; readonly accountId: string; readonly clock: RuntimeClock;
+    report(failure: BackgroundFailure): void;
+}
+const establishmentKey: RecordKey = { collection: 'client_account_operations', key: 'establishment' };
+const migrationKey: RecordKey = { collection: 'client_account_operations', key: 'migration' };
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+const day = 86400;
+function settings(source: AccountEstablishmentOptions) {
+    if (source.relayId !== undefined) validateRelayId(source.relayId);
+    const certificateValiditySeconds = source.certificateValiditySeconds ?? 365 * day; const routeValiditySeconds = source.routeValiditySeconds ?? 365 * day;
+    requireSafeInteger(certificateValiditySeconds, 1); requireSafeInteger(routeValiditySeconds, 1);
+    if (certificateValiditySeconds > 720 * day || routeValiditySeconds > 3650 * day) throw new RangeError('Account certificate or route validity exceeds its supported limit.');
+    return { ...source, certificateValiditySeconds, routeValiditySeconds };
+}
+function unavailable(error: unknown): boolean {
+    if (error instanceof AggregateError) return error.errors.length > 0 && error.errors.every(unavailable);
+    return error instanceof TypeError || error instanceof DOMException && ['TimeoutError', 'NetworkError'].includes(error.name)
+        || error instanceof RelayError && ['temporarily_unavailable', 'bad_gateway', 'rate_limited', 'route_stale', 'target_not_local', 'route_not_found'].includes(error.code);
+}
+function lookupFailure(error: unknown): boolean {
+    if (error instanceof AggregateError) return error.errors.length > 0 && error.errors.every(lookupFailure);
+    return unavailable(error) || error instanceof RelayError || error instanceof ProtocolError && !['invalid_storage', 'invalid_binding', 'context_changed', 'not_initialized', 'disposed'].includes(error.code);
+}
+
+/** Called under the owning client's account-operation gate. Child publications retain their exact signed requests. */
+export class ClientAccountOperations {
+    constructor(readonly host: AccountOperationsOptions) {}
+    async #select(requested: string | undefined, signal: AbortSignal): Promise<string> {
+        const verify = async (id: string) => { validateRelayId(id); await (await this.host.pool.get(id, undefined, signal)).getDescriptor(signal); return id; };
+        if (requested !== undefined) return verify(requested);
+        const failures: unknown[] = []; const seen = new Set<string>();
+        for await (const entry of this.host.pool.registry.getRelays(signal)) {
+            throwIfAborted(signal); if (entry.status !== 'active' || seen.has(entry.relayId)) continue; seen.add(entry.relayId);
+            try { return await verify(entry.relayId); }
+            catch (error) { throwIfAborted(signal); if (!lookupFailure(error)) throw error; failures.push(error); this.host.report({ operation: 'select_relay', resource: entry.relayId, error }); }
+        }
+        throw new ProtocolError('no_active_relay', 'No verified active relay is available.', { cause: new AggregateError(failures) });
+    }
+    async #prepareDevice(validity: number, signal: AbortSignal) {
+        const local = this.host.device.local; const now = this.host.clock.nowSeconds();
+        if (!local) return this.host.device.createDevice(validity, signal);
+        return local.notBefore <= now && now < local.expiresAt ? local : this.host.device.renewDevice(validity, signal);
+    }
+    async #confirm(relayId: string, signal: AbortSignal): Promise<void> {
+        const local = this.host.device.local; if (!local) throw new ProtocolError('device_required', 'No local device has been created.');
+        const state = await this.host.device.getOwnDeviceState(relayId, signal); if (!state) throw new ProtocolError('device_state_required', 'Home relay returned no device state after publication.');
+        authorizedDevice(state, certificateId(local, this.host.context), this.host.context, this.host.clock.nowSeconds());
+        await this.host.pool.get(relayId, { mode: 'device', signer: this.host.device }, signal);
+    }
+    async #clear(keys: readonly RecordKey[], signal: AbortSignal): Promise<void> {
+        await updateStore(this.host.store, keys, snapshot => ({ mutations: keys.flatMap((key, index) => snapshot.sets[index]!.length ? [{ kind: 'delete' as const, ...key }] : []), result: undefined }), signal);
+    }
+    async establish(source: AccountEstablishmentOptions, signal: AbortSignal): Promise<void> {
+        const options = settings(source); const { account, device, store } = this.host;
+        const route = await account.getRoute(undefined, signal);
+        if (route) {
+            if (device.local) {
+                const state = await device.getDeviceState(undefined, signal);
+                if (state && device.getAuthorizationState(certificateId(device.local, this.host.context)) === 'authorized') { await this.#clear([establishmentKey], signal); return; }
+            }
+            throw new StateConflictError('The account already has a route. Start its authorized local device or explicitly recover the account.');
+        }
+        if (account.route) throw new StateConflictError('A previous route is known. Use explicit account recovery instead of initial establishment.');
+        const initial = (await store.read([establishmentKey], signal)).sets[0]![0]?.value;
+        if (initial) { if (typeof initial.relayId !== 'string') throw new ProtocolError('invalid_storage', 'Stored establishment has no target relay.'); validateRelayId(initial.relayId); }
+        if (initial && options.relayId !== undefined && initial.relayId !== options.relayId) throw new StateConflictError('Resume establishment at its original relay or recover explicitly.');
+        const relayId = await this.#select(initial?.relayId as string | undefined ?? options.relayId, signal);
+        if (!initial) await updateStore(store, [establishmentKey], snapshot => {
+            if (snapshot.sets[0]!.length) throw new StateConflictError('Another establishment was staged concurrently.');
+            return { mutations: [{ kind: 'put', ...establishmentKey, value: { relayId } }], result: undefined };
+        }, signal);
+        const certificate = await this.#prepareDevice(options.certificateValiditySeconds, signal);
+        const publication = await device.publishDeviceState(relayId, { certificates: [certificate], signal });
+        if (publication.status !== 'staged') throw new StateConflictError('Relay already considers this account established. Resolve its route before continuing.');
+        await account.publishRoute(relayId, { validitySeconds: options.routeValiditySeconds, signal }); await this.#confirm(relayId, signal);
+        await this.#clear([establishmentKey], signal);
+    }
+    async recover(source: AccountRecoveryOptions, signal: AbortSignal): Promise<void> {
+        const options = settings(source); const previous = source.previousDeviceState && accountDeviceStateCodec.decode(accountDeviceStateCodec.encode(source.previousDeviceState));
+        if (previous) { validateDeviceState(previous, this.host.context); if (previous.account !== this.host.accountId) throw new ProtocolError('invalid_identity', 'Previous device state belongs to another account.'); }
+        if (source.deviceStateRevision !== undefined) requireSafeInteger(source.deviceStateRevision, 0); if (source.routeRevision !== undefined) requireSafeInteger(source.routeRevision, 0);
+        const { account, device } = this.host; let route: AccountRoute | undefined;
+        try { route = await account.getRoute(undefined, signal); }
+        catch (error) { throwIfAborted(signal); if (!lookupFailure(error)) throw error; this.host.report({ operation: 'resolve_recovery_route', error }); }
+        let relayId: string;
+        if (options.relayId === undefined && route) {
+            try { relayId = await this.#select(route.relayId, signal); }
+            catch (error) { throwIfAborted(signal); if (!lookupFailure(error)) throw error; this.host.report({ operation: 'select_recovery_relay', resource: route.relayId, error }); relayId = await this.#select(undefined, signal); }
+        } else relayId = await this.#select(options.relayId, signal);
+        if (account.route) {
+            try { await device.getOwnDeviceState(account.route.relayId, signal); }
+            catch (error) { throwIfAborted(signal); if (!lookupFailure(error)) throw error; this.host.report({ operation: 'resolve_recovery_devices', resource: account.route.relayId, error }); }
+        }
+        await this.#prepareDevice(options.certificateValiditySeconds, signal);
+        await device.publishDeviceState(relayId, { ...(previous ? { previousState: previous } : {}), recovery: true, ...(source.deviceStateRevision === undefined ? {} : { revision: source.deviceStateRevision }), signal });
+        await account.publishRoute(relayId, { validitySeconds: options.routeValiditySeconds, recovery: true, ...(source.routeRevision === undefined ? {} : { revision: source.routeRevision }), signal });
+        await this.#confirm(relayId, signal); await this.#clear([establishmentKey, migrationKey], signal);
+    }
+    async #route(signal: AbortSignal): Promise<AccountRoute | undefined> {
+        const previous = this.host.account.route;
+        try { return await this.host.account.getRoute(undefined, signal) ?? previous; }
+        catch (error) { throwIfAborted(signal); if (!previous || !unavailable(error)) throw error; this.host.report({ operation: 'resolve_migration_route', resource: previous.relayId, error }); return previous; }
+    }
+    async #deviceState(source: string, fallback: AccountDeviceState | undefined, signal: AbortSignal): Promise<AccountDeviceState> {
+        try { await this.host.device.getOwnDeviceState(source, signal); }
+        catch (error) { throwIfAborted(signal); if (!unavailable(error)) throw error; this.host.report({ operation: 'resolve_migration_devices', resource: source, error }); }
+        const current = this.host.device.deviceState; const state = current && (!fallback || current.revision > fallback.revision) ? current : fallback;
+        if (!state) throw new StateConflictError('The complete previous device state is unavailable. Recover explicitly rather than discarding other devices.');
+        const local = this.host.device.local;
+        if (!local || !state.certificates.some(value => certificateId(value, this.host.context) === certificateId(local, this.host.context))) throw new StateConflictError('Authorize the local device or recover explicitly before migrating.');
+        return state;
+    }
+    async #profile(signal: AbortSignal): Promise<AccountProfile | undefined> {
+        const previous = this.host.profile.profile;
+        try { return await this.host.profile.getProfile(undefined, signal) ?? previous; }
+        catch (error) { throwIfAborted(signal); if (!unavailable(error)) throw error; this.host.report({ operation: 'resolve_migration_profile', error }); return previous; }
+    }
+    #migration(value: JsonObject) {
+        if (typeof value.source !== 'string' || typeof value.target !== 'string') throw new ProtocolError('invalid_storage', 'Stored migration has no source or target relay.');
+        validateRelayId(value.source); validateRelayId(value.target); requireSafeInteger(value.routeValiditySeconds, 1);
+        const state = accountDeviceStateCodec.decode(value.deviceState!); validateDeviceState(state, this.host.context);
+        const profile = value.profile === undefined ? undefined : accountProfileCodec.decode(value.profile); if (profile) validateProfile(profile);
+        if (state.account !== this.host.accountId || profile && profile.account !== this.host.accountId) throw new ProtocolError('invalid_storage', 'Migration snapshot belongs to another account.');
+        return { source: value.source, target: value.target, state, profile, routeValiditySeconds: value.routeValiditySeconds };
+    }
+    async resumeMigration(signal: AbortSignal): Promise<void> { const value = (await this.host.store.read([migrationKey], signal)).sets[0]![0]?.value; if (value) await this.migrate(this.#migration(value).target, signal); }
+    async migrate(relayId: string, signal: AbortSignal): Promise<void> {
+        validateRelayId(relayId); const { store, account, device, profile, clock } = this.host;
+        let value = (await store.read([migrationKey], signal)).sets[0]![0]?.value; let migration = value && this.#migration(value);
+        if (migration && migration.target !== relayId) throw new StateConflictError('Resume migration to its original target or recover explicitly.');
+        const route = await this.#route(signal); if (!route) throw new StateConflictError('No previous route is available. Establish or recover the account.');
+        if (!migration && route.relayId === relayId && route.expiresAt > clock.nowSeconds()) return;
+        await this.#select(relayId, signal);
+        if (!migration) {
+            const state = await this.#deviceState(route.relayId, undefined, signal); const previousProfile = await this.#profile(signal);
+            if (account.route && account.route.relayId !== route.relayId) throw new StateConflictError('Account moved while migration was being prepared.');
+            value = { source: route.relayId, target: relayId, deviceState: accountDeviceStateCodec.encode(state), routeValiditySeconds: route.expiresAt - route.updatedAt, ...(previousProfile ? { profile: accountProfileCodec.encode(previousProfile) } : {}) };
+            const prepared = value;
+            await updateStore(store, [migrationKey, { collection: 'account_routes', key: this.host.accountId }], snapshot => {
+                if (snapshot.sets[0]!.length || snapshot.sets[1]![0]?.value.relay_id !== route.relayId) throw new StateConflictError('Account migration or route changed before staging.');
+                return { mutations: [{ kind: 'put', ...migrationKey, value: prepared }], result: undefined };
+            }, signal); migration = this.#migration(value);
+        }
+        if (route.relayId !== migration.source && route.relayId !== migration.target) throw new StateConflictError('Account moved to a third relay after this migration began. Resolve the concurrent change or recover explicitly.');
+        if (route.relayId !== relayId || route.expiresAt <= clock.nowSeconds()) {
+            const state = await this.#deviceState(migration.source, migration.state, signal); const local = device.local!;
+            if (local.notBefore > clock.nowSeconds()) throw new StateConflictError('Local device certificate is not yet valid.');
+            await this.#prepareDevice(local.expiresAt - local.notBefore, signal); const publication = await device.publishDeviceState(relayId, { previousState: state, signal });
+            if (publication.status === 'staged' && publication.stagedUntil! - clock.nowSeconds() < 60) throw new StateConflictError('Staged device state must remain available for at least one minute.');
+            if (account.route && account.route.relayId !== migration.source && account.route.relayId !== migration.target) throw new StateConflictError('Account moved to a third relay during migration preparation.');
+            const deadline = createAbortController(); const window = abortScope([signal, deadline.signal]);
+            const timer = publication.status === 'staged' ? clock.delay(60000, deadline.signal).then(() => deadline.abort(new DOMException('Migration route publication deadline expired.', 'TimeoutError')), error => { if (!deadline.signal.aborted) deadline.abort(error); }) : undefined;
+            try { await account.publishRoute(relayId, { validitySeconds: migration.routeValiditySeconds, signal: window.signal }); }
+            finally { deadline.abort(); window.dispose(); await timer; }
+        }
+        await this.#confirm(relayId, signal); await profile.publishProfile(migration.profile, signal);
+        await updateStore(store, [migrationKey], snapshot => {
+            if (fingerprint(snapshot.sets[0]![0]?.value) !== fingerprint(value)) throw new StateConflictError('Pending migration changed before completion.');
+            return { mutations: [{ kind: 'delete', ...migrationKey }], result: undefined };
+        }, signal);
+    }
+}

package/src/client/conversations.ts

@@ -0,0 +1,95 @@
+import { ProtocolError } from '../errors.js';
+import { decodeGroupProjection } from '../groups/repository.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId } from '../identity/neo.js';
+import { snapshotReader } from '../messages/repository.js';
+import { channelPostCodec, validateChannelRef } from '../models/channels.js';
+import { groupEventCodec } from '../models/group-management.js';
+import { groupMessageCodec, groupMessageEnvelopeCodec } from '../models/groups.js';
+import { directMessageCodec } from '../models/messages.js';
+import { requireObject, requireSafeInteger } from '../protocol/json.js';
+import type { MeshlineStore, QueryReader, RecordQuery, StoreSnapshot } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+
+export type ConversationKind = 'direct' | 'group' | 'channel';
+export interface ConversationSummary { readonly sender: string; readonly timestamp: number; readonly text?: string; readonly hasAttachments: boolean }
+export interface Conversation { readonly conversationId: string; readonly kind: ConversationKind; readonly latest?: ConversationSummary; readonly unreadCount: number }
+export interface ConversationQuery { readonly kinds?: readonly ConversationKind[]; readonly unreadOnly?: boolean; readonly hasMessages?: boolean }
+export interface ConversationChange { readonly conversationId: string; readonly kind: 'created' | 'updated' | 'removed' }
+interface Content { sequence: number; summary: ConversationSummary }
+interface Projection { conversation: Conversation; head?: number }
+const queries: readonly RecordQuery[] = ['messages', 'groups', 'group_events', 'channels', 'channel_posts', 'conversation_reads'].map(collection => ({ collection }));
+const readKey = (conversationId: string) => ({ collection: 'conversation_reads', key: conversationId });
+const compare = (a: string, b: string) => a === b ? 0 : a < b ? -1 : 1;
+export function conversationKind(id: string): ConversationKind {
+    if (id.startsWith('grp_')) { validateIdentifier('group', id); return 'group'; }
+    if (id.startsWith('chan_')) { validateIdentifier('channel', id); return 'channel'; }
+    validateAccountId(id); return 'direct';
+}
+function content(sequence: unknown, sender: unknown, timestamp: unknown, value: { readonly body?: { readonly text?: string }; readonly attachments?: readonly unknown[] }): Content {
+    requireSafeInteger(sequence, 0); requireSafeInteger(timestamp, 0); if (typeof sender !== 'string') throw new ProtocolError('invalid_storage', 'Conversation item has no sender.'); validateAccountId(sender);
+    return { sequence, summary: { sender, timestamp, ...(value.body?.text === undefined ? {} : { text: value.body.text }), hasAttachments: Boolean(value.attachments?.length) } };
+}
+
+/** All summaries and read positions come from one fixed storage snapshot. */
+export class ClientConversations {
+    constructor(readonly store: MeshlineStore, readonly accountId: string) {}
+    #project(snapshot: StoreSnapshot, includeUnfollowed = false): readonly Projection[] {
+        const [messages, groups, groupEvents, channels, channelPosts, reads] = snapshot.sets; const positions = new Map<string, number>();
+        for (const row of reads!) { conversationKind(row.key); requireSafeInteger(row.value.sequence, 0); positions.set(row.key, row.value.sequence); }
+        const records = new Map<string, { kind: ConversationKind; items: Content[] }>();
+        const add = (id: string, kind: ConversationKind, item?: Content) => { const record = records.get(id) ?? { kind, items: [] }; if (item) record.items.push(item); records.set(id, record); };
+        for (const row of messages!) {
+            const value = row.value; if (value.payloadType !== 'meshline.message.direct' || value.sender !== this.accountId && value.recipient !== this.accountId) continue;
+            if (typeof value.sender !== 'string' || typeof value.recipient !== 'string') throw new ProtocolError('invalid_storage', 'Direct conversation has malformed participants.');
+            const peer = value.sender === this.accountId ? value.recipient : value.sender; validateAccountId(peer);
+            add(peer, 'direct', content(value.localSequence, value.sender, value.createdAt, directMessageCodec.decode(value.payload!)));
+        }
+        const knownGroups = new Set(groups!.map(row => row.key));
+        for (const row of groups!) {
+            const group = { groupId: row.key, relayId: String(row.value.relayId) }; if (!row.value.projection) continue;
+            const state = decodeGroupProjection(requireObject(row.value.projection), group);
+            if (row.value.localDepartureAfter !== undefined) { requireSafeInteger(row.value.localDepartureAfter, 0); if (state.sequence <= row.value.localDepartureAfter) continue; }
+            if (state.members.some(value => value.account === this.accountId)) add(row.key, 'group');
+        }
+        for (const row of groupEvents!) {
+            const value = row.value; if (value.isMessage !== true || value.decryptedPayload === undefined) continue;
+            const event = groupEventCodec.decode(value.event!); const envelope = groupMessageEnvelopeCodec.decode(event.payload);
+            if (!knownGroups.has(envelope.groupId) || row.key !== `${envelope.groupId}|${String(event.sequence).padStart(16, '0')}`) throw new ProtocolError('invalid_storage', 'Group conversation event has no consistent hosting association.');
+            add(envelope.groupId, 'group', content(event.sequence, requireObject(value.message!).sender, envelope.createdAt, groupMessageCodec.decode(value.decryptedPayload)));
+        }
+        const followed = new Set<string>();
+        for (const row of channels!) {
+            validateChannelRef({ channelId: row.key, relayId: String(row.value.relayId) });
+            if (typeof row.value.isFollowed !== 'boolean') throw new ProtocolError('invalid_storage', 'Channel conversation has no followed state.');
+            if (row.value.isFollowed || includeUnfollowed) { followed.add(row.key); add(row.key, 'channel'); }
+        }
+        for (const row of channelPosts!) {
+            const value = row.value; const channelId = row.key.split('|')[0]!; if (!followed.has(channelId) || value.isDeleted === true || value.post === undefined) continue;
+            const post = channelPostCodec.decode(value.post); if (post.channelId !== channelId || row.key !== `${channelId}|${String(value.sequence).padStart(16, '0')}`) throw new ProtocolError('invalid_storage', 'Channel conversation post differs from its storage identity.');
+            add(channelId, 'channel', content(value.sequence, value.author, value.acceptedAt, post));
+        }
+        return [...records].map(([conversationId, record]) => {
+            const position = positions.get(conversationId) ?? -1; let latest: Content | undefined; let unreadCount = 0;
+            for (const item of record.items) { if (!latest || item.sequence > latest.sequence) latest = item; if (item.summary.sender !== this.accountId && item.sequence > position) unreadCount++; }
+            return { conversation: { conversationId, kind: record.kind, unreadCount, ...(latest ? { latest: latest.summary } : {}) }, ...(latest ? { head: latest.sequence } : {}) };
+        }).sort((a, b) => (b.conversation.latest?.timestamp ?? -1) - (a.conversation.latest?.timestamp ?? -1) || compare(a.conversation.conversationId, b.conversation.conversationId));
+    }
+    async list(query: ConversationQuery = {}, signal?: AbortSignal): Promise<QueryReader<Conversation>> {
+        const kinds = query.kinds && [...query.kinds]; const { unreadOnly, hasMessages } = query;
+        if (kinds?.some(value => !['direct', 'group', 'channel'].includes(value)) || unreadOnly !== undefined && typeof unreadOnly !== 'boolean' || hasMessages !== undefined && typeof hasMessages !== 'boolean') throw new TypeError('Invalid conversation filter.');
+        const records = this.#project(await this.store.read(queries, signal));
+        return snapshotReader(records.map(value => value.conversation).filter(value => (!kinds || kinds.includes(value.kind)) && (!unreadOnly || value.unreadCount > 0) && (hasMessages === undefined || Boolean(value.latest) === hasMessages)));
+    }
+    async get(id: string, signal?: AbortSignal): Promise<Conversation | undefined> { conversationKind(id); return this.#project(await this.store.read(queries, signal)).find(value => value.conversation.conversationId === id)?.conversation; }
+    async ids(signal?: AbortSignal): Promise<ReadonlySet<string>> { return new Set(this.#project(await this.store.read(queries, signal)).map(value => value.conversation.conversationId)); }
+    async markRead(id: string, signal?: AbortSignal): Promise<boolean> {
+        conversationKind(id);
+        return updateStore(this.store, queries, snapshot => {
+            const projection = this.#project(snapshot, true).find(value => value.conversation.conversationId === id); const sequence = projection?.head;
+            const before = snapshot.sets[5]!.find(row => row.key === id)?.value.sequence ?? -1; requireSafeInteger(before, -1);
+            if (sequence === undefined || sequence <= before) return { mutations: [], result: false };
+            return { mutations: [{ kind: 'put', ...readKey(id), value: { sequence } }], result: true };
+        }, signal);
+    }
+}

package/src/client.ts

@@ -0,0 +1,108 @@
+import { createAbortController } from './runtime/abort.js';
+import { AccountManager } from './components/account.js';
+import { ChannelManager } from './components/channel.js';
+import { ClientComponent, type ClientOptions } from './components/component.js';
+import { DeviceManager } from './components/device.js';
+import { GroupManager } from './components/group.js';
+import { MessageManager } from './components/message.js';
+import { ProfileManager } from './components/profile.js';
+import { ClientAccountOperations, type AccountEstablishmentOptions, type AccountRecoveryOptions } from './client/account-operations.js';
+import { ClientConversations, type ConversationChange, type ConversationQuery } from './client/conversations.js';
+import type { RandomSource } from './crypto/primitives.js';
+import type { AccountSigner, SecretProtector } from './interactions.js';
+import { accountDeviceStateCodec } from './models/identity.js';
+import { AsyncGate } from './runtime/async-gate.js';
+import { AsyncPulse } from './runtime/async-pulse.js';
+import { EventHub, type EventListener } from './runtime/events.js';
+import type { MeshlineStore } from './storage/store.js';
+import type { RelayClientPool } from './transport/pool.js';
+
+export type { AccountEstablishmentOptions, AccountRecoveryOptions } from './client/account-operations.js';
+export type { Conversation, ConversationChange, ConversationKind, ConversationQuery, ConversationSummary } from './client/conversations.js';
+export interface MeshlineClientEvents { readonly conversationChanged: ConversationChange }
+export interface MeshlineClientOptions extends ClientOptions {
+    readonly store: MeshlineStore; readonly relayClients: RelayClientPool; readonly secretProtector: SecretProtector;
+    readonly accountSigner?: AccountSigner; readonly random?: RandomSource;
+}
+
+/** Owns six managers; the application retains ownership of the migrated store, pool, signer and protector. */
+export class MeshlineClient extends ClientComponent {
+    readonly accountManager: AccountManager; readonly deviceManager: DeviceManager; readonly profileManager: ProfileManager;
+    readonly messageManager: MessageManager; readonly channelManager: ChannelManager; readonly groupManager: GroupManager;
+    readonly #components: readonly ClientComponent[]; readonly #detach: (() => void)[] = [];
+    readonly #accountGate = new AsyncGate(); readonly #accountOperations: ClientAccountOperations;
+    readonly #conversations: ClientConversations; readonly #events = new EventHub<MeshlineClientEvents>();
+    readonly #conversationLifetime = createAbortController(); readonly #conversationPulse = new AsyncPulse(); readonly #pendingConversations = new Set<string>();
+    #conversationIds: ReadonlySet<string> = new Set(); #conversationJob: Promise<void> | undefined;
+    constructor(options: MeshlineClientOptions) {
+        super(options);
+        this.accountManager = new AccountManager(options);
+        this.deviceManager = new DeviceManager({ ...options, accountManager: this.accountManager });
+        this.profileManager = new ProfileManager({ ...options, accountManager: this.accountManager, deviceSigner: this.deviceManager });
+        this.messageManager = new MessageManager({ ...options, accountManager: this.accountManager, deviceManager: this.deviceManager });
+        this.channelManager = new ChannelManager({ ...options, deviceManager: this.deviceManager });
+        this.groupManager = new GroupManager({ ...options, deviceManager: this.deviceManager, messageManager: this.messageManager });
+        this.#components = [this.accountManager, this.deviceManager, this.profileManager, this.messageManager, this.channelManager, this.groupManager];
+        for (const component of this.#components) this.#detach.push(component.onLifecycle('backgroundError', error => this.notifyBackgroundError(error)));
+        this.#accountOperations = new ClientAccountOperations({ store: options.store, pool: options.relayClients, account: this.accountManager, device: this.deviceManager, profile: this.profileManager,
+            context: this.context, accountId: this.accountId, clock: this.clock, report: failure => this.notifyBackgroundError(failure) });
+        this.#conversations = new ClientConversations(options.store, this.accountId);
+        this.#detach.push(this.messageManager.on('messageReceived', messages => { for (const message of messages) this.#queueConversation(message.key.sender === this.accountId ? message.recipient : message.key.sender); }),
+            this.messageManager.on('sendStatusChanged', status => { if (status.state === 'queued') this.#queueConversation(status.recipient); }),
+            this.channelManager.on('timelineChanged', value => this.#queueConversation(value.channel.channelId)), this.channelManager.on('followChanged', value => this.#queueConversation(value.channel.channelId)),
+            this.groupManager.on('timelineChanged', value => { if (value.message) this.#queueConversation(value.group.groupId); }), this.groupManager.on('groupChanged', value => this.#queueConversation(value.ref.groupId)));
+    }
+    get route() { return this.accountManager.route; }
+    get device() { return this.deviceManager.local; }
+    get deviceState() { return this.deviceManager.deviceState; }
+    get profile() { return this.profileManager.profile; }
+    on<K extends keyof MeshlineClientEvents>(event: K, listener: EventListener<MeshlineClientEvents[K]>): () => void { return this.#events.on(event, listener); }
+    getConversations(query: ConversationQuery = {}, signal?: AbortSignal) { const copy = { ...query, ...(query.kinds ? { kinds: [...query.kinds] } : {}) }; return this.runOperation(scope => this.#conversations.list(copy, scope), signal); }
+    getConversation(conversationId: string, signal?: AbortSignal) { return this.runOperation(scope => this.#conversations.get(conversationId, scope), signal); }
+    async markRead(conversationId: string, signal?: AbortSignal): Promise<void> { if (await this.runOperation(scope => this.#conversations.markRead(conversationId, scope), signal)) this.#queueConversation(conversationId); }
+    #queueConversation(id: string): void { if (this.#conversationLifetime.signal.aborted) return; this.#pendingConversations.add(id); this.#conversationPulse.pulse(); }
+    async #observeConversations(): Promise<void> {
+        const signal = this.#conversationLifetime.signal;
+        try { for (;;) {
+            await this.#conversationPulse.wait(signal); const pending = [...this.#pendingConversations]; this.#pendingConversations.clear(); if (!pending.length) continue;
+            let present: ReadonlySet<string>;
+            try { present = await this.#conversations.ids(signal); }
+            catch (error) { if (signal.aborted) throw error; this.notifyBackgroundError({ operation: 'synchronize_conversations', error }); for (const id of pending) this.#queueConversation(id); await this.clock.delay(1000, signal); continue; }
+            for (const id of pending) {
+                if (signal.aborted) return;
+                const kind = present.has(id) ? this.#conversationIds.has(id) ? 'updated' : 'created' : this.#conversationIds.has(id) ? 'removed' : undefined;
+                if (kind) this.#events.notify('conversationChanged', { conversationId: id, kind }, error => this.notifyBackgroundError({ operation: 'observer', resource: 'conversationChanged', error }));
+            }
+            // Preserve membership for other queued IDs until their own notification is processed.
+            const next = new Set(this.#conversationIds); for (const id of pending) { if (present.has(id)) next.add(id); else next.delete(id); } this.#conversationIds = next;
+        } } catch (error) { if (!signal.aborted) this.notifyBackgroundError({ operation: 'observe_conversations', error }); }
+    }
+    establishAccount(options: AccountEstablishmentOptions = {}, signal?: AbortSignal): Promise<void> {
+        const copy = { ...options }; return this.runOperation(scope => this.#accountGate.run(() => this.#accountOperations.establish(copy, scope), scope), signal);
+    }
+    recoverAccount(options: AccountRecoveryOptions = {}, signal?: AbortSignal): Promise<void> {
+        const copy = { ...options, ...(options.previousDeviceState ? { previousDeviceState: accountDeviceStateCodec.decode(accountDeviceStateCodec.encode(options.previousDeviceState)) } : {}) };
+        return this.runOperation(scope => this.#accountGate.run(() => this.#accountOperations.recover(copy, scope), scope), signal);
+    }
+    changeHomeRelay(relayId: string, signal?: AbortSignal): Promise<void> { return this.runOperation(scope => this.#accountGate.run(() => this.#accountOperations.migrate(relayId, scope), scope), signal); }
+    protected override async onInitialize(signal: AbortSignal): Promise<void> {
+        for (const component of this.#components) await component.initialize(signal);
+        this.#conversationIds = await this.#conversations.ids(signal); this.#conversationJob ??= this.#observeConversations();
+    }
+    protected override async onStart(signal: AbortSignal): Promise<void> {
+        await this.accountManager.start(signal);
+        await this.#accountGate.run(() => this.#accountOperations.resumeMigration(signal), signal);
+        for (const component of this.#components.slice(1)) await component.start(signal);
+    }
+    protected override async onStop(): Promise<void> {
+        const errors: unknown[] = []; for (const component of [...this.#components].reverse()) { try { await component.stop(); } catch (error) { errors.push(error); } }
+        if (errors.length) throw new AggregateError(errors, 'One or more client components failed to stop.');
+    }
+    protected override async onDispose(): Promise<void> {
+        this.#conversationLifetime.abort(); await this.#conversationJob;
+        const errors: unknown[] = []; for (const component of [...this.#components].reverse()) { try { await component.dispose(); } catch (error) { errors.push(error); } }
+        for (const detach of this.#detach) detach();
+        this.#events.clear();
+        if (errors.length) throw new AggregateError(errors, 'One or more client components failed to dispose.');
+    }
+}

package/src/components/account.ts

@@ -0,0 +1,206 @@
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { matchesAccount, validateAccountId, validateRelayId, verifyRelay } from '../identity/neo.js';
+import type { AccountSigner } from '../interactions.js';
+import { accountRouteCodec, compareRoutes, routeAccountInput, routeRelayInput, validateRoute, type AccountRoute } from '../models/identity.js';
+import { nextRevision } from '../protocol/context.js';
+import { canonicalJson, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { AsyncGate } from '../runtime/async-gate.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import { EventHub, type EventListener } from '../runtime/events.js';
+import type { MeshlineStore, RecordKey, StoreMutation } from '../storage/store.js';
+import { finishSignedRequest, putSignedRequest, readSignedRequest, requestKey, type SignedRequest } from '../storage/signed-request.js';
+import { updateStore } from '../storage/transaction.js';
+import type { RelayClientPool } from '../transport/pool.js';
+import { RelayError } from '../transport/relay-error.js';
+import { ClientComponent, type BackgroundFailure, type ClientOptions } from './component.js';
+
+export type AccountState = 'unknown' | 'notEstablished' | 'established';
+export interface AccountSnapshot { readonly state: AccountState; readonly route: AccountRoute | undefined }
+export interface AccountEvents { readonly accountChanged: AccountSnapshot }
+export interface AccountManagerOptions extends ClientOptions { readonly store: MeshlineStore; readonly relayClients: RelayClientPool; readonly accountSigner?: AccountSigner }
+export interface PublishRouteOptions { readonly validitySeconds: number; readonly revision?: number; readonly recovery?: boolean; readonly signal?: AbortSignal }
+const method = 'account.route.publish';
+const routeKey = (account: string): RecordKey => ({ collection: 'account_routes', key: account });
+const clone = (route: AccountRoute): AccountRoute => accountRouteCodec.decode(accountRouteCodec.encode(route));
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+
+/** Signed route discovery and durable, explicit publication retries. */
+export class AccountManager extends ClientComponent {
+    readonly #store: MeshlineStore;
+    readonly #pool: RelayClientPool;
+    readonly #signer: AccountSigner | undefined;
+    readonly #gate = new AsyncGate();
+    readonly #events = new EventHub<AccountEvents>();
+    #state: AccountState = 'unknown';
+    #route: AccountRoute | undefined;
+
+    constructor(options: AccountManagerOptions) {
+        super(options);
+        if (options.relayClients.accountId !== this.accountId || options.relayClients.context.toString() !== this.context.toString())
+            throw new ProtocolError('invalid_context', 'Relay pool belongs to another account or network.');
+        this.#store = options.store; this.#pool = options.relayClients; this.#signer = options.accountSigner;
+    }
+    get state(): AccountState { return this.#state; }
+    get route(): AccountRoute | undefined { return this.#route && clone(this.#route); }
+    on<K extends keyof AccountEvents>(event: K, listener: EventListener<AccountEvents[K]>): () => void { return this.#events.on(event, listener); }
+    protected override async onInitialize(signal: AbortSignal): Promise<void> {
+        await this.#store.initialize({ context: this.context.toString(), accountId: this.accountId }, signal);
+        const value = (await this.#store.read([routeKey(this.accountId)], signal)).sets[0]![0]?.value;
+        const route = value === undefined ? undefined : accountRouteCodec.decode(value);
+        if (route) {
+            validateRoute(route, this.context, 0);
+            if (route.account !== this.accountId) throw new ProtocolError('invalid_storage', 'Stored route belongs to another account.');
+        }
+        this.#route = route; this.#state = route && route.expiresAt > this.clock.nowSeconds() ? 'established' : 'unknown';
+    }
+    #accept(route: AccountRoute | undefined): boolean {
+        const state = route ? 'established' : 'unknown';
+        const changed = this.#state !== state || route !== undefined && accountRouteCodec.stringify(route) !== (this.#route && accountRouteCodec.stringify(this.#route));
+        this.#state = state;
+        if (route) this.#route = clone(route);
+        return changed;
+    }
+    #changed(): void { this.#events.notify('accountChanged', { state: this.state, route: this.route }, error => this.notifyBackgroundError({ operation: 'observer', resource: 'accountChanged', error })); }
+    async getRoute(accountId = this.accountId, signal?: AbortSignal): Promise<AccountRoute | undefined> {
+        validateAccountId(accountId);
+        const failures: BackgroundFailure[] = [];
+        let changed = false;
+        let route: AccountRoute | undefined;
+        let operationError: unknown; let failed = false;
+        try {
+            route = await this.runOperation(scope => this.#gate.run(async () => {
+                const resolved = await this.#resolve(accountId, failures, scope);
+                if (accountId === this.accountId) changed = this.#accept(resolved);
+                return resolved;
+            }, scope), signal);
+        } catch (error) { failed = true; operationError = error; }
+        for (const failure of failures) this.notifyBackgroundError(failure);
+        if (changed) this.#changed();
+        if (failed) throw operationError;
+        return route && clone(route);
+    }
+    async #resolve(accountId: string, failures: BackgroundFailure[], signal: AbortSignal): Promise<AccountRoute | undefined> {
+        const previous = (await this.#store.read([routeKey(accountId)], signal)).sets[0]![0]?.value;
+        const known = previous === undefined ? undefined : accountRouteCodec.decode(previous);
+        let attempted = false;
+        for await (const entry of this.#pool.registry.getRelays(signal)) {
+            throwIfAborted(signal);
+            if (entry.status !== 'active') continue;
+            attempted = true;
+            let route: AccountRoute;
+            try {
+                const client = await this.#pool.get(entry.relayId, undefined, signal);
+                const response = await client.requestHttp('GET', 'account.route.resolve', { account: accountId }, { authenticated: false, signal });
+                if (response === undefined) throw new ProtocolError('invalid_response', 'Route resolution returned no document.');
+                route = accountRouteCodec.decode(response);
+                if (route.account !== accountId) throw new ProtocolError('invalid_identity', 'Resolved route belongs to another account.');
+                if (known && route.revision < known.revision) throw new ProtocolError('stale_route', 'Relay returned an older route.');
+                await this.#verifyRelay(route, signal);
+            } catch (error) {
+                throwIfAborted(signal);
+                if (error instanceof RelayError) {
+                    if (error.code === 'not_found') continue;
+                    if (!['temporarily_unavailable', 'bad_gateway', 'rate_limited'].includes(error.code)) throw error;
+                } else if (!(error instanceof Error)) throw error;
+                failures.push({ operation: 'connect', resource: entry.relayId, error }); continue;
+            }
+            await this.#save(route, signal); return route;
+        }
+        if (failures.length) throw new AggregateError(failures.map(value => value.error), 'Account route discovery failed through the available relays.');
+        if (!attempted) throw new ProtocolError('no_active_relay', 'No active relay is available for route discovery.');
+        return undefined;
+    }
+    async publishRoute(relayId: string, options: PublishRouteOptions): Promise<AccountRoute> {
+        options = { ...options };
+        validateRelayId(relayId); requireSafeInteger(options.validitySeconds, 1);
+        if (options.validitySeconds > 3650 * 86400) throw new RangeError('Route validity cannot exceed 3650 days.');
+        if (options.revision !== undefined) requireSafeInteger(options.revision, 0);
+        const signer = this.#signer;
+        if (!signer) throw new ProtocolError('signer_required', 'An account signer is required to publish a route.');
+        let changed = false;
+        const result = await this.runOperation(signal => this.#gate.run(async () => {
+            const signed = await this.#prepare(relayId, options, signer, signal);
+            const request = accountRouteCodec.decode(signed.document);
+            const client = await this.#pool.get(relayId, { mode: 'account', signer }, signal);
+            let response;
+            try { response = await client.requestHttp('PUT', method, signed.document, { signal }); }
+            catch (error) {
+                if (error instanceof RelayError && error.isDefinitiveRejection) {
+                    try { await finishSignedRequest(this.#store, method, signed); }
+                    catch (storageError) { throw new AggregateError([error, storageError], 'Relay rejected publication but its durable result could not be saved.'); }
+                }
+                throw error;
+            }
+            if (response === undefined) throw new ProtocolError('invalid_response', 'Route publication returned no acknowledgement.');
+            const route = accountRouteCodec.decode(response);
+            const acknowledged = accountRouteCodec.encode(route); delete acknowledged.relay_signature;
+            if (canonicalJson(acknowledged) !== accountRouteCodec.stringify(request)) throw new ProtocolError('invalid_response', 'Relay modified the submitted route.');
+            await this.#verifyRelay(route, signal); await this.#save(route, signal);
+            changed = this.#accept(route); return route;
+        }, signal), options.signal);
+        if (changed) this.#changed();
+        return clone(result);
+    }
+    async #prepare(relayId: string, options: PublishRouteOptions, signer: AccountSigner, signal: AbortSignal): Promise<SignedRequest> {
+        const queries = [routeKey(this.accountId), requestKey(method)];
+        const snapshot = await this.#store.read(queries, signal);
+        const previous = snapshot.sets[0]![0]?.value;
+        const saved = snapshot.sets[1]![0]?.value;
+        const known = previous === undefined ? undefined : accountRouteCodec.decode(previous);
+        const signed = readSignedRequest(saved);
+        const knownRevision = Math.max(known?.revision ?? -1, signed?.revision ?? -1);
+        const pending = signed?.pending ? accountRouteCodec.decode(signed.document) : undefined;
+        const now = this.clock.nowSeconds(); requireSafeInteger(now, 0);
+        let revision = options.revision;
+        if (options.recovery && revision === undefined && (!pending || signed!.relayId !== relayId || pending.expiresAt <= now))
+            revision = Math.max(nextRevision(knownRevision), now * 1000);
+        else if (revision === undefined && pending && signed!.relayId === relayId && pending.expiresAt <= now) revision = nextRevision(knownRevision);
+        if (signed?.pending && (revision === undefined || revision === signed.revision)) {
+            const route = pending!;
+            validateRoute(route, this.context, now);
+            if (route.account !== this.accountId || signed.relayId !== relayId || route.relayId !== relayId || route.revision !== signed.revision
+                || route.expiresAt - route.updatedAt !== options.validitySeconds)
+                throw new StateConflictError('A route publication has an unknown result. Retry the original publication or resolve it first.');
+            return signed;
+        }
+        const publicKey = signer.publicKey.slice();
+        if (signer.accountId !== this.accountId || !matchesAccount(this.accountId, publicKey)) throw new ProtocolError('invalid_identity', 'Account signer identity changed.');
+        let request: AccountRoute = { account: this.accountId, accountPublicKey: publicKey, relayId, revision: nextRevision(knownRevision, revision),
+            updatedAt: now, expiresAt: now + options.validitySeconds, accountSignature: new Uint8Array(64) };
+        requireSafeInteger(request.expiresAt, 0);
+        request = { ...request, accountSignature: (await signer.sign(routeAccountInput(request, this.context), signal)).slice() };
+        validateRoute(request, this.context, this.clock.nowSeconds());
+        const prepared: SignedRequest = { relayId, revision: request.revision, document: accountRouteCodec.encode(request), pending: true };
+        await updateStore(this.#store, queries, current => {
+            if (fingerprint(current.sets[0]![0]?.value) !== fingerprint(previous) || fingerprint(current.sets[1]![0]?.value) !== fingerprint(saved))
+                throw new StateConflictError('The route changed while it was being signed. Resolve current state before retrying.');
+            return { mutations: [putSignedRequest(method, prepared)], result: undefined };
+        }, signal);
+        return prepared;
+    }
+    async #verifyRelay(route: AccountRoute, signal: AbortSignal): Promise<void> {
+        validateRoute(route, this.context, this.clock.nowSeconds());
+        const client = await this.#pool.get(route.relayId, undefined, signal);
+        const descriptor = await client.getDescriptor(signal);
+        if (!route.relaySignature || !verifyRelay(route.relayId, descriptor.publicKey, routeRelayInput(route, this.context), route.relaySignature))
+            throw new ProtocolError('invalid_signature', 'Account route lacks a valid signature from its home relay.');
+    }
+    async #save(route: AccountRoute, signal: AbortSignal): Promise<void> {
+        await updateStore(this.#store, [routeKey(route.account), requestKey(method)], snapshot => {
+            const current = snapshot.sets[0]![0]?.value;
+            if (current) {
+                const comparison = compareRoutes(route, accountRouteCodec.decode(current));
+                if (comparison === 'older' || comparison === 'conflict') throw new ProtocolError('stale_route', 'Returned route is older or conflicts at the same revision.');
+            }
+            const mutations: StoreMutation[] = [{ kind: 'put', ...routeKey(route.account), value: accountRouteCodec.encode(route) }];
+            const signed = readSignedRequest(snapshot.sets[1]![0]?.value);
+            if (signed?.pending) {
+                const request = accountRouteCodec.decode(signed.document);
+                if (request.account === route.account && ['equivalent', 'newer'].includes(compareRoutes(route, request)))
+                    mutations.push(putSignedRequest(method, { ...signed, pending: false }));
+            }
+            return { mutations, result: undefined };
+        }, signal);
+    }
+    protected override async onDispose(): Promise<void> { this.#events.clear(); }
+}