@maudecode/talaria-web 1.18.0 → 1.20.0

package/dist/sessions/relay.js

@@ -1,3 +1,4 @@
+import { filterAsync } from '../util.js';
 /**
  * Talaria Relay: publisher pairing, profile enrollment, browser presence
  * leases, and the best-effort snapshot publisher (Python
@@ -8,9 +9,9 @@
  */
 import { readCapped } from '../http/capped.js';
 import { createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign as cryptoSign } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { atomicWriteText } from '../fs/atomic.js';
+import { readFileSync, statSync } from 'node:fs';
+import { z } from 'zod';
+import { updateDocument } from './storage/document.js';
 import { str } from '../util.js';
 export const PRESENCE_LEASE_SECONDS = 90;
 export const PRESENCE_MAX_LEASES = 256;
@@ -55,13 +56,12 @@ export function validatedOrigin(raw, httpsOnly = false) {
     }
     return value;
 }
-export function relayStatePath(stateDir) { return join(stateDir, 'talaria-relay.json'); }
 /** Python `RelayConfig.from_state`: null when absent or a v1 file (registration is required again); throws on corruption. */
-export function loadRelayConfig(stateDir) {
-    const path = relayStatePath(stateDir);
-    if (!existsSync(path))
+export async function loadRelayConfig(documents) {
+    const record = await documents.get('relay', 'config');
+    if (!record)
         return null;
-    const values = JSON.parse(readFileSync(path, 'utf8'));
+    const values = record.value;
     if (!values || typeof values !== 'object' || Array.isArray(values))
         throw new Error('saved relay configuration is not an object');
     const v = values;
@@ -77,32 +77,54 @@ export function loadRelayConfig(stateDir) {
             throw new Error('saved relay profiles are invalid');
         normalized[name] = { identity: p.identity, profile_id: p.profile_id };
     }
-    return { url: validatedOrigin(str(v.url)), publisher_id: validatedOrigin(str(v.publisher_id)), key_id: str(v.key_id), private_key_path: str(v.private_key_path), profiles: normalized };
+    return { url: validatedOrigin(str(v.url)), publisher_id: validatedOrigin(str(v.publisher_id)), key_id: str(v.key_id), private_key_path: str(v.private_key_path), ...(typeof v.private_key_document === 'string' ? { private_key_document: v.private_key_document } : {}), profiles: normalized };
 }
-export function saveRelayConfig(stateDir, config) {
+export async function saveRelayConfig(documents, config) {
     const payload = { key_id: config.key_id, private_key_path: config.private_key_path, profiles: sortedProfiles(config.profiles), publisher_id: config.publisher_id, url: config.url, version: 2 };
-    mkdirSync(stateDir, { recursive: true });
-    atomicWriteText(relayStatePath(stateDir), JSON.stringify(payload, null, 2) + '\n');
+    const value = { ...payload, ...(config.private_key_document ? { private_key_document: config.private_key_document } : {}) };
+    await updateDocument(documents, 'relay', 'config', () => ({ value, result: undefined }), { replaceInvalid: true });
 }
 function sortedProfiles(profiles) {
     return Object.fromEntries(Object.keys(profiles).sort().map((k) => [k, { identity: profiles[k].identity, profile_id: profiles[k].profile_id }]));
 }
-/** Python `_profile_identity`: a persistent `pfi_<32 hex>` per profile home, minted on first use (0600). */
-export function profileIdentity(profileHome) {
-    const path = join(profileHome, '.talaria-relay-profile-id');
-    let identity;
-    if (existsSync(path))
-        identity = readFileSync(path, 'utf8').trim();
-    else {
-        identity = `pfi_${randomUUID().replace(/-/g, '')}`;
-        atomicWriteText(path, identity + '\n', { mode: 0o600 });
-    }
-    if (!/^pfi_[0-9a-f]{32}$/.test(identity))
-        throw new Error('invalid Talaria Relay profile identity');
-    return identity;
+// The started ledger records announcements; deletions need a separate, non-expiring delivery outbox.
+const DeletedViewSchema = z.object({
+    id: z.string().min(1), sessionId: z.string().min(1), profile: z.string().min(1),
+    through: z.number().int().nonnegative(), identity: z.string().nullable(),
+    scope: z.object({ url: z.string(), publisherId: z.string(), profileId: z.string() }).nullable(),
+});
+const DeletedViewsSchema = z.object({ version: z.literal(1), views: z.array(DeletedViewSchema) });
+// A staged deletion cannot clear a session that survived a failed removal or a restart before removal.
+async function hasSessionData(store, sid) {
+    if (store.sessions.has(sid))
+        return true;
+    return (await store.exists(sid));
 }
-function loadKey(path) {
-    const key = createPrivateKey(readFileSync(path));
+function parseDeletedViews(raw) { return raw === undefined ? [] : DeletedViewsSchema.parse(raw).views; }
+async function loadDeletedViews(documents) { return parseDeletedViews((await documents.get('relay', 'deleted'))?.value); }
+async function mutateDeletedViews(documents, edit) {
+    return (await updateDocument(documents, 'relay', 'deleted', async (raw) => {
+        const views = parseDeletedViews(raw);
+        const result = await edit(views);
+        return { value: { version: 1, views }, result };
+    }));
+}
+/** The profile identity lives in the selected backend, with the JSON adapter retaining its old private file. */
+export async function profileIdentity(deps, profile) {
+    if (!statSync(deps.profileHome(profile)).isDirectory())
+        throw new Error('Hermes profile is unavailable');
+    return (await updateDocument(deps.documents, 'relay-identities', profile, (raw) => {
+        const identity = typeof raw === 'string' ? raw.trim() : `pfi_${randomUUID().replace(/-/g, '')}`;
+        if (!/^pfi_[0-9a-f]{32}$/.test(identity))
+            throw new Error('invalid Talaria Relay profile identity');
+        return { value: typeof raw === 'string' ? raw : identity + '\n', result: identity };
+    }));
+}
+async function loadKey(documents, config) {
+    const value = config.private_key_document ? (await documents.get('relay-keys', config.private_key_document))?.value : readFileSync(config.private_key_path, 'utf8');
+    if (typeof value !== 'string')
+        throw new Error('Talaria publisher key is missing');
+    const key = createPrivateKey(value);
     if (key.asymmetricKeyType !== 'ed25519')
         throw new Error('Talaria publisher key must be an Ed25519 private key');
     return key;
@@ -172,8 +194,6 @@ export class RelayPublisher {
     config;
     deps;
     key;
-    revisionPath;
-    startedPath;
     startedUnsupportedLogged = false;
     lastRevision = 0;
     terminal = new Map();
@@ -190,18 +210,15 @@ export class RelayPublisher {
     constructor(config, deps) {
         this.config = config;
         this.deps = deps;
-        this.key = loadKey(config.private_key_path);
-        this.revisionPath = join(dirname(config.private_key_path), 'talaria-relay-revision');
-        this.startedPath = join(dirname(config.private_key_path), 'talaria-relay-started.json');
-        // Tracking starts now, before any session event can wake the first pass, so the chat that wakes it is announced.
+    }
+    async initialize() {
+        this.key = await loadKey(this.deps.documents, this.config);
         try {
-            const ledger = this.loadStarted();
-            if (this.trackProfiles(ledger))
-                this.saveStarted(ledger);
+            await this.mutateStarted((ledger) => { this.trackProfiles(ledger); });
         }
-        catch { /* the first pass starts tracking instead */ }
+        catch { /* the first pass retries */ }
         try {
-            this.lastRevision = Number.parseInt(readFileSync(this.revisionPath, 'utf8'), 10) || 0;
+            this.lastRevision = Number.parseInt(str((await this.deps.documents.get('relay', 'revision'))?.value), 10) || 0;
         }
         catch {
             this.lastRevision = 0;
@@ -215,11 +232,11 @@ export class RelayPublisher {
             this.views.set(sid, view);
         this.lastRevision = Math.max(this.lastRevision, previous.lastRevision);
     }
-    start(publishInitial = true) {
+    async start(publishInitial = true) {
         if (this.loop)
             return;
         this.loop = this.run();
-        if (publishInitial)
+        if (publishInitial || (await loadDeletedViews(this.deps.documents)).length)
             this.changed();
     }
     stop() {
@@ -247,15 +264,37 @@ export class RelayPublisher {
         this.views.set(sid, { profile, through: Math.floor(this.deps.now() * 1000) });
         this.changed();
     }
+    /** Bind an unconfigured deletion once, before sending, so retries cannot cross relay or profile identities. */
+    async pendingDeleted() {
+        const views = await mutateDeletedViews(this.deps.documents, async (views) => {
+            for (const view of views) {
+                if (view.scope)
+                    continue;
+                const cfg = this.config.profiles[view.profile];
+                if (!cfg || (view.identity !== null && cfg.identity !== view.identity) || !await this.publishes(view.profile, cfg))
+                    continue;
+                view.identity = cfg.identity;
+                view.scope = { url: this.config.url, publisherId: this.config.publisher_id, profileId: cfg.profile_id };
+            }
+            return views;
+        });
+        return filterAsync(views, async (view) => !await hasSessionData(this.deps.store, view.sessionId));
+    }
     /** Send the views queued before the snapshot just published, so the relay already holds every outcome they saw. */
     async flushViews(ready) {
         for (const [sid, view] of ready) {
+            if (view.deleted && (await hasSessionData(this.deps.store, sid)))
+                continue;
+            let accepted = false;
             for (const [profile, cfg] of Object.entries(this.config.profiles)) {
-                if (!this.deps.profilesMatch(view.profile, profile) || !this.publishes(profile, cfg))
+                if (!this.deps.profilesMatch(view.profile, profile) || !(await this.publishes(profile, cfg)))
+                    continue;
+                if (view.deleted && (view.deleted.identity !== cfg.identity || view.deleted.scope?.url !== this.config.url || view.deleted.scope.publisherId !== this.config.publisher_id || view.deleted.scope.profileId !== cfg.profile_id))
                     continue;
                 const path = `/v1/publishers/${encodeURIComponent(this.config.publisher_id)}/profiles/${encodeURIComponent(cfg.profile_id)}/sessions/${encodeURIComponent(sid)}/viewed`;
                 try {
                     await this.put(path, JSON.stringify({ through: view.through }));
+                    accepted = true;
                 }
                 catch (error) {
                     if (!(error instanceof RelayHttpError) || error.retryable)
@@ -268,7 +307,12 @@ export class RelayPublisher {
                         this.deps.log(`[relay] Talaria relay rejected a viewed acknowledgement (HTTP ${String(error.status)})`);
                 }
             }
-            if (this.views.get(sid) === view)
+            if (view.deleted) {
+                if (accepted)
+                    await mutateDeletedViews(this.deps.documents, (views) => { const index = views.findIndex((entry) => entry.id === view.deleted.id && entry.through === view.through); if (index >= 0)
+                        views.splice(index, 1); });
+            }
+            else if (this.views.get(sid) === view)
                 this.views.delete(sid);
         }
     }
@@ -292,7 +336,7 @@ export class RelayPublisher {
                 return;
             this.dirty = false;
             try {
-                const ready = new Map(this.views);
+                const ready = [...this.views, ...(await this.pendingDeleted()).map((view) => [view.sessionId, { profile: view.profile, through: view.through, deleted: view }])];
                 await this.publishSnapshot(true);
                 await this.flushViews(ready);
                 await this.publishStarted();
@@ -315,7 +359,7 @@ export class RelayPublisher {
         }
     }
     /** Python `build_states`: one row per session with a live or recently terminal run in this profile. */
-    buildStates(profile) {
+    async buildStates(profile) {
         const cutoff = this.deps.now() - TERMINAL_RETENTION_S;
         for (const [sid, run] of this.terminal)
             if (run.terminal_at < cutoff)
@@ -339,7 +383,7 @@ export class RelayPublisher {
         for (const [sid, run] of bySession) {
             let session;
             try {
-                session = this.deps.store.get(sid, { metadataOnly: true });
+                session = (await this.deps.store.get(sid, { metadataOnly: true }));
             }
             catch {
                 continue;
@@ -362,13 +406,22 @@ export class RelayPublisher {
             states.push(state);
         }
         if (states.length)
-            atomicWriteText(this.revisionPath, `${String(this.lastRevision)}\n`);
+            await updateDocument(this.deps.documents, 'relay', 'revision', (raw) => {
+                let floor = Number.parseInt(str(raw), 10) || 0;
+                for (const state of states) {
+                    state.revision = Math.max(state.revision, floor + 1);
+                    state.eventId = `snapshot:${String(state.revision)}:${state.sessionId}`;
+                    floor = state.revision;
+                }
+                this.lastRevision = Math.max(this.lastRevision, floor);
+                return { value: `${String(this.lastRevision)}\n`, result: undefined };
+            });
         return states;
     }
     async publishSnapshot(isolatePermanent = false) {
         let retryable = null;
         for (const [profile, cfg] of Object.entries(this.config.profiles)) {
-            if (!this.publishes(profile, cfg))
+            if (!(await this.publishes(profile, cfg)))
                 continue;
             try {
                 await this.publishProfileSnapshot(profile, cfg.profile_id);
@@ -387,10 +440,10 @@ export class RelayPublisher {
         if (retryable)
             throw retryable;
     }
-    publishes(profile, cfg) {
+    async publishes(profile, cfg) {
         if (cfg.identity) {
             try {
-                if (profileIdentity(this.deps.profileHome(profile)) !== cfg.identity)
+                if ((await profileIdentity(this.deps, profile)) !== cfg.identity)
                     return false;
             }
             catch {
@@ -404,7 +457,7 @@ export class RelayPublisher {
         for (const [profile, cfg] of Object.entries(this.config.profiles)) {
             if (cfg.profile_id !== profileId)
                 continue;
-            if (cfg.identity !== expectedIdentity || profileIdentity(this.deps.profileHome(profile)) !== expectedIdentity)
+            if (cfg.identity !== expectedIdentity || (await profileIdentity(this.deps, profile)) !== expectedIdentity)
                 throw new RelayPairingError('Hermes profile changed during relay enrollment', 409);
             await this.publishProfileSnapshot(profile, profileId);
             return;
@@ -412,15 +465,8 @@ export class RelayPublisher {
         throw new RelayPairingError('Talaria Relay profile enrollment is unavailable', 502);
     }
     // The ledger is reread for every change, so a restarted or replacement publisher resends an unsent event under its ID.
-    loadStarted() {
+    parseStarted(raw) {
         const ledger = new Map();
-        let raw;
-        try {
-            raw = JSON.parse(readFileSync(this.startedPath, 'utf8'));
-        }
-        catch {
-            return ledger;
-        }
         const profiles = raw?.profiles;
         if (!Array.isArray(profiles))
             return ledger;
@@ -436,9 +482,16 @@ export class RelayPublisher {
         }
         return ledger;
     }
-    saveStarted(ledger) {
+    startedDocument(ledger) {
         const profiles = [...ledger].map(([profileId, p]) => ({ profileId, floor: p.floor, sessions: [...p.sessions].map(([sessionId, e]) => ({ sessionId, startedAt: e.startedAt, sent: e.sent })) }));
-        atomicWriteText(this.startedPath, JSON.stringify({ version: 1, profiles }) + '\n');
+        return { version: 1, profiles };
+    }
+    async mutateStarted(edit) {
+        return (await updateDocument(this.deps.documents, 'relay', 'started', async (raw) => {
+            const ledger = this.parseStarted(raw);
+            const result = await edit(ledger);
+            return { value: this.startedDocument(ledger), result };
+        }, { replaceInvalid: true }));
     }
     /** Give each enrolled profile without a ledger entry a floor of now; true when the ledger changed. */
     trackProfiles(ledger) {
@@ -457,7 +510,7 @@ export class RelayPublisher {
         // Agent rows come from the listing worker first, so the ledger's load-to-save stays synchronous.
         const agentRows = new Map();
         for (const [profile, cfg] of Object.entries(this.config.profiles)) {
-            if (!this.publishes(profile, cfg))
+            if (!(await this.publishes(profile, cfg)))
                 continue;
             try {
                 agentRows.set(profile, await this.deps.agentSessions(profile));
@@ -466,50 +519,49 @@ export class RelayPublisher {
                 agentRows.set(profile, []);
             }
         }
-        const ledger = this.loadStarted();
-        const nowMs = Math.floor(this.deps.now() * 1000);
-        let changed = this.trackProfiles(ledger);
         let index = [];
         try {
-            index = this.deps.store.readIndexEntries();
-        }
-        catch {
-            index = [];
-        }
-        for (const [profile, cfg] of Object.entries(this.config.profiles)) {
-            if (!this.publishes(profile, cfg))
-                continue;
-            const entry = ledger.get(cfg.profile_id);
-            const floor = Math.max(entry.floor, nowMs - STARTED_WINDOW_MS);
-            for (const [sid, e] of entry.sessions)
-                if (e.startedAt < floor) {
-                    entry.sessions.delete(sid);
-                    changed = true;
-                }
-            // A compressed Agent chat keeps its lineage root's id and start, so later segments are not new sessions.
-            const agent = agentRows.get(profile) ?? [];
-            const seen = [
-                ...index.filter((row) => Number(row.message_count) > 0 && this.deps.profilesMatch(row.profile, profile)).map((row) => [row.session_id, row.created_at]),
-                ...agent.map((row) => [row._lineage_root_id || row.id, row.started_at]),
-            ];
-            for (const [rawSid, created] of seen) {
-                const sid = str(rawSid).trim();
-                const startedAt = Math.floor(Number(created) * 1000);
-                if (!sid || sid.length > 191 || !Number.isSafeInteger(startedAt) || startedAt < floor || entry.sessions.has(sid))
+            index = await this.deps.store.readIndexEntries();
+        }
+        catch { /* no resident index */ }
+        const eligible = new Set();
+        for (const [profile, cfg] of Object.entries(this.config.profiles))
+            if (await this.publishes(profile, cfg))
+                eligible.add(profile);
+        return (await this.mutateStarted((ledger) => {
+            const nowMs = Math.floor(this.deps.now() * 1000);
+            this.trackProfiles(ledger);
+            for (const [profile, cfg] of Object.entries(this.config.profiles)) {
+                if (!eligible.has(profile))
                     continue;
-                entry.sessions.set(sid, { startedAt, sent: false });
-                changed = true;
+                const entry = ledger.get(cfg.profile_id);
+                const floor = Math.max(entry.floor, nowMs - STARTED_WINDOW_MS);
+                for (const [sid, e] of entry.sessions)
+                    if (e.startedAt < floor) {
+                        entry.sessions.delete(sid);
+                    }
+                // A compressed Agent chat keeps its lineage root's id and start, so later segments are not new sessions.
+                const agent = agentRows.get(profile) ?? [];
+                const seen = [
+                    ...index.filter((row) => Number(row.message_count) > 0 && this.deps.profilesMatch(row.profile, profile)).map((row) => [row.session_id, row.created_at]),
+                    ...agent.map((row) => [row._lineage_root_id || row.id, row.started_at]),
+                ];
+                for (const [rawSid, created] of seen) {
+                    const sid = str(rawSid).trim();
+                    const startedAt = Math.floor(Number(created) * 1000);
+                    if (!sid || sid.length > 191 || !Number.isSafeInteger(startedAt) || startedAt < floor || entry.sessions.has(sid))
+                        continue;
+                    entry.sessions.set(sid, { startedAt, sent: false });
+                }
             }
-        }
-        if (changed)
-            this.saveStarted(ledger);
-        return ledger;
+            return ledger;
+        }));
     }
     /** Announce each newly observed session once, oldest first, to the relay scope of the profile that owns it. */
     async publishStarted() {
         const ledger = await this.observeStarted();
         for (const [profile, cfg] of Object.entries(this.config.profiles)) {
-            if (!this.publishes(profile, cfg))
+            if (!(await this.publishes(profile, cfg)))
                 continue;
             const unsent = [...(ledger.get(cfg.profile_id)?.sessions ?? [])].filter(([, e]) => !e.sent).sort((a, b) => a[1].startedAt - b[1].startedAt);
             for (const [sid, e] of unsent) {
@@ -528,17 +580,13 @@ export class RelayPublisher {
                         this.deps.log('[relay] Talaria relay does not support session-started events (HTTP 404); devices refresh on their own schedule');
                     }
                 }
-                const latest = this.loadStarted();
-                const sent = latest.get(cfg.profile_id)?.sessions.get(sid);
-                if (sent && !sent.sent) {
-                    sent.sent = true;
-                    this.saveStarted(latest);
-                }
+                await this.mutateStarted((latest) => { const sent = latest.get(cfg.profile_id)?.sessions.get(sid); if (sent)
+                    sent.sent = true; });
             }
         }
     }
     async publishProfileSnapshot(profile, profileId) {
-        const states = this.buildStates(profile);
+        const states = (await this.buildStates(profile));
         try {
             await this.putSnapshot(profileId, states);
         }
@@ -584,18 +632,19 @@ export class RelayService {
     }
     current() { return this.publisher; }
     /** Python `start_talaria_relay_publisher`: resume from saved state; invalid state disables the publisher. */
-    start() {
+    async start() {
         if (this.publisher)
             return true;
         let candidate = null;
         try {
-            const config = loadRelayConfig(this.deps.stateDir);
+            const config = (await loadRelayConfig(this.deps.documents));
             if (!config)
                 return false;
             candidate = new RelayPublisher(config, this.deps);
+            await candidate.initialize();
             this.candidate = candidate;
             this.adopt(candidate, null);
-            candidate.start(false);
+            await candidate.start(false);
             return true;
         }
         catch (error) {
@@ -625,21 +674,50 @@ export class RelayService {
         }
     }
     /** A viewed session clears its finished runs on the relay; without a publisher there is nothing to clear. */
-    markViewed(sid) {
+    async markViewed(sid) {
         const publisher = this.publisher ?? this.candidate;
-        publisher?.markViewed(sid, this.deps.store.get(sid, { metadataOnly: true }).profile);
+        publisher?.markViewed(sid, (await this.deps.store.get(sid, { metadataOnly: true })).profile);
     }
-    /**
-     * A deleted session can never be viewed, so its finished runs are cleared once, under the profile it had (the
-     * store no longer knows it). Later lookups of the same id do not resend.
-     */
-    clearDeleted(sid, profile) {
+    /** Persist before reporting successful deletion, even when publication is unavailable. */
+    async clearDeleted(sid, profile) {
         const publisher = this.publisher ?? this.candidate;
-        if (!publisher || this.clearedDeleted.has(sid))
+        const name = this.deps.canonicalProfile(profile ?? 'default');
+        const key = JSON.stringify([name, sid]);
+        const live = (await hasSessionData(this.deps.store, sid));
+        if (!live && this.clearedDeleted.has(key))
             return;
-        // ponytail: grows by one id per deleted session per process; reset on restart is fine because the relay ack is idempotent.
-        this.clearedDeleted.add(sid);
-        publisher.markViewed(sid, profile);
+        await mutateDeletedViews(this.deps.documents, async (views) => {
+            const queued = views.find((view) => view.sessionId === sid && view.profile === name);
+            if (queued && live) {
+                const through = Math.max(queued.through, Math.floor(this.deps.now() * 1000));
+                if (through !== queued.through) {
+                    queued.through = through;
+                }
+            }
+            else if (!queued) {
+                let config = publisher?.config ?? null;
+                if (!config) {
+                    try {
+                        config = (await loadRelayConfig(this.deps.documents));
+                    }
+                    catch { /* preserve unconfigured cleanup */ }
+                }
+                const cfg = config?.profiles[name];
+                let identity = cfg?.identity ?? null;
+                if (identity === null) {
+                    try {
+                        identity = (await profileIdentity(this.deps, name));
+                    }
+                    catch { /* bind when this profile becomes available */ }
+                }
+                views.push({
+                    id: randomUUID(), sessionId: sid, profile: name, through: Math.floor(this.deps.now() * 1000), identity,
+                    scope: config && cfg ? { url: config.url, publisherId: config.publisher_id, profileId: cfg.profile_id } : null,
+                });
+            }
+        });
+        this.clearedDeleted.add(key);
+        publisher?.changed();
     }
     /** Terminal turn events reach the relay even mid-swap (Python `note_talaria_terminal`). */
     noteTerminal(streamId, phase) {
@@ -654,6 +732,7 @@ export class RelayService {
     /** Python `configure_talaria_relay_publisher`: validate with a real snapshot before swapping publishers. */
     async configure(config, validate) {
         const candidate = new RelayPublisher(config, this.deps);
+        await candidate.initialize();
         const previous = this.publisher;
         this.candidate = candidate;
         if (previous)
@@ -670,7 +749,7 @@ export class RelayService {
             throw new RelayPairingError(error instanceof RelayPairingError ? error.message : 'Could not publish the initial Talaria Relay snapshot', error instanceof RelayPairingError ? error.status : 502);
         }
         this.adopt(candidate, previous);
-        candidate.start(false);
+        await candidate.start(false);
         candidate.changed();
     }
     /** Python `pair_talaria_relay`, serialised so concurrent enrollments preserve both mappings. */
@@ -730,12 +809,12 @@ export class RelayService {
         let identity;
         try {
             canonical = this.deps.canonicalProfile(profile);
-            identity = profileIdentity(this.deps.profileHome(canonical));
+            identity = (await profileIdentity(this.deps, canonical));
         }
         catch {
             throw new RelayPairingError('Hermes profile is unavailable', 403);
         }
-        const existing = loadRelayConfig(this.deps.stateDir);
+        const existing = (await loadRelayConfig(this.deps.documents));
         if (existing) {
             if (existing.url !== relayUrl || existing.publisher_id !== publisherId)
                 throw new RelayPairingError('This Hermes server is registered to a different relay', 409);
@@ -743,11 +822,11 @@ export class RelayService {
             const profileId = known?.identity === identity ? known.profile_id : `prf_${randomUUID().replace(/-/g, '')}`;
             const requestBody = JSON.stringify({ invitation, publisherId, profileId });
             const path = '/v1/pairings/profile/redeem';
-            const payload = await this.relayPost(existing.url + path, requestBody, signedHeaders(loadKey(existing.private_key_path), existing.key_id, 'POST', path, requestBody, this.deps.now), 'Talaria Relay rejected the profile enrollment');
+            const payload = await this.relayPost(existing.url + path, requestBody, signedHeaders((await loadKey(this.deps.documents, existing)), existing.key_id, 'POST', path, requestBody, this.deps.now), 'Talaria Relay rejected the profile enrollment');
             if (payload.protocolVersion !== 2 || payload.publisherId !== publisherId || payload.profileId !== profileId)
                 throw new RelayPairingError('Talaria Relay returned an invalid response', 502);
             const config = { ...existing, profiles: { ...existing.profiles, [canonical]: { identity, profile_id: profileId } } };
-            saveRelayConfig(this.deps.stateDir, config);
+            await saveRelayConfig(this.deps.documents, config);
             await this.configure(config, { profileId, identity });
             return { ok: true, publisher_id: publisherId };
         }
@@ -771,11 +850,10 @@ export class RelayService {
         catch {
             throw new RelayPairingError('Talaria Relay returned an invalid response', 502);
         }
-        const keyPath = join(this.deps.stateDir, `talaria-relay-publisher-${createHash('sha256').update(keyId, 'utf8').digest('hex').slice(0, 16)}.pem`);
-        mkdirSync(this.deps.stateDir, { recursive: true });
-        atomicWriteText(keyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), { mode: 0o600 });
-        const config = { url: relayUrl, publisher_id: finalPublisher, key_id: keyId, private_key_path: keyPath, profiles: { [canonical]: { identity, profile_id: pairedProfile } } };
-        saveRelayConfig(this.deps.stateDir, config);
+        const keyDocument = createHash('sha256').update(keyId, 'utf8').digest('hex').slice(0, 16);
+        await updateDocument(this.deps.documents, 'relay-keys', keyDocument, () => ({ value: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), result: undefined }));
+        const config = { url: relayUrl, publisher_id: finalPublisher, key_id: keyId, private_key_path: '', private_key_document: keyDocument, profiles: { [canonical]: { identity, profile_id: pairedProfile } } };
+        await saveRelayConfig(this.deps.documents, config);
         await this.configure(config, { profileId: pairedProfile, identity });
         return { ok: true, publisher_id: finalPublisher };
     }