@plane31/blind-relay 0.2.0 → 0.4.0

package/src/client.ts

@@ -167,6 +167,22 @@ export interface Client {
   completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }>;
   /** The key changes this device accepted for its contacts, newest first, bounded. */
   keyChanges(options?: { accountId?: Uint8Array; limit?: number }): Promise<KeyChangeEntry[]>;
+  /**
+   * Account recovery as one call over `prepareReplacement` and `completeReplacement`, with the
+   * protocol's retry rules: an earlier proposal is settled through the chain first; the same
+   * proposal is kept through an unknown outcome and a refused authorization; a new proposal is
+   * made only after a definitive conflict, and then only by the next call. The product supplies
+   * `authorize`, which obtains the host's token for a proposal after its own fresh sign-in, or
+   * answers `"reauthenticate"` when it cannot. Attempts are bounded; `pending` means call again.
+   */
+  replaceDevice(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult>;
+  /**
+   * Synchronise in rounds until nothing is left that this device can do now: the relay has no
+   * more records within the budget, bootstrap is complete, or progress needs someone else (an
+   * authorization, another person, metadata the host does not serve). Bounded by rounds and by
+   * time; the result says why it stopped and what remains.
+   */
+  syncUntilDrained(options?: DrainOptions): Promise<DrainReport>;
   /** A durable outbound record of a declared kind; the payload is the product's bytes, never read by the SDK. */
   enqueue(kind: RecordKind, payload: Uint8Array, options?: EnqueueOptions): Promise<EnqueueResult>;
   /** One synchronisation; `options.catchUp` bounds how much of a backlog this call reads (`SyncReport.inbox.hasMore` says when to call again). */
@@ -192,9 +208,75 @@ export interface Client {
     list(): Promise<readonly CircleSummary[]>;
   };
   resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }>;
+  /**
+   * Stop: no new operation is accepted (`CLOSED`), the operations in flight finish their current
+   * transaction and a running sync stops at its next phase boundary, then listeners are cleared
+   * so nothing is emitted afterwards. Closes nothing it did not open: the store and the secret
+   * store are the caller's. Idempotent.
+   */
   close(): Promise<void>;
 }
 
+export interface ReplaceDeviceOptions {
+  /** Obtain the host's authorization for this proposal after the product's fresh sign-in, or say that a sign-in is needed first. */
+  readonly authorize: (proposal: ReplacementProposal) => Promise<Uint8Array | "reauthenticate">;
+  /** Commit attempts per call, over unknown outcomes and refused authorizations. Default 3. */
+  readonly maxAttempts?: number;
+}
+
+export type ReplaceDeviceResult =
+  | { readonly status: "activated"; readonly identityId: Uint8Array; readonly generation: bigint }
+  /** The outcome is still unknown or the attempts are spent: the proposal is kept; call again. */
+  | { readonly status: "pending"; readonly proposal: ReplacementProposal }
+  /** The account moved under the proposal, which is discarded; the next call prepares a new one after a fresh sign-in. */
+  | { readonly status: "conflict"; readonly currentGeneration: bigint | undefined }
+  /** The product's `authorize` asked for a fresh sign-in; the proposal is kept for the next call. */
+  | { readonly status: "reauthenticate"; readonly proposal: ReplacementProposal };
+
+export interface DrainOptions {
+  readonly catchUp?: SyncOptions["catchUp"];
+  readonly skipMaintenance?: boolean;
+  /** Rounds at most. Default 10. */
+  readonly maxRounds?: number;
+  /** A soft bound in milliseconds across every round: no round starts past it and each round's reading budget is the time left, but a transport call already in flight ends on its own timeout. Default 30,000. */
+  readonly maxMs?: number;
+}
+
+export type DrainStop =
+  /** Nothing is left that this device can do now. */
+  | "drained"
+  | "maxRounds"
+  | "maxMs"
+  /** A round changed nothing and reported the same errors as the one before. */
+  | "noProgress"
+  /** Progress needs metadata the host does not serve yet (a chain, a certificate, the key list). */
+  | "metadata"
+  /** Progress needs an authorization or a sign-in (a prepared replacement, an account to recover). */
+  | "authentication"
+  /** Nothing more is reported, but a round could not read its inbox fully (discovery or a stream failed), so emptiness is not established. */
+  | "incomplete"
+  /** The host asked for a pause; `remaining.retryAfterMs` says how long, and the product schedules the next attempt. */
+  | "rateLimited"
+  | "closed";
+
+/** The merged report of every round, with why the loop stopped and what remains. */
+export interface DrainReport extends SyncReport {
+  readonly rounds: number;
+  readonly stoppedBecause: DrainStop;
+  readonly remaining: {
+    /** The relay still holds records this device has not read; `"unknown"` when the last round could not read its inbox fully. */
+    readonly inboxHasMore: boolean | "unknown";
+    /** Bootstrap after account recovery has circles left to adopt. */
+    readonly bootstrapIncomplete: boolean;
+    /** Contacts whose succession chain this device has verified only partly; the next rounds continue them. */
+    readonly chainsIncomplete: number;
+    /** Authors whose current epoch has not reached this device: nothing to do but wait for them. */
+    readonly waitingFor: number;
+    /** On `rateLimited`: the longest wait the host asked for in the last round, when it said one. */
+    readonly retryAfterMs?: number;
+  };
+}
+
 export interface SyncOptions {
   /**
    * The inbox budget of this sync, shared by every stream: at most this many records
@@ -203,6 +285,12 @@ export interface SyncOptions {
    * at least one page.
    */
   readonly catchUp?: { readonly maxRecords?: number; readonly maxMs?: number };
+  /**
+   * Leave the housekeeping to a later sync: the retention purge, the periodic re-check of the
+   * reset-key list (a stale list is still fetched, since verification needs it) and the
+   * recovery-key re-save. For a short background window; the report says `maintenance: "skipped"`.
+   */
+  readonly skipMaintenance?: boolean;
 }
 
 export const DEFAULT_CATCH_UP = { maxRecords: 500, maxMs: 5_000 } as const;
@@ -214,11 +302,39 @@ export interface SyncReport {
   /** `hasMore`: a stream still has records on the relay that this sync's budget did not reach; sync again soon. */
   inbox: { streams: number; stored: number; keyPending: number; invalid: number; acked: number; hasMore: boolean };
   purged: number;
+  /** Whether this sync did its housekeeping (purge, list re-check, key re-save) or left it to a later one. */
+  maintenance: "done" | "skipped";
   /** Present while account recovery discovers circles through the host: pinned, pending and failed on this sync. */
   bootstrap?: { circles: number; pending: number; failed: number };
+  /** Wall-clock milliseconds per phase and record bytes moved, for diagnostics (section 14: counts and durations only). */
+  timings: SyncTimings;
   errors: SyncError[];
 }
 
+export interface SyncTimings {
+  resume: number;
+  bootstrap: number;
+  metadata: number;
+  preferences: number;
+  epoch: number;
+  outbox: number;
+  inbox: number;
+  maintenance: number;
+  total: number;
+  /** Record bytes handed to the relay. */
+  bytesSent: number;
+  /** Record bytes read from the relay. */
+  bytesReceived: number;
+}
+
+const emptyTimings = (): SyncTimings => ({ resume: 0, bootstrap: 0, metadata: 0, preferences: 0, epoch: 0, outbox: 0, inbox: 0, maintenance: 0, total: 0, bytesSent: 0, bytesReceived: 0 });
+
+/** A monotonic wall clock for durations; the protocol clock (`now`) is not used, since a test drives it by hand. */
+const wall = (): number => {
+  const g = globalThis as { performance?: { now?: () => number } };
+  return typeof g.performance?.now === "function" ? g.performance.now() : Date.now();
+};
+
 /** What `prepareReplacement()` returns: everything the product hands to the host for authorization. All public. */
 export interface ReplacementProposal {
   readonly successionId: Uint8Array;
@@ -256,10 +372,14 @@ export interface SyncError {
   readonly authorIdentityId?: Uint8Array;
   /** On a `bootstrap` entry: the circle that could not be adopted on this sync; it is retried by the next. */
   readonly circleId?: Uint8Array;
+  /** On a `RATE_LIMITED` entry: the wait the host asked for, when it said. */
+  readonly retryAfterMs?: number;
 }
 
 function syncError(operation: string, e: unknown, extra: Partial<Pick<SyncError, "circleId" | "streamId" | "authorIdentityId">> = {}): SyncError {
-  return e instanceof KavachError ? { operation, code: e.code, stage: e.stage, retryable: e.retryable, ...extra } : { operation, code: "UNEXPECTED", stage: operation, retryable: false, ...extra };
+  return e instanceof KavachError
+    ? { operation, code: e.code, stage: e.stage, retryable: e.retryable, ...(e.retryAfterMs === undefined ? {} : { retryAfterMs: e.retryAfterMs }), ...extra }
+    : { operation, code: "UNEXPECTED", stage: operation, retryable: false, ...extra };
 }
 
 const RESET_LIST_RECHECK_MS = 86_400_000n;
@@ -292,6 +412,9 @@ class ClientImpl implements Client {
   private selfPin: AccountPin | undefined;
   private trust: ResetTrust;
   private syncing: Promise<SyncReport> | undefined;
+  private closed = false;
+  /** Every public operation in flight, so `close()` can wait for them. */
+  private readonly running = new Set<Promise<unknown>>();
   /** The current sync's reading budget: records, and the links of a succession chain, count against it. */
   private syncBudget: ReadBudget | undefined;
   private backupChecked = false;
@@ -309,17 +432,56 @@ class ClientImpl implements Client {
     this.now = options.now ?? ((): bigint => BigInt(Date.now()));
     this.trust = new ResetTrust(options.resetTrust);
     this.circles = {
-      create: () => this.createCircle(),
-      requestJoin: (c, o, opts) => this.requestJoin(c, o, opts?.shareOnApproval ?? true),
-      approve: (c, n) => this.approve(c, n),
-      remove: (c, m) => this.changeMembership(c, { remove: m }),
-      leave: (c) => this.leave(c),
-      setEnabled: (c, e) => this.setEnabled(c, e),
-      closeCircle: (c) => this.closeCircle(c),
+      create: () => this.track("createCircle", () => this.createCircle()),
+      requestJoin: (c, o, opts) => this.track("requestJoin", () => this.requestJoin(c, o, opts?.shareOnApproval ?? true)),
+      approve: (c, n) => this.track("approve", () => this.approve(c, n)),
+      remove: (c, m) => this.track("changeMembership", () => this.changeMembership(c, { remove: m })),
+      leave: (c) => this.track("leave", () => this.leave(c)),
+      setEnabled: (c, e) => this.track("setEnabled", () => this.setEnabled(c, e)),
+      closeCircle: (c) => this.track("closeCircle", () => this.closeCircle(c)),
       list: () => this.listCircles()
     };
   }
 
+  // Every public operation that writes enters through `track`, explicitly and typed, so `close()`
+  // refuses new ones and waits for those in flight. Reads stay untracked.
+
+  initializeAccount(): Promise<{ identityId: Uint8Array }> {
+    return this.track("initializeAccount", () => this.initializeAccountNow());
+  }
+
+  restoreAccount(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
+    return this.track("restoreAccount", () => this.restoreAccountNow(recoveryCode));
+  }
+
+  enqueue(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions = {}): Promise<EnqueueResult> {
+    return this.track("enqueue", () => this.enqueueNow(kind, payload, options));
+  }
+
+  receive(wire: Uint8Array): Promise<ReceiveResult> {
+    return this.track("receive", () => receiveRecord(this.inboxDeps(), wire));
+  }
+
+  prepareReplacement(): Promise<ReplacementProposal> {
+    return this.track("prepareReplacement", () => this.prepareReplacementNow());
+  }
+
+  completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
+    return this.track("completeReplacement", () => this.completeReplacementNow(input));
+  }
+
+  resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
+    return this.track("resetAccount", () => this.resetAccountNow(options));
+  }
+
+  replaceDevice(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult> {
+    return this.track("replaceDevice", () => this.replaceDeviceNow(options));
+  }
+
+  syncUntilDrained(options: DrainOptions = {}): Promise<DrainReport> {
+    return this.track("syncUntilDrained", () => this.drainNow(options));
+  }
+
   // Loading ---------------------------------------------------------------------------------------
 
   async load(): Promise<void> {
@@ -354,8 +516,18 @@ class ClientImpl implements Client {
     });
   }
 
-  /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. */
+  /** Refuse after `close()`, and keep the operation's promise until it settles. */
+  private track<T>(stage: string, fn: () => Promise<T>): Promise<T> {
+    if (this.closed) return Promise.reject(new KavachError("CLOSED", stage, "the client is closed"));
+    const p = fn();
+    this.running.add(p);
+    void p.finally(() => this.running.delete(p)).catch(() => undefined);
+    return p;
+  }
+
+  /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. Nothing after `close()`. */
   private emit(event: ClientEvent): void {
+    if (this.closed) return;
     for (const l of this.listeners) {
       try {
         l(event);
@@ -489,7 +661,7 @@ class ClientImpl implements Client {
 
   // Enrollment ------------------------------------------------------------------------------------
 
-  async initializeAccount(): Promise<{ identityId: Uint8Array }> {
+  private async initializeAccountNow(): Promise<{ identityId: Uint8Array }> {
     const stage = "initializeAccount";
     const opened = await openStore(this.store, this.secrets, this.accountName);
     if (opened.kind !== "fresh" && opened.kind !== "initializing") throw new KavachError("MALFORMED", stage, "an account already exists on this device");
@@ -551,7 +723,7 @@ class ClientImpl implements Client {
     return encodeRecoveryCode(key);
   }
 
-  async restoreAccount(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
+  private async restoreAccountNow(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
     const stage = "restoreAccount";
     const opened = await openStore(this.store, this.secrets, this.accountName);
     if (opened.kind === "ACTIVE" || opened.kind === "RETIRED") throw new KavachError("MALFORMED", stage, "an account already exists on this device");
@@ -720,7 +892,7 @@ class ClientImpl implements Client {
 
   // Sending ---------------------------------------------------------------------------------------
 
-  async enqueue(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions = {}): Promise<EnqueueResult> {
+  private async enqueueNow(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions): Promise<EnqueueResult> {
     const deps = this.outboxDeps();
     // A key answered before anything that may need the network: the record it names is already
     // durable, so a retry offline, or with a rotation due, returns it. The outbox checks the key
@@ -839,21 +1011,148 @@ class ClientImpl implements Client {
 
   async sync(options: SyncOptions = {}): Promise<SyncReport> {
     if (this.syncing) return this.syncing;
-    this.syncing = this.runSync(options).finally(() => {
+    if (this.closed) throw new KavachError("CLOSED", "sync", "the client is closed");
+    this.syncing = this.track("sync", () => this.runSync(options)).finally(() => {
       this.syncing = undefined;
     });
     return this.syncing;
   }
 
+  private async drainNow(options: DrainOptions): Promise<DrainReport> {
+    const maxRounds = Math.max(1, Math.floor(options.maxRounds ?? 10));
+    const maxMs = Math.max(0, Math.floor(options.maxMs ?? 30_000));
+    const deadline = this.now() + BigInt(maxMs);
+    const merged: SyncReport = {
+      metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
+      epoch: "unchanged",
+      outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 },
+      inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false },
+      purged: 0,
+      maintenance: options.skipMaintenance ? "skipped" : "done",
+      timings: emptyTimings(),
+      errors: []
+    };
+    let rounds = 0;
+    let previousErrors: string | undefined;
+    let stop: DrainStop = "drained";
+    let last: SyncReport | undefined;
+    // An inbox this device could not fully read this round: discovery or a stream failed, or metadata it
+    // depends on did. Such a round never establishes that the inbox is empty.
+    const inboxUncertain = (r: SyncReport): boolean => r.errors.some((e) => e.operation === "listSubscriptions" || e.operation === "inbox" || e.operation === "metadata");
+    // Chains verified only partly: remaining work, and their cursors moving is progress.
+    const chains = (): Promise<Map<string, string>> => this.store.read((tx) => new Map(tx.list("chainProgress").filter(([, c]) => !c.complete).map(([k, c]) => [k, c.nextGeneration])));
+    let previousChains = await chains();
+    for (;;) {
+      if (this.closed) {
+        stop = "closed";
+        break;
+      }
+      // The time left is this round's reading budget too, so a round never starts work the deadline
+      // does not cover; a transport call already in flight ends on its own timeout.
+      const remainingMs = Number(deadline - this.now());
+      if (rounds > 0 && remainingMs <= 0) {
+        stop = "maxMs";
+        break;
+      }
+      const roundMs = Math.max(0, Math.min(remainingMs, options.catchUp?.maxMs ?? DEFAULT_CATCH_UP.maxMs));
+      const r = await this.sync({ catchUp: { maxMs: roundMs, ...(options.catchUp?.maxRecords !== undefined ? { maxRecords: options.catchUp.maxRecords } : {}) }, ...(options.skipMaintenance ? { skipMaintenance: true } : {}) });
+      rounds++;
+      last = r;
+      // The round's work counts whether or not it was the last: what it accepted, stored and failed
+      // is merged first, and only then is a close that landed meanwhile reported.
+      for (const k of Object.keys(merged.metadata) as (keyof SyncReport["metadata"])[]) merged.metadata[k] += r.metadata[k];
+      for (const k of Object.keys(merged.outbox) as (keyof SyncReport["outbox"])[]) merged.outbox[k] += r.outbox[k];
+      merged.inbox.streams += r.inbox.streams;
+      merged.inbox.stored += r.inbox.stored;
+      merged.inbox.keyPending += r.inbox.keyPending;
+      merged.inbox.invalid += r.inbox.invalid;
+      merged.inbox.acked += r.inbox.acked;
+      merged.purged += r.purged;
+      for (const k of Object.keys(merged.timings) as (keyof SyncTimings)[]) merged.timings[k] += r.timings[k];
+      merged.epoch = r.epoch;
+      merged.errors.push(...r.errors);
+      if (r.bootstrap) merged.bootstrap = r.bootstrap;
+      if (this.closed) {
+        // The round may have stopped at a boundary before its inbox: nothing it reports is complete.
+        stop = "closed";
+        break;
+      }
+      if (r.errors.some((e) => e.code === "RATE_LIMITED")) {
+        // The host asked for a pause: no further round now; the wait goes back to the product.
+        stop = "rateLimited";
+        break;
+      }
+      const bootstrapIncomplete = (await this.inspect()).bootstrap?.complete === false;
+      const currentChains = await chains();
+      const more = r.inbox.hasMore || bootstrapIncomplete || currentChains.size > 0;
+      const status = (await this.getState()).status;
+      if (status === "replacementPrepared" || status === "accountRecoveryRequired") {
+        stop = "authentication";
+        break;
+      }
+      if (!more) {
+        stop = inboxUncertain(r) ? "incomplete" : "drained";
+        break;
+      }
+      const signature = r.errors.map((e) => `${e.operation}:${e.code}`).sort().join(",");
+      const chainsAdvanced = [...currentChains].some(([k, next]) => previousChains.get(k) !== next) || [...previousChains.keys()].some((k) => !currentChains.has(k));
+      previousChains = currentChains;
+      const changed = chainsAdvanced || r.inbox.stored + r.metadata.certificates + r.metadata.snapshots + r.metadata.successions + (r.bootstrap?.circles ?? 0) + (r.bootstrap?.pending ?? 0) > 0;
+      if (!changed && signature !== "" && signature === previousErrors) {
+        stop = r.errors.some((e) => e.code === "METADATA_REQUIRED" || e.code === "RESET_KEYS_REQUIRED" || e.code === "RESET_CLOCK_UNTRUSTED") ? "metadata" : "noProgress";
+        break;
+      }
+      previousErrors = signature;
+      if (rounds >= maxRounds) {
+        stop = "maxRounds";
+        break;
+      }
+      if (this.now() >= deadline) {
+        stop = "maxMs";
+        break;
+      }
+    }
+    merged.inbox.hasMore = last?.inbox.hasMore ?? false;
+    const bootstrapIncomplete = this.closed ? false : (await this.inspect()).bootstrap?.complete === false;
+    const chainsIncomplete = this.closed ? previousChains.size : (await chains()).size;
+    const waitingFor = this.closed ? 0 : (await this.getState()).waitingFor.length;
+    const inboxHasMore = !last || inboxUncertain(last) || stop === "closed" || stop === "rateLimited" ? "unknown" : merged.inbox.hasMore;
+    const waits = (last?.errors ?? []).flatMap((e) => (e.code === "RATE_LIMITED" && e.retryAfterMs !== undefined ? [e.retryAfterMs] : []));
+    const retryAfterMs = waits.length ? Math.max(...waits) : undefined;
+    return { ...merged, rounds, stoppedBecause: stop, remaining: { inboxHasMore, bootstrapIncomplete, chainsIncomplete, waitingFor, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) } };
+  }
+
   private async runSync(options: SyncOptions): Promise<SyncReport> {
+    const started = wall();
     const report: SyncReport = {
       metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
       epoch: "unchanged",
       outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 },
       inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false },
       purged: 0,
+      maintenance: options.skipMaintenance ? "skipped" : "done",
+      timings: emptyTimings(),
       errors: []
     };
+    const maintain = !options.skipMaintenance;
+    let mark = started;
+    const phase = (name: keyof Omit<SyncTimings, "total" | "bytesSent" | "bytesReceived">): void => {
+      const now = wall();
+      report.timings[name] += now - mark;
+      mark = now;
+    };
+    const finish = (): SyncReport => {
+      report.timings.total = wall() - started;
+      return report;
+    };
+    try {
+      return await this.runSyncPhases(options, report, maintain, phase);
+    } finally {
+      finish();
+    }
+  }
+
+  private async runSyncPhases(options: SyncOptions, report: SyncReport, maintain: boolean, phase: (name: keyof Omit<SyncTimings, "total" | "bytesSent" | "bytesReceived">) => void): Promise<SyncReport> {
     this.syncBudget = {
       remainingRecords: Math.max(1, Math.floor(options.catchUp?.maxRecords ?? DEFAULT_CATCH_UP.maxRecords)),
       deadline: this.now() + BigInt(Math.max(0, Math.floor(options.catchUp?.maxMs ?? DEFAULT_CATCH_UP.maxMs)))
@@ -871,6 +1170,7 @@ class ClientImpl implements Client {
         }
       }
     }
+    phase("resume");
     if (!this.account || !this.selfPin) return report;
     const meta = await this.store.read((tx) => tx.get("meta", META));
     if (!meta || meta.state === "RETIRED") return report;
@@ -895,7 +1195,9 @@ class ClientImpl implements Client {
         return report;
       }
     } else if (meta.state !== "ACTIVE") return report;
-    await this.ensureBackup();
+    phase("resume");
+    if (maintain) await this.ensureBackup();
+    phase("maintenance");
     if (meta.bootstrap && !meta.bootstrap.complete) {
       try {
         report.bootstrap = await this.bootstrap(report, meta.bootstrap);
@@ -903,28 +1205,38 @@ class ClientImpl implements Client {
         report.errors.push(syncError("bootstrap", e));
       }
     }
+    phase("bootstrap");
     try {
-      await this.syncMetadata(report);
+      await this.syncMetadata(report, maintain);
     } catch (e) {
       report.errors.push(syncError("metadata", e));
     }
+    phase("metadata");
     try {
       await this.pushPreferences(report);
     } catch (e) {
       report.errors.push(syncError("preference", e));
     }
+    phase("preferences");
     const after = await this.store.read((tx) => tx.get("meta", META));
-    if (after?.state === "RETIRED") return report;
+    if (after?.state === "RETIRED" || this.closed) return report;
     try {
       report.epoch = await this.ensureEpoch();
     } catch (e) {
       report.errors.push(syncError("epoch", e));
     }
+    phase("epoch");
+    if (this.closed) return report;
     try {
-      report.outbox = await drain(this.outboxDeps());
+      const drained = await drain(this.outboxDeps());
+      report.outbox = { sent: drained.sent, accepted: drained.accepted, cancelled: drained.cancelled, unknown: drained.unknown, retry: drained.retry };
+      report.timings.bytesSent += drained.bytes;
+      if (drained.blocked) report.errors.push(syncError("outbox", drained.blocked)); // the records stay queued
     } catch (e) {
       report.errors.push(syncError("outbox", e));
     }
+    phase("outbox");
+    if (this.closed) return report;
     let subs: Awaited<ReturnType<Relay["listSubscriptions"]>> = [];
     try {
       subs = await this.transport.relay.listSubscriptions();
@@ -937,26 +1249,35 @@ class ClientImpl implements Client {
     const budget: ReadBudget = this.syncBudget;
     if (budget.remainingRecords < 1) budget.remainingRecords = 1; // every stream reads at least one page
     for (const s of subs) {
+      if (this.closed) return report;
       try {
         const known = await this.store.read((tx) => tx.list("certificates").some(([, c]) => c.streamId === toHex(s.streamId)));
         if (!known) continue;
         const r = await syncStream(this.inboxDeps(), s.streamId, s.authorIdentityId, budget);
-        report.inbox.streams++;
+        // What landed counts, whether or not the stream then failed; a failed stream is not synced.
         report.inbox.stored += r.stored;
         report.inbox.keyPending += r.keyPending;
         report.inbox.invalid += r.invalid;
+        report.timings.bytesReceived += r.bytes;
+        if (r.failure !== undefined) {
+          report.errors.push({ ...syncError("inbox", r.failure), streamId: s.streamId, authorIdentityId: s.authorIdentityId });
+          continue;
+        }
+        report.inbox.streams++;
         if (r.acked !== undefined) report.inbox.acked++;
         if (r.hasMore) report.inbox.hasMore = true;
       } catch (e) {
         report.errors.push({ ...syncError("inbox", e), streamId: s.streamId, authorIdentityId: s.authorIdentityId });
       }
     }
-    report.purged = (await purgeHistory(this.store, this.policy, this.now())) + (await purgeOutbox(this.store, this.policy, this.now()));
+    phase("inbox");
+    if (maintain) report.purged = (await purgeHistory(this.store, this.policy, this.now())) + (await purgeOutbox(this.store, this.policy, this.now()));
+    phase("maintenance");
     await this.emitState();
     return report;
   }
 
-  private async syncMetadata(report: SyncReport): Promise<void> {
+  private async syncMetadata(report: SyncReport, maintain = true): Promise<void> {
     const { pin } = this.requireAccount("sync");
     // Own account: has this device been superseded?
     const [me] = await this.transport.directory.resolveAccounts([this.accountName]);
@@ -978,9 +1299,9 @@ class ClientImpl implements Client {
         return;
       }
     }
-    // Reset-key list when due.
+    // Reset-key list when due: always when stale (verification needs it), periodically unless maintenance is skipped.
     const now = this.now();
-    const due = !this.trust.fresh(now) || now - this.trust.state.timeHighWater >= RESET_LIST_RECHECK_MS;
+    const due = !this.trust.fresh(now) || (maintain && now - this.trust.state.timeHighWater >= RESET_LIST_RECHECK_MS);
     if (due) {
       const wire = await this.transport.directory.getResetKeyList();
       if (wire) {
@@ -1480,10 +1801,6 @@ class ClientImpl implements Client {
 
   // Receiving and reads ---------------------------------------------------------------------------
 
-  receive(wire: Uint8Array): Promise<ReceiveResult> {
-    return receiveRecord(this.inboxDeps(), wire);
-  }
-
   history(query?: HistoryQuery): Promise<HistoryEntry[]> {
     return history(this.store, this.policy, query);
   }
@@ -1678,7 +1995,7 @@ class ClientImpl implements Client {
   private async approve(circleId: Uint8Array, accountName: string): Promise<{ revision: bigint }> {
     const [resolved] = await this.transport.directory.resolveAccounts([accountName]);
     if (!resolved) throw new KavachError("METADATA_REQUIRED", "approve", "unknown account");
-    const report: SyncReport = { metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 }, epoch: "unchanged", outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 }, inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false }, purged: 0, errors: [] };
+    const report: SyncReport = { metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 }, epoch: "unchanged", outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 }, inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false }, purged: 0, maintenance: "done", timings: emptyTimings(), errors: [] };
     await this.acceptMemberCertificate(resolved, report);
     const requester = resolvedAccountId(resolved);
     const pinned = await this.pinFor(requester);
@@ -1848,7 +2165,7 @@ class ClientImpl implements Client {
 
   // Account recovery (amendment A1) ---------------------------------------------------------------
 
-  async prepareReplacement(): Promise<ReplacementProposal> {
+  private async prepareReplacementNow(): Promise<ReplacementProposal> {
     const stage = "prepareReplacement";
     if (!acceptsSuccession(this.policy)) throw new KavachError("NOT_AUTHORIZED", stage, "this deployment does not use account recovery");
     const opened = await openStore(this.store, this.secrets, this.accountName);
@@ -1893,7 +2210,7 @@ class ClientImpl implements Client {
     return proposalOf(row);
   }
 
-  async completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
+  private async completeReplacementNow(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
     const stage = "completeReplacement";
     // Already activated (by an earlier call, or by a sync that found the commit on the chain): idempotent.
     if (this.selfPin && this.account && !this.retired) return { identityId: this.selfPin.identityId, generation: this.selfPin.generation };
@@ -2143,7 +2460,7 @@ class ClientImpl implements Client {
 
   // Reset -----------------------------------------------------------------------------------------
 
-  async resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
+  private async resetAccountNow(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
     const stage = "resetAccount";
     if (!options.confirmed) throw new KavachError("NOT_AUTHORIZED", stage, "reset requires confirmation");
     const { pin } = this.requireAccount(stage);
@@ -2227,7 +2544,50 @@ class ClientImpl implements Client {
   }
 
   async close(): Promise<void> {
+    this.closed = true;
+    // Everything in flight finishes its current transaction; a sync stops at its next boundary.
+    while (this.running.size > 0) await Promise.allSettled([...this.running]);
     this.listeners.clear();
   }
+
+  // The replacement helper ------------------------------------------------------------------------
+
+  private async replaceDeviceNow(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult> {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+    const activated = (): ReplaceDeviceResult | undefined => (this.selfPin && this.account && !this.retired ? { status: "activated", identityId: this.selfPin.identityId, generation: this.selfPin.generation } : undefined);
+    const done = activated();
+    if (done) return done;
+    // A proposal left by an earlier run may have committed: the chain settles it before anything else.
+    const existing = await this.store.read((tx) => tx.get("replacement", "pending"));
+    if (existing && !existing.stale) {
+      await this.sync();
+      const settled = activated();
+      if (settled) return settled;
+    }
+    const proposal = await this.prepareReplacementNow();
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const authorization = await options.authorize(proposal);
+      if (authorization === "reauthenticate") return { status: "reauthenticate", proposal };
+      for (;;) {
+        try {
+          const r = await this.completeReplacementNow({ successionId: proposal.successionId, authorization });
+          return { status: "activated", identityId: r.identityId, generation: r.generation };
+        } catch (e) {
+          if (isKavachError(e, "SUCCESSION_PENDING")) {
+            // The same call again with the same bytes; the host answers a committed id first.
+            if (++attempt >= maxAttempts) return { status: "pending", proposal };
+            continue;
+          }
+          if (isKavachError(e, "AUTHORIZATION_REQUIRED")) break; // a fresh token for the same proposal
+          if (isKavachError(e, "REPLACEMENT_CONFLICT")) {
+            const conflict = (await this.inspect()).replacement;
+            return { status: "conflict", currentGeneration: conflict?.conflictGeneration };
+          }
+          throw e;
+        }
+      }
+    }
+    return { status: "pending", proposal };
+  }
 }