@plane31/blind-relay 0.1.3 → 0.2.0

package/src/client.ts

@@ -6,7 +6,7 @@
 import { concat, equalBytes, fromHex, toHex } from "./bytes.js";
 import { resolveAudience, type ResolvedAudience } from "./audience.js";
 import { acceptSnapshot, checkMemberResolution, createCircleSnapshot, newCircleId, pinCircle, successorSnapshot, type CircleState } from "./circle.js";
-import { DocumentType, expectType, parseVaultHeader, verifyDocument, type AccountDevice, type RecordKind } from "./codec.js";
+import { DocumentType, buildCircleSnapshot, expectType, parseDocument, parseVaultHeader, verifyDocument, type AccountDevice, type AccountSuccession, type RecordKind } from "./codec.js";
 import { randomBytes, ready, type BoxKeypair } from "./crypto.js";
 import { prepareEpoch, resolvePublish, type PreparedEpoch } from "./epoch.js";
 import { KavachError, isKavachError, type ErrorCode } from "./errors.js";
@@ -21,12 +21,13 @@ export interface EnqueueResult {
   readonly recordId: Uint8Array;
   readonly duplicate: boolean;
 }
-import { kindOf, validatePolicy, type RetentionPolicy } from "./policy.js";
+import { acceptsSuccession, allowsContinuity, kindOf, validatePolicy, type ReplacementModel, type RetentionPolicy } from "./policy.js";
 import { ResetTrust, type ResetTrustConfig } from "./reset.js";
 import { big, circleToRow, pinToRow, rowToCircle, rowToPin, rowToPrepared, unbig } from "./rows.js";
-import type { CircleRow, PendingResetRow, SecretStore, Store, Tx, VaultRow } from "./store.js";
+import type { BootstrapRetryRow, CircleRow, MetaRow, PendingResetRow, ReplacementRow, SecretStore, Store, Tx, VaultRow } from "./store.js";
 import { META, REVISION, STREAM, VAULT, openStore, t1Activate, t1Header, t1Secrets, t2PrepareActivation, t3ApplyChange, t3Circle, t4PersistPrepared, t5Committed, t8OwnerSnapshot, t9MarkVault, t9Vault } from "./transactions.js";
-import type { Relay, Transport } from "./transport.js";
+import { applySuccession, authenticateSuccession, pinnedState, recordChainIn, rootIdentityIn, rootState, sameTransition, transitionOf, validateTransition, verifyChain, type SuccessionEffect, type VerifiedLink } from "./succession.js";
+import type { CircleListing, Directory, Relay, ResolvedAccount, SuccessionLink, Transport } from "./transport.js";
 import { buildVault, encodeRecoveryCode, newRecoveryKey, openVault, recoverAccount, removeEntry, upsertEntry, type ProviderStatusResult, type RecoveryProvider, type VaultEntry } from "./vault.js";
 
 /** The types of the client's queries and of `receive`, defined with the inbox. */
@@ -51,13 +52,28 @@ function sameEntries(a: readonly VaultEntry[], b: readonly VaultEntry[]): boolea
   return key(a) === key(b);
 }
 
-export type ClientStatus = "fresh" | "ready" | "locked" | "accountRecoveryRequired" | "activationPending" | "retired" | "paused" | "quarantined";
+export type ClientStatus = "fresh" | "replacementPrepared" | "ready" | "locked" | "accountRecoveryRequired" | "activationPending" | "retired" | "paused" | "quarantined";
 export type PauseReason = "sync" | "rotation" | "metadata" | "limit";
 
+function proposalOf(row: ReplacementRow): ReplacementProposal {
+  return { successionId: fromHex(row.successionId), accountName: row.accountName, accountId: fromHex(row.accountId), expectedCertificateHash: fromHex(row.expectedCertificateHash), expectedGeneration: unbig(row.expectedGeneration), certificate: fromHex(row.certificate) };
+}
+
+/** The account id a directory answer names: the root of its succession chain, else the identity of its key. */
+export function resolvedAccountId(r: ResolvedAccount): Uint8Array {
+  const first = r.successions?.[0];
+  if (first) return expectType<AccountSuccession>(parseDocument(first.wire), DocumentType.AccountSuccession, "resolve").accountId;
+  const doc = expectType<AccountDevice>(verifyDocument(r.certificate), DocumentType.AccountDevice, "resolve");
+  return pinFromCertificate(doc).identityId;
+}
+
 export interface ClientState {
   readonly status: ClientStatus;
   readonly paused: PauseReason | undefined;
+  /** The account id: what circles, manifests and records name. Constant across successions. */
   readonly identityId: Uint8Array | undefined;
+  /** The identity of the current account key; equal to `identityId` until a succession. */
+  readonly keyIdentityId: Uint8Array | undefined;
   readonly certificateHash: Uint8Array | undefined;
   readonly generation: bigint | undefined;
   readonly outbox: number;
@@ -69,6 +85,13 @@ export interface ClientState {
 /** Diagnostics: where the protocol stands on this device. Never a secret or a plaintext. */
 export interface Inspection {
   readonly identityId: Uint8Array | undefined;
+  readonly keyIdentityId: Uint8Array | undefined;
+  /** The replacement models the profile enables; never a runtime choice. */
+  readonly replacementModel: ReplacementModel;
+  /** A prepared account-recovery proposal on this device, until it commits or is definitively conflicted. */
+  readonly replacement: { readonly successionId: Uint8Array; readonly expectedGeneration: bigint; readonly stale: boolean; readonly conflictGeneration: bigint | undefined } | undefined;
+  /** Discovery after account recovery: where it stands. */
+  readonly bootstrap: { readonly cursor: string | undefined; readonly complete: boolean } | undefined;
   readonly certificateHash: Uint8Array | undefined;
   readonly generation: bigint | undefined;
   readonly desiredRevision: bigint;
@@ -110,7 +133,8 @@ export type ClientEvent =
 export interface OpenOptions {
   readonly accountName: string;
   readonly retentionPolicy: unknown;
-  readonly recoveryProvider: RecoveryProvider;
+  /** The platform's synced secret store for the recovery key. Required when the profile enables identity continuity; a recovery-only profile may omit it, and then has no vault backup and no recovery code. */
+  readonly recoveryProvider?: RecoveryProvider;
   readonly resetTrust: ResetTrustConfig;
   readonly secretStore: SecretStore;
   readonly store: Store;
@@ -128,6 +152,21 @@ export interface Client {
   recoveryStatus(): Promise<ProviderStatusResult>;
   recoveryCode(): Promise<string>;
   restoreAccount(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }>;
+  /**
+   * Account recovery (amendment A1), on a fresh device with no secret from the old one: prepare
+   * a replacement under fresh keys and return the proposal the product takes to the host's fresh
+   * authentication. A second call returns the same pending proposal. The remote account is untouched.
+   */
+  prepareReplacement(): Promise<ReplacementProposal>;
+  /**
+   * Commit the prepared replacement with the host's authorization. `SUCCESSION_PENDING` means the
+   * outcome is unknown and the same call is to be made again; `REPLACEMENT_CONFLICT` means the
+   * account moved and the next `prepareReplacement()` starts over; `AUTHORIZATION_REQUIRED` means
+   * the host refused the authorization.
+   */
+  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[]>;
   /** 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). */
@@ -169,15 +208,39 @@ export interface SyncOptions {
 export const DEFAULT_CATCH_UP = { maxRecords: 500, maxMs: 5_000 } as const;
 
 export interface SyncReport {
-  metadata: { certificates: number; snapshots: number; rotations: number; quarantined: number; resets: number };
+  metadata: { certificates: number; snapshots: number; rotations: number; quarantined: number; resets: number; successions: number };
   epoch: "unchanged" | "prepared" | "paused" | "pending";
   outbox: { sent: number; accepted: number; cancelled: number; unknown: number; retry: number };
   /** `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;
+  /** Present while account recovery discovers circles through the host: pinned, pending and failed on this sync. */
+  bootstrap?: { circles: number; pending: number; failed: number };
   errors: SyncError[];
 }
 
+/** What `prepareReplacement()` returns: everything the product hands to the host for authorization. All public. */
+export interface ReplacementProposal {
+  readonly successionId: Uint8Array;
+  readonly accountName: string;
+  readonly accountId: Uint8Array;
+  readonly expectedCertificateHash: Uint8Array;
+  readonly expectedGeneration: bigint;
+  readonly certificate: Uint8Array;
+}
+
+/** One accepted key change of a contact: a verified succession or a validated reset. */
+export interface KeyChangeEntry {
+  readonly accountId: Uint8Array;
+  readonly accountName: string;
+  readonly previousIdentityId: Uint8Array;
+  readonly newIdentityId: Uint8Array;
+  readonly generation: bigint;
+  readonly reason: "succession" | "reset";
+  readonly successionId: Uint8Array | undefined;
+  readonly acceptedAt: bigint;
+}
+
 /** One failure a sync worked around: which step, the protocol code and stage, and whether the same step may succeed later unchanged. */
 export interface SyncError {
   readonly operation: string;
@@ -191,10 +254,12 @@ export interface SyncError {
    */
   readonly streamId?: Uint8Array;
   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;
 }
 
-function syncError(operation: string, e: unknown): SyncError {
-  return e instanceof KavachError ? { operation, code: e.code, stage: e.stage, retryable: e.retryable } : { operation, code: "UNEXPECTED", stage: operation, retryable: false };
+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 };
 }
 
 const RESET_LIST_RECHECK_MS = 86_400_000n;
@@ -202,6 +267,7 @@ const RESET_LIST_RECHECK_MS = 86_400_000n;
 export async function open(options: OpenOptions): Promise<Client> {
   await ready();
   const policy = validatePolicy(options.retentionPolicy);
+  if (!options.recoveryProvider && allowsContinuity(policy)) throw new KavachError("MALFORMED", "open", "recoveryProvider is required when the profile enables identity continuity");
   const impl = new ClientImpl(options, policy);
   await impl.load();
   return impl;
@@ -212,14 +278,22 @@ class ClientImpl implements Client {
   private readonly store: Store;
   private readonly secrets: SecretStore;
   private readonly transport: Transport;
-  private readonly provider: RecoveryProvider;
+  private readonly provider: RecoveryProvider | undefined;
+  /** A vault exists only where a recovery provider does: a recovery-only profile without one has no path that reads it. */
+  private get vaultEnabled(): boolean {
+    return this.provider !== undefined;
+  }
   private readonly now: () => bigint;
   private readonly listeners = new Set<(e: ClientEvent) => void>();
   private account: OwnAccount | undefined;
+  /** Retired by a succession or a later device: nothing is written from here again. */
+  private retired = false;
   private device: DeviceKeys | undefined;
   private selfPin: AccountPin | undefined;
   private trust: ResetTrust;
   private syncing: Promise<SyncReport> | undefined;
+  /** The current sync's reading budget: records, and the links of a succession chain, count against it. */
+  private syncBudget: ReadBudget | undefined;
   private backupChecked = false;
   readonly circles: Client["circles"];
 
@@ -252,14 +326,16 @@ class ClientImpl implements Client {
     await this.finishInterruptedReset();
     const opened = await openStore(this.store, this.secrets, this.accountName);
     if (opened.kind === "fresh") return;
+    this.retired = opened.kind === "RETIRED";
     await ensureHistoryIndex(this.store);
     await ensureSlots(this.store, this.policy);
     this.account = opened.account;
     const deviceSeed = await this.secrets.get("deviceSeed");
     const self = await this.store.read((tx) => tx.get("self", "self"));
-    if (deviceSeed && self) {
+    if (deviceSeed && self && opened.account) {
+      const accountId = opened.account.accountId;
       this.device = deviceFromSeed(deviceSeed, fromHex(self.deviceId));
-      const pinRow = await this.store.read((tx) => tx.get("pins", toHex(opened.account.identityId)));
+      const pinRow = await this.store.read((tx) => tx.get("pins", toHex(accountId)));
       if (pinRow) this.selfPin = rowToPin(pinRow);
     }
     const rows = await this.store.read((tx) => ({
@@ -299,13 +375,14 @@ class ClientImpl implements Client {
   }
 
   private requireAccount(stage: string): { account: OwnAccount; device: DeviceKeys; pin: AccountPin } {
+    if (this.retired) throw new KavachError("SUPERSEDED_DEVICE", stage, "this device is retired");
     if (!this.account || !this.device || !this.selfPin) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, "no account on this device");
     return { account: this.account, device: this.device, pin: this.selfPin };
   }
 
   private selfView(): { identityId: Uint8Array; certificateHash: Uint8Array; box: BoxKeypair } {
     const { device, pin } = this.requireAccount("self");
-    return { identityId: pin.identityId, certificateHash: pin.certificateHash, box: device.box };
+    return { identityId: pin.accountId, certificateHash: pin.certificateHash, box: device.box };
   }
 
   private outboxDeps() {
@@ -315,7 +392,7 @@ class ClientImpl implements Client {
       relay: this.transport.relay,
       policy: this.policy,
       now: this.now,
-      author: () => ({ streamId: pin.streamId, signingSecretKey: device.signing.secretKey, generation: pin.generation, identityId: pin.identityId }),
+      author: () => ({ streamId: pin.streamId, signingSecretKey: device.signing.secretKey, generation: pin.generation, identityId: pin.accountId }),
       events: {
         queued: (recordId: Uint8Array, recordKind: RecordKind) => this.emit({ kind: "queued", recordId, recordKind }),
         accepted: (recordId: Uint8Array) => this.emit({ kind: "accepted", recordId }),
@@ -347,8 +424,11 @@ class ClientImpl implements Client {
 
   async getState(): Promise<ClientState> {
     const meta = await this.store.read((tx) => tx.get("meta", META));
-    const base = { identityId: this.selfPin?.identityId, certificateHash: this.selfPin?.certificateHash, generation: this.selfPin?.generation, outbox: 0, waitingFor: [] as Uint8Array[], circles: [] as CircleSummary[] };
-    if (!meta || !this.account) return { status: "fresh", paused: undefined, ...base };
+    const base = { identityId: this.selfPin?.accountId, keyIdentityId: this.selfPin?.identityId, certificateHash: this.selfPin?.certificateHash, generation: this.selfPin?.generation, outbox: 0, waitingFor: [] as Uint8Array[], circles: [] as CircleSummary[] };
+    if (!meta || (!this.account && meta.state !== "RETIRED")) {
+      const proposal = await this.store.read((tx) => tx.get("replacement", "pending"));
+      return { status: proposal && !proposal.stale ? "replacementPrepared" : "fresh", paused: undefined, ...base };
+    }
     const circles = await this.listCircles();
     const outbox = await outboxCount(this.store);
     const waitingFor = await this.waitingFor();
@@ -365,7 +445,7 @@ class ClientImpl implements Client {
 
   private async waitingFor(): Promise<Uint8Array[]> {
     if (!this.selfPin) return [];
-    const selfHex = toHex(this.selfPin.identityId);
+    const selfHex = toHex(this.selfPin.accountId);
     return this.store.read((tx) => {
       const authors = new Set<string>();
       for (const [, c] of tx.list("circles")) if (c.status === "member") for (const m of c.members) if (m !== selfHex) authors.add(m);
@@ -386,9 +466,15 @@ class ClientImpl implements Client {
       const stream = tx.get("stream", STREAM);
       const revision = tx.get("revision", REVISION);
       const vault = tx.get("vault", VAULT);
+      const meta = tx.get("meta", META);
+      const proposal = tx.get("replacement", "pending");
       const pendingEpoch = tx.list("epochs").find(([, e]) => e.status === "prepared" || e.status === "committed")?.[1].epoch;
       return {
-        identityId: this.selfPin?.identityId,
+        identityId: this.selfPin?.accountId,
+        keyIdentityId: this.selfPin?.identityId,
+        replacementModel: this.policy.replacement,
+        replacement: proposal ? { successionId: fromHex(proposal.successionId), expectedGeneration: unbig(proposal.expectedGeneration), stale: proposal.stale, conflictGeneration: proposal.conflictGeneration === undefined ? undefined : unbig(proposal.conflictGeneration) } : undefined,
+        bootstrap: meta?.bootstrap ? { cursor: meta.bootstrap.cursor, complete: meta.bootstrap.complete } : undefined,
         certificateHash: this.selfPin?.certificateHash,
         generation: this.selfPin?.generation,
         desiredRevision: revision ? unbig(revision.desiredRevision) : 1n,
@@ -424,8 +510,8 @@ class ClientImpl implements Client {
     const pin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice));
     const iid = instanceId;
     await this.store.transaction((tx) => t1Header(tx, { account, device, certificate, instanceId: iid, generation: 1n }));
-    const vault = buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: 1n }, { accountSeed, lastDeviceGeneration: 1n, lastCertificateHash: pin.certificateHash, entries: [] }, recoveryKey);
-    const outcome = await this.transport.directory.registerAccount({ certificate, vault: vault.wire });
+    const vault = this.vaultEnabled ? buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: 1n }, { accountSeed, lastDeviceGeneration: 1n, lastCertificateHash: pin.certificateHash, entries: [] }, recoveryKey) : undefined;
+    const outcome = await this.transport.directory.registerAccount({ certificate, vault: vault?.wire });
     if (outcome.status === "CONFLICT") {
       // A restart or a lost response after the host committed: the name is ours if the host holds
       // exactly the certificate this device saved; anything else is somebody else's account.
@@ -435,7 +521,7 @@ class ClientImpl implements Client {
       throw new KavachError("NOT_AUTHORIZED", stage, `host refused registration: ${outcome.status}`);
     }
     await this.store.transaction((tx) => {
-      t9Vault(tx, { revision: "1", hash: toHex(vault.hash), wire: toHex(vault.wire), pending: false, dirty: false });
+      if (vault) t9Vault(tx, { revision: "1", hash: toHex(vault.hash), wire: toHex(vault.wire), pending: false, dirty: false });
       t1Activate(tx);
     });
     this.account = account;
@@ -443,7 +529,7 @@ class ClientImpl implements Client {
     this.selfPin = pin;
     // The recovery key goes to the provider; enrollment never blocks on it or on the code.
     try {
-      await this.provider.save(this.accountName, pin.identityId, recoveryKey);
+      await this.provider?.save(this.accountName, pin.identityId, recoveryKey);
     } catch {
       /* status is reported by recoveryStatus() */
     }
@@ -452,10 +538,14 @@ class ClientImpl implements Client {
   }
 
   async recoveryStatus(): Promise<ProviderStatusResult> {
+    if (!this.provider) return { status: "unsupported", backupState: "unavailable", reason: "no recovery provider on a recovery-only profile" };
     return this.provider.status();
   }
 
   async recoveryCode(): Promise<string> {
+    // A code opens a vault for identity continuity; where the profile disables that, or where no
+    // vault exists, the code would open nothing and is not issued.
+    if (!allowsContinuity(this.policy) || !this.vaultEnabled) throw new KavachError("NOT_AUTHORIZED", "recoveryCode", "this deployment does not restore accounts by recovery code");
     const key = await this.secrets.get("recoveryKey");
     if (!key) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", "recoveryCode");
     return encodeRecoveryCode(key);
@@ -473,12 +563,18 @@ class ClientImpl implements Client {
       // moved under us): prepare again with the same device keys. Nothing was allocated remotely.
       pending = resumed;
     }
+    if (!allowsContinuity(this.policy)) throw new KavachError("NOT_AUTHORIZED", stage, "this deployment replaces devices through successions, not the recovery key");
     const [resolved] = await this.transport.directory.resolveAccounts([this.accountName]);
     if (!resolved) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, "unknown account");
     const current = expectType<AccountDevice>(verifyDocument(resolved.certificate), DocumentType.AccountDevice, stage);
     const vaultWire = await this.transport.directory.getVault(this.accountName);
     if (!vaultWire) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, "no vault");
+    const accountId = resolvedAccountId(resolved);
     const identity = pinFromCertificate(current).identityId;
+    if (!this.provider) throw new KavachError("NOT_AUTHORIZED", stage, "identity continuity needs a recovery provider");
+    // An account that succeeded: the served chain is verified link by link under the current list,
+    // from the root to the key this device is about to hold, before anything is written.
+    const verified = resolved.successions?.length ? (await this.followChain({ accountId, accountName: this.accountName, finalIdentityId: identity, firstPage: resolved.successions, next: resolved.successionsNext })).verified : [];
     const recovered = await recoverAccount({
       accountName: this.accountName,
       identityId: identity,
@@ -487,12 +583,12 @@ class ClientImpl implements Client {
       provider: this.provider,
       ...(recoveryCode === undefined ? {} : { recoveryCode })
     });
-    const account = openAccount(this.accountName, recovered.vault.accountSeed);
+    const account = openAccount(this.accountName, recovered.vault.accountSeed, accountId);
     // Fresh device keys and a fresh local store. Nothing from the old device is copied.
     const device = pending?.device ?? newDevice();
     const generation = current.generation + 1n;
     const certificate = certify(account, device, generation);
-    const pin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice));
+    const pin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice), undefined, accountId);
     const header = parseVaultHeader(vaultWire);
     const nextVault = buildVault(
       { accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: header.vaultRevision + 1n },
@@ -503,6 +599,8 @@ class ClientImpl implements Client {
     if (!pending) await t1Secrets(this.secrets, { accountSeed: recovered.vault.accountSeed, deviceSeed: device.deviceSeed, recoveryKey: recovered.recoveryKey, instanceId });
     await this.store.transaction((tx) => {
       t1Header(tx, { account, device, certificate, instanceId, generation });
+      recordChainIn(tx, verified, this.now());
+      rootIdentityIn(tx, accountId, this.accountName, resolved.rootCertificate);
       t2PrepareActivation(tx, {
         certificate: toHex(certificate),
         vault: toHex(nextVault.wire),
@@ -538,7 +636,7 @@ class ClientImpl implements Client {
       tx.delete("activation", "pending");
       t9Vault(tx, { revision: big(input.vaultRevision), hash: toHex(input.vault.hash), wire: toHex(input.vault.wire), pending: false, dirty: false });
       for (const e of input.entries) {
-        const owned = equalBytes(e.ownerIdentityId, pin.identityId);
+        const owned = equalBytes(e.ownerIdentityId, pin.accountId);
         const c = pinCircle(e.circleId, e.ownerIdentityId, e.sharingEnabled, owned ? "member" : "requested");
         tx.put("circles", toHex(e.circleId), circleToRow(c));
       }
@@ -549,7 +647,7 @@ class ClientImpl implements Client {
     this.device = device;
     this.selfPin = pin;
     try {
-      await this.provider.save(this.accountName, pin.identityId, input.recoveryKey);
+      await this.provider?.save(this.accountName, pin.identityId, input.recoveryKey);
     } catch {
       /* reported by recoveryStatus() */
     }
@@ -568,13 +666,14 @@ class ClientImpl implements Client {
     const row = await this.store.read((tx) => tx.get("activation", "pending"));
     if (!row) throw new KavachError("RECOVERY_REQUIRED", stage, "activation pending without its prepared bytes");
     const [accountSeed, deviceSeed, recoveryKey, instanceId] = await Promise.all([this.secrets.get("accountSeed"), this.secrets.get("deviceSeed"), this.secrets.get("recoveryKey"), this.secrets.get("instanceId")]);
-    const self = await this.store.read((tx) => tx.get("self", "self"));
-    if (!accountSeed || !deviceSeed || !recoveryKey || !instanceId || !self) throw new KavachError("RECOVERY_REQUIRED", stage, "activation pending without its roots");
-    const account = openAccount(this.accountName, accountSeed);
+    const [self, meta] = await this.store.read((tx) => [tx.get("self", "self"), tx.get("meta", META)] as const);
+    if (!accountSeed || !deviceSeed || !recoveryKey || !instanceId || !self || !meta) throw new KavachError("RECOVERY_REQUIRED", stage, "activation pending without its roots");
+    const accountId = fromHex(meta.accountId ?? meta.identityId);
+    const account = openAccount(this.accountName, accountSeed, accountId);
     const device = deviceFromSeed(deviceSeed, fromHex(self.deviceId));
     const certificate = fromHex(row.certificate);
     const prepared = expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice, stage);
-    const pin = pinFromCertificate(prepared);
+    const pin = pinFromCertificate(prepared, undefined, accountId);
     const [me] = await this.transport.directory.resolveAccounts([this.accountName]);
     if (!me) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, "unknown account");
     const theirs = expectType<AccountDevice>(verifyDocument(me.certificate), DocumentType.AccountDevice, stage);
@@ -603,7 +702,7 @@ class ClientImpl implements Client {
    * asks the provider and saves again when it has nothing for this identity.
    */
   private async ensureBackup(): Promise<void> {
-    if (this.backupChecked || !this.selfPin) return;
+    if (this.backupChecked || !this.selfPin || !this.provider) return;
     this.backupChecked = true;
     try {
       const key = await this.secrets.get("recoveryKey");
@@ -646,7 +745,7 @@ class ClientImpl implements Client {
 
   /** After commit: the device's own record is stored like any author's, so one subscription covers self and others. */
   private enqueued(kind: RecordKind, r: { recordId: Uint8Array; duplicate: boolean; own: boolean }): EnqueueResult {
-    if (!r.duplicate && this.selfPin) this.emit({ kind: "recordStored", recordKind: kind, authorIdentityId: this.selfPin.identityId, recordId: r.recordId, tookSlot: r.own });
+    if (!r.duplicate && this.selfPin) this.emit({ kind: "recordStored", recordKind: kind, authorIdentityId: this.selfPin.accountId, recordId: r.recordId, tookSlot: r.own });
     return { recordId: r.recordId, duplicate: r.duplicate };
   }
 
@@ -656,7 +755,11 @@ class ClientImpl implements Client {
     const { pin } = this.requireAccount("audience");
     const retired = new Set(this.trust.state.retired);
     return this.store.read((tx) => {
+      // A reset retires the whole account, however many successions it went through.
+      for (const [, r] of tx.list("identities")) if (r.resetAt !== undefined) retired.add(r.accountId);
       const pins = new Map(tx.list("pins").map(([k, p]) => [k, rowToPin(p)]));
+      // An account whose chain this device has not finished verifying is out of every audience until it has.
+      for (const [, p] of tx.list("chainProgress")) if (!p.complete) pins.delete(p.accountId);
       const circles = tx.list("circles").map(([, c]) => rowToCircle(c));
       return resolveAudience(pin, circles, pins, retired);
     });
@@ -692,7 +795,7 @@ class ClientImpl implements Client {
       } else {
         const revision = revisionRow ? unbig(revisionRow.desiredRevision) : 1n;
         const fresh = prepareEpoch({
-          author: { identityId: pin.identityId, certificateHash: pin.certificateHash, streamId: pin.streamId, signingSecretKey: device.signing.secretKey },
+          author: { identityId: pin.accountId, certificateHash: pin.certificateHash, streamId: pin.streamId, signingSecretKey: device.signing.secretKey },
           epoch: stream.highestCommittedEpoch + 1,
           createdAt: this.now(),
           audience,
@@ -744,13 +847,30 @@ class ClientImpl implements Client {
 
   private async runSync(options: SyncOptions): Promise<SyncReport> {
     const report: SyncReport = {
-      metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0 },
+      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: []
     };
+    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)))
+    };
+    if (!this.selfPin) {
+      // A prepared replacement whose commit this device never saw: the chain says whether it landed.
+      const row = await this.store.read((tx) => tx.get("replacement", "pending"));
+      if (row && !row.stale) {
+        try {
+          const link = await this.findOwnLink(row);
+          const roots = await this.secrets.get("pendingReplacement");
+          if (link && roots && roots.length === RESET_ROOTS_BYTES) await this.activateReplacement(row, roots, link.wire);
+        } catch (e) {
+          report.errors.push(syncError("resumeReplacement", e));
+        }
+      }
+    }
     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;
@@ -776,11 +896,23 @@ class ClientImpl implements Client {
       }
     } else if (meta.state !== "ACTIVE") return report;
     await this.ensureBackup();
+    if (meta.bootstrap && !meta.bootstrap.complete) {
+      try {
+        report.bootstrap = await this.bootstrap(report, meta.bootstrap);
+      } catch (e) {
+        report.errors.push(syncError("bootstrap", e));
+      }
+    }
     try {
       await this.syncMetadata(report);
     } catch (e) {
       report.errors.push(syncError("metadata", e));
     }
+    try {
+      await this.pushPreferences(report);
+    } catch (e) {
+      report.errors.push(syncError("preference", e));
+    }
     const after = await this.store.read((tx) => tx.get("meta", META));
     if (after?.state === "RETIRED") return report;
     try {
@@ -802,10 +934,8 @@ class ClientImpl implements Client {
     // Each stream on its own: a failed download or a refused record names its stream in the report
     // and leaves the other streams to be read; a stream that failed is not counted as synced.
     // One budget spans the streams; a stream it stops early reports hasMore.
-    const budget: ReadBudget = {
-      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)))
-    };
+    const budget: ReadBudget = this.syncBudget;
+    if (budget.remainingRecords < 1) budget.remainingRecords = 1; // every stream reads at least one page
     for (const s of subs) {
       try {
         const known = await this.store.read((tx) => tx.list("certificates").some(([, c]) => c.streamId === toHex(s.streamId)));
@@ -833,7 +963,16 @@ class ClientImpl implements Client {
     if (me) {
       const theirs = expectType<AccountDevice>(verifyDocument(me.certificate), DocumentType.AccountDevice, "sync");
       if (!equalBytes(theirs.accountKey, pin.accountKey)) {
-        // Our own key changed at the host: only a receipt we produced explains that; otherwise ignore.
+        // Our own key changed at the host. A succession from our identity, attested by an authority
+        // we trust, retires this device (its key is no longer the account's); a bare key change or a
+        // reset we did not make is ignored here, as before.
+        if (await this.supersededBySuccession(pin, me, report)) {
+          await this.retire();
+          // The key itself is retired, not only the device: nothing of it stays here.
+          await this.secrets.delete("accountSeed");
+          this.account = undefined;
+          return;
+        }
       } else if (!equalBytes(theirs.bodyHash, pin.certificateHash) && theirs.generation > pin.generation) {
         await this.retire();
         return;
@@ -856,7 +995,7 @@ class ClientImpl implements Client {
     // Unconfirmed writes of our own first: a successor snapshot the host never took, a vault update
     // it never saw. Until they land, peers read stale membership and a replacement phone a stale
     // preference.
-    const pendingOwned = await this.store.read((tx) => tx.list("circles").filter(([, r]) => r.pending && r.ownerIdentityId === toHex(pin.identityId)).map(([, r]) => fromHex(r.circleId)));
+    const pendingOwned = await this.store.read((tx) => tx.list("circles").filter(([, r]) => r.pending && r.ownerIdentityId === toHex(pin.accountId)).map(([, r]) => fromHex(r.circleId)));
     for (const circleId of pendingOwned) {
       try {
         if ((await this.publishPendingSnapshot(circleId)) === "COMMITTED") report.metadata.snapshots++;
@@ -874,15 +1013,15 @@ class ClientImpl implements Client {
     const unknownOwners: Uint8Array[] = [];
     for (const c of circles) {
       if (c.status === "closed" || c.status === "quarantined" || c.status === "left") continue;
-      if (!equalBytes(c.ownerIdentityId, pin.identityId) && !(await this.pinFor(c.ownerIdentityId))) unknownOwners.push(c.ownerIdentityId);
+      if (!equalBytes(c.ownerIdentityId, pin.accountId) && !(await this.pinFor(c.ownerIdentityId))) unknownOwners.push(c.ownerIdentityId);
     }
     if (unknownOwners.length > 0) {
-      for (const r of await this.transport.directory.resolveIdentities(unknownOwners)) await this.acceptMemberCertificate(r.certificate, r.resetReceipt, report);
+      for (const r of await this.transport.directory.resolveIdentities(unknownOwners)) await this.acceptMemberCertificate(r, report);
     }
     const memberIds = new Map<string, Uint8Array>();
     for (const c of circles) {
       if (c.status === "closed" || c.status === "quarantined" || c.status === "left") continue;
-      const ownerPin = equalBytes(c.ownerIdentityId, pin.identityId) ? pin : await this.pinFor(c.ownerIdentityId);
+      const ownerPin = equalBytes(c.ownerIdentityId, pin.accountId) ? pin : await this.pinFor(c.ownerIdentityId);
       if (!ownerPin) {
         memberIds.set(toHex(c.ownerIdentityId), c.ownerIdentityId);
         continue;
@@ -890,7 +1029,7 @@ class ClientImpl implements Client {
       const wire = await this.transport.directory.getCircle(c.circleId);
       if (wire) {
         try {
-          const r = acceptSnapshot(c, wire, ownerPin.accountKey, pin.identityId, now);
+          const r = await this.acceptSnapshotFrom(c, wire, ownerPin, now, report);
           if (r.outcome === "ACCEPTED") {
             // The row may have moved since it was read: a sharing preference, a leave or a close
             // made meanwhile wins over the fetched snapshot, and a newer snapshot already stored
@@ -920,46 +1059,299 @@ class ClientImpl implements Client {
           for (const m of c.members) memberIds.set(toHex(m), m);
         }
       } else for (const m of c.members) memberIds.set(toHex(m), m);
-      if (equalBytes(c.ownerIdentityId, pin.identityId) && c.status === "member") {
+      if (equalBytes(c.ownerIdentityId, pin.accountId) && c.status === "member") {
         const requests = await this.transport.directory.readRequests(c.circleId);
         const joins = requests.filter((r) => r.action === "join").map((r) => r.accountName);
         if (joins.length) this.emit({ kind: "joinRequests", circleId: c.circleId, accountNames: joins });
         for (const r of requests.filter((r) => r.action === "leave")) {
           const [acct] = await this.transport.directory.resolveAccounts([r.accountName]);
           if (!acct) continue;
-          const leaver = pinFromCertificate(expectType<AccountDevice>(verifyDocument(acct.certificate), DocumentType.AccountDevice));
           try {
-            await this.changeMembership(c.circleId, { remove: leaver.identityId });
+            await this.changeMembership(c.circleId, { remove: resolvedAccountId(acct) });
           } catch (e) {
             report.errors.push(syncError("removeLeaver", e));
           }
         }
       }
     }
-    memberIds.delete(toHex(pin.identityId));
+    memberIds.delete(toHex(pin.accountId));
     if (memberIds.size > 0) {
       const resolved = await this.transport.directory.resolveIdentities([...memberIds.values()]);
       const byIdentity = new Map<string, { accountName: string; accountKey: Uint8Array }>();
       for (const r of resolved) {
-        const doc = expectType<AccountDevice>(verifyDocument(r.certificate), DocumentType.AccountDevice, "sync");
-        const iid = toHex(pinFromCertificate(doc).identityId);
-        byIdentity.set(iid, { accountName: r.accountName, accountKey: r.accountKey });
-        await this.acceptMemberCertificate(r.certificate, r.resetReceipt, report);
+        expectType<AccountDevice>(verifyDocument(r.certificate), DocumentType.AccountDevice, "sync");
+        byIdentity.set(toHex(resolvedAccountId(r)), { accountName: r.accountName, accountKey: r.accountKey });
+        await this.acceptMemberCertificate(r, report);
       }
       checkMemberResolution(byIdentity);
     }
   }
 
-  private async pinFor(identityId: Uint8Array): Promise<AccountPin | undefined> {
-    const row = await this.store.read((tx) => tx.get("pins", toHex(identityId)));
+  /**
+   * Has the host's chain for our own account moved past our key? A valid succession from our
+   * current identity means an authority replaced this account's key; the device holding the old
+   * key has nothing left to say. Deferred (no fresh list, untrusted clock) and invalid
+   * attestations leave the device as it is.
+   */
+  private async supersededBySuccession(pin: AccountPin, me: ResolvedAccount, report: SyncReport): Promise<boolean> {
+    if (!me.successions?.length) return false;
+    try {
+      const r = await this.followChain({ accountId: pin.accountId, accountName: pin.accountName, current: pin, firstPage: me.successions, next: me.successionsNext, budget: this.syncBudget });
+      return r.pin !== undefined && !equalBytes(r.pin.identityId, pin.identityId);
+    } catch (e) {
+      // A chain this device cannot follow for its own account is a diagnostic the product must
+      // see: the host has already fenced the device, and only this report says why it still runs.
+      report.errors.push(syncError("ownSuccession", e));
+      return false;
+    }
+  }
+
+  /**
+   * Verify a snapshot under the owner's current key, or, when the owner's key changed through a
+   * succession and the snapshot predates it, under the retired key it was signed with. The
+   * successor republishes at the next revision; until then the older snapshot stays valid.
+   */
+  private async acceptSnapshotFrom(c: CircleState, wire: Uint8Array, ownerPin: AccountPin, now: bigint, report?: SyncReport, resolved = false): Promise<ReturnType<typeof acceptSnapshot>> {
+    const { pin } = this.requireAccount("sync");
+    // The very bytes this device already verified (a bootstrap snapshot under a key since retired)
+    // are a duplicate whatever key signed them; only new bytes are verified.
+    if (c.snapshot && equalBytes(c.snapshot, wire)) return { outcome: "DUPLICATE", state: c };
+    try {
+      return acceptSnapshot(c, wire, ownerPin.accountKey, pin.accountId, now);
+    } catch (e) {
+      if (!isKavachError(e, "BAD_SIGNATURE")) throw e;
+      // A retired key may only vouch for a circle this device holds at revision 0 (bootstrap, first
+      // contact): an established circle advances under the current owner key alone.
+      const ownerHex = toHex(ownerPin.accountId);
+      const retiredKeys = c.revision === 0n ? await this.store.read((tx) => tx.list("identities").flatMap(([, r]) => (r.accountId === ownerHex && r.retired && r.accountKey ? [fromHex(r.accountKey)] : []))) : [];
+      for (const key of retiredKeys) {
+        try {
+          return acceptSnapshot(c, wire, key, pin.accountId, now);
+        } catch (inner) {
+          if (!isKavachError(inner, "BAD_SIGNATURE")) throw inner;
+        }
+      }
+      // Signed by a key we do not know: the owner may have succeeded since we last resolved it.
+      // The chain is verified first; only a key it produced may sign this circle.
+      if (!resolved && report && !equalBytes(ownerPin.accountId, pin.accountId)) {
+        const [r] = await this.transport.directory.resolveIdentities([ownerPin.accountId]);
+        if (r && !equalBytes(r.accountKey, ownerPin.accountKey)) {
+          await this.acceptMemberCertificate(r, report);
+          const fresh = await this.pinFor(ownerPin.accountId);
+          if (fresh && !equalBytes(fresh.accountKey, ownerPin.accountKey)) return this.acceptSnapshotFrom(c, wire, fresh, now, report, true);
+        }
+      }
+      throw e;
+    }
+  }
+
+  private async pinFor(accountId: Uint8Array): Promise<AccountPin | undefined> {
+    const row = await this.store.read((tx) => tx.get("pins", toHex(accountId)));
     return row ? rowToPin(row) : undefined;
   }
 
-  /** Accept a member's certificate; a changed account key is quarantined unless a valid receipt explains it. */
-  private async acceptMemberCertificate(wire: Uint8Array, resetReceipt: Uint8Array | undefined, report: SyncReport): Promise<void> {
+  /**
+   * The one path every succession takes (section 4, "Chains"): the policy gate first, then the
+   * key list, then each link verified in order from the start identity (the pinned identity for
+   * an established contact, the account id at first contact or for a restoring device), page by
+   * page within the sync's budget, with the verified prefix persisted so that the next sync
+   * resumes instead of starting over. Only when the chain is complete does anything move: for a
+   * pinned contact every link is applied in one transaction, so no epoch is ever sealed to an
+   * intermediate successor; for a first contact or a restore the verified links are returned and
+   * the caller records them with the pin or the header. Any failure leaves the pin where it was.
+   */
+  private async followChain(input: { accountId: Uint8Array; accountName: string; current?: AccountPin; finalIdentityId?: Uint8Array; untilGeneration?: bigint; firstPage: readonly SuccessionLink[]; next: bigint | undefined; budget?: ReadBudget | undefined }): Promise<{ pin: AccountPin | undefined; verified: VerifiedLink[]; accepted: SuccessionEffect[] }> {
+    const stage = "chain";
+    if (!acceptsSuccession(this.policy)) throw new KavachError("UNSUPPORTED_TYPE", stage, "this deployment does not accept successions");
+    const accountHex = toHex(input.accountId);
+    const startIdentity = input.current?.identityId ?? input.accountId;
+    await this.ensureResetList();
+    // The state the chain is validated against: the pin with what this store retired, or the root.
+    const current = input.current;
+    let state = current ? await this.store.read((tx) => pinnedState(tx, current, this.trust)) : rootState(input.accountId, input.accountName, this.trust);
+    // Reconcile first: the host serves the chain from the root, and a pinned contact already holds
+    // a prefix of it. Links whose transition is on record are dropped (the same transition at a
+    // recorded state; a different one is the authority signing two successors), so verification
+    // starts at the pinned identity with only the transitions this device has not seen.
+    const recorded = current ? await this.store.read((tx) => tx.list("successions", accountHex + ":").map(([, r]) => r)) : [];
+    // The bound, applied to every page alike: links past `untilGeneration` are not this call's to
+    // follow (a replacing device stops at the state its own succession left from).
+    const within = (l: SuccessionLink): boolean => input.untilGeneration === undefined || expectType<AccountSuccession>(parseDocument(l.wire), DocumentType.AccountSuccession, stage).newGeneration <= input.untilGeneration;
+    const unseen = (links: readonly SuccessionLink[]): SuccessionLink[] =>
+      links.filter(within).filter((l) => {
+        const doc = expectType<AccountSuccession>(parseDocument(l.wire), DocumentType.AccountSuccession, stage);
+        const t = transitionOf(doc);
+        const row = recorded.find((r) => unbig(r.previousGeneration) === t.previousGeneration && r.previousIdentityId === t.previousIdentityId);
+        if (!row) return true;
+        if (!sameTransition({ accountName: row.accountName, accountId: row.accountId, successionId: row.successionId, previousIdentityId: row.previousIdentityId, newIdentityId: row.newIdentityId, previousGeneration: unbig(row.previousGeneration), newGeneration: unbig(row.newGeneration), newCertificateHash: row.newCertificateHash }, t)) {
+          // A different transition at a recorded state is evidence against the authority only if
+          // the authority signed it: unauthenticated bytes are a bad signature, nothing more.
+          authenticateSuccession(l.wire, this.trust, this.now());
+          throw new KavachError("EQUIVOCATION", stage, "two successors for one account state");
+        }
+        return false;
+      });
+    const progress = await this.store.read((tx) => tx.get("chainProgress", accountHex));
+    const verified: VerifiedLink[] = [];
+    let cursor: bigint | undefined;
+    let pending: readonly SuccessionLink[];
+    // Only links this device has not recorded are verified, and only they count against the budget.
+    const verifyMore = (links: readonly SuccessionLink[]): void => {
+      const fresh = unseen(links);
+      const r = verifyChain(fresh, { state, trust: this.trust, now: this.now() });
+      verified.push(...r.links);
+      state = r.state;
+      if (input.budget) input.budget.remainingRecords -= fresh.length;
+    };
+    if (progress && progress.startIdentityId === toHex(startIdentity)) {
+      // Resume at the saved cursor, however long the verified prefix is. The prefix's transitions
+      // were verified when their attestations were allowed, so they are replayed through the
+      // transition rules alone; their bytes are authenticated again below, and refreshed from the
+      // host where a key rotation since made them stale.
+      for (const l of progress.links) {
+        const doc = expectType<AccountSuccession>(parseDocument(fromHex(l.wire)), DocumentType.AccountSuccession, stage);
+        state = validateTransition(doc, fromHex(l.certificate), state).next;
+        verified.push({ doc, wire: fromHex(l.wire), certificate: fromHex(l.certificate) });
+      }
+      cursor = unbig(progress.nextGeneration);
+      pending = [];
+    } else {
+      pending = input.firstPage;
+      cursor = input.next;
+    }
+    const persist = (): Promise<void> =>
+      this.store.transaction((tx) => {
+        if (cursor === undefined) tx.delete("chainProgress", accountHex);
+        else tx.put("chainProgress", accountHex, { accountId: accountHex, startIdentityId: toHex(startIdentity), links: verified.map((v) => ({ wire: toHex(v.wire), certificate: toHex(v.certificate) })), nextGeneration: big(cursor), complete: false });
+      });
+    const reached = (): boolean => input.untilGeneration !== undefined && state.generation >= input.untilGeneration;
+    verifyMore(pending);
+    if (reached()) cursor = undefined;
+    while (cursor !== undefined) {
+      if (input.budget && (input.budget.remainingRecords <= 0 || this.now() >= input.budget.deadline)) {
+        await persist();
+        throw new KavachError("METADATA_REQUIRED", stage, "the chain continues past this sync's budget");
+      }
+      let page;
+      try {
+        page = await this.transport.directory.getSuccessions(input.accountId, cursor, 32);
+      } catch (e) {
+        await persist();
+        throw e;
+      }
+      if (page.successions.length === 0) {
+        await persist();
+        throw new KavachError("METADATA_REQUIRED", stage, "the host did not finish serving the chain");
+      }
+      verifyMore(page.successions);
+      cursor = reached() ? undefined : page.nextGeneration;
+      if (cursor !== undefined) await persist();
+    }
+    if (input.finalIdentityId && state.identityId !== toHex(input.finalIdentityId)) throw new KavachError("SUCCESSION_BINDING", stage, "the chain does not end at the served key");
+    // Every attestation under the current list before anything is recorded. A link whose signer
+    // left the list since it was verified is fetched again: the host re-attests a legitimate
+    // transition under a current key, and the transition must be the same one.
+    for (let i = 0; i < verified.length; i++) {
+      const link = verified[i];
+      if (!link) continue;
+      try {
+        authenticateSuccession(link.wire, this.trust, this.now());
+      } catch (e) {
+        if (!isKavachError(e, "RESET_KEY_REVOKED")) throw e;
+        const page = await this.transport.directory.getSuccessions(input.accountId, link.doc.newGeneration - 1n, 1);
+        const again = page.successions[0];
+        if (!again) throw e;
+        const doc = authenticateSuccession(again.wire, this.trust, this.now());
+        if (!sameTransition(transitionOf(doc), transitionOf(link.doc)) || !equalBytes(again.certificate, link.certificate)) throw new KavachError("EQUIVOCATION", stage, "the re-attested link is a different transition");
+        verified[i] = { doc, wire: again.wire, certificate: link.certificate };
+      }
+    }
+    if (!current) {
+      if (progress) await this.store.transaction((tx) => tx.delete("chainProgress", accountHex));
+      return { pin: undefined, verified, accepted: [] };
+    }
+    const applied = await this.store.transaction((tx) => {
+      const effects: SuccessionEffect[] = [];
+      let pin = current;
+      for (const link of verified) {
+        // A link behind the pinned key that is already on record: the pin moved past it earlier.
+        if (link.doc.previousGeneration < pin.generation && tx.list("successions").some(([, s]) => s.accountId === accountHex && unbig(s.previousGeneration) === link.doc.previousGeneration)) continue;
+        const e = applySuccession(tx, { wire: link.wire, newCertificate: link.certificate, policy: this.policy, trust: this.trust, now: this.now() });
+        effects.push(e);
+        pin = e.pin;
+      }
+      this.persistTrustIn(tx);
+      tx.delete("chainProgress", accountHex);
+      return { effects, pin };
+    });
+    return { pin: applied.pin, verified, accepted: applied.effects };
+  }
+
+  /** The report side of an applied chain: counters and events for every accepted link. */
+  private reportAccepted(accepted: readonly SuccessionEffect[], report: SyncReport): void {
+    for (const effect of accepted) {
+      if (effect.outcome !== "ACCEPTED") continue;
+      report.metadata.successions++;
+      report.metadata.rotations++;
+      this.emit({ kind: "accountKeyChanged", accountName: effect.accountName, quarantined: false });
+      this.emit({ kind: "deviceChanged", identityId: effect.pin.accountId, generation: effect.pin.generation });
+    }
+  }
+
+  private securityCodeOf(e: unknown): ErrorCode | undefined {
+    return e instanceof KavachError && (e.code === "EQUIVOCATION" || e.code === "ROLLBACK" || e.code === "SUCCESSION_BINDING" || e.code === "DEVICE_ID_REUSED" || e.code === "SUPERSEDED_IDENTITY") ? e.code : undefined;
+  }
+
+  /** Accept a member's certificate; a changed account key is quarantined unless a succession chain or a reset receipt explains it. */
+  private async acceptMemberCertificate(resolved: ResolvedAccount, report: SyncReport): Promise<void> {
+    const wire = resolved.certificate;
+    const resetReceipt = resolved.resetReceipt;
     const doc = expectType<AccountDevice>(verifyDocument(wire), DocumentType.AccountDevice, "sync");
     const existing = await this.store.read((tx) => tx.list("pins").find(([, p]) => p.accountName === doc.accountName)?.[1]);
-    const current = existing ? rowToPin(existing) : undefined;
+    let current = existing ? rowToPin(existing) : undefined;
+    const accountId = current?.accountId ?? resolvedAccountId(resolved);
+    const chain = resolved.successions ?? [];
+    // A served chain is followed whenever there is one, even when the served key equals the pinned
+    // one: a certificate under a retired key at a higher generation must be refused as a return to
+    // that identity, never accepted as a plain device change. Links already on record cost nothing.
+    if (current && chain.length > 0) {
+      try {
+        const r = await this.followChain({ accountId, accountName: doc.accountName, current, firstPage: chain, next: resolved.successionsNext, budget: this.syncBudget });
+        this.reportAccepted(r.accepted, report);
+        current = r.pin;
+      } catch (e) {
+        report.errors.push(syncError("succession", e));
+        // A deployment that refuses successions quarantines the key change below, as a bare
+        // directory key change. Anything else leaves the pin where it was until the next sync.
+        if (!isKavachError(e, "UNSUPPORTED_TYPE")) {
+          const code = this.securityCodeOf(e);
+          if (code) this.emit({ kind: "securityError", code, detail: doc.accountName });
+          return;
+        }
+      }
+      if (!current) return;
+    }
+    let verified: VerifiedLink[] = [];
+    if (!current && chain.length > 0) {
+      // A first contact with an account that went through successions: the chain is verified from
+      // the root to the served key before any pin is written, under the same policy gate as for an
+      // established contact. A deployment that refuses successions pins nothing and quarantines.
+      try {
+        verified = (await this.followChain({ accountId, accountName: doc.accountName, finalIdentityId: pinFromCertificate(doc).identityId, firstPage: chain, next: resolved.successionsNext, budget: this.syncBudget })).verified;
+      } catch (e) {
+        report.errors.push(syncError("succession", e));
+        if (isKavachError(e, "UNSUPPORTED_TYPE")) {
+          const already = await this.store.read((tx) => tx.get("quarantine", doc.accountName));
+          await this.store.transaction((tx) => tx.put("quarantine", doc.accountName, { accountName: doc.accountName, certificate: toHex(wire), reason: "succession refused", at: big(this.now()) }));
+          report.metadata.quarantined++;
+          if (!already) this.emit({ kind: "accountKeyChanged", accountName: doc.accountName, quarantined: true });
+        } else {
+          const code = this.securityCodeOf(e);
+          if (code) this.emit({ kind: "securityError", code, detail: doc.accountName });
+        }
+        return;
+      }
+    }
     let outcome;
     try {
       outcome = acceptCertificate(current, wire);
@@ -976,21 +1368,30 @@ class ClientImpl implements Client {
       throw e;
     }
     if (outcome.outcome === "DUPLICATE") return;
-    const p = outcome.pin;
+    const p = current ? outcome.pin : { ...outcome.pin, accountId };
     await this.store.transaction((tx) => {
-      tx.put("pins", toHex(p.identityId), pinToRow(p));
+      tx.put("pins", toHex(p.accountId), pinToRow(p));
+      if (verified.length) {
+        recordChainIn(tx, verified, this.now());
+        rootIdentityIn(tx, p.accountId, p.accountName, resolved.rootCertificate);
+      }
+      if (!tx.get("identities", toHex(p.identityId))) {
+        const last = resolved.successions?.at(-1);
+        const since = last ? expectType<AccountSuccession>(parseDocument(last.wire), DocumentType.AccountSuccession, "sync").newGeneration : 1n;
+        tx.put("identities", toHex(p.identityId), { accountId: toHex(p.accountId), accountName: p.accountName, accountKey: toHex(p.accountKey), sinceGeneration: big(since), retired: false });
+      }
       if (outcome.previous) {
         const old = tx.get("certificates", toHex(outcome.previous.certificateHash));
         if (old) tx.put("certificates", toHex(outcome.previous.certificateHash), { ...old, current: false });
       }
-      tx.put("certificates", toHex(p.certificateHash), { identityId: toHex(p.identityId), certificateHash: toHex(p.certificateHash), signingKey: toHex(p.signingKey), boxKey: toHex(p.boxKey), streamId: toHex(p.streamId), generation: big(p.generation), wire: toHex(p.certificate), current: true });
+      tx.put("certificates", toHex(p.certificateHash), { identityId: toHex(p.accountId), certificateHash: toHex(p.certificateHash), signingKey: toHex(p.signingKey), boxKey: toHex(p.boxKey), streamId: toHex(p.streamId), generation: big(p.generation), wire: toHex(p.certificate), current: true });
       if (outcome.rotate) {
-        const ch = t3ApplyChange(tx, { kind: "deviceChanged", identityId: p.identityId, certificateHash: p.certificateHash });
+        const ch = t3ApplyChange(tx, { kind: "deviceChanged", identityId: p.accountId, certificateHash: p.certificateHash });
         if (ch.changed) report.metadata.rotations++;
       }
     });
     report.metadata.certificates++;
-    if (outcome.rotate) this.emit({ kind: "deviceChanged", identityId: p.identityId, generation: p.generation });
+    if (outcome.rotate) this.emit({ kind: "deviceChanged", identityId: p.accountId, generation: p.generation });
   }
 
   private async onKeyChanged(current: AccountPin, wire: Uint8Array, receipt: Uint8Array | undefined, report: SyncReport): Promise<void> {
@@ -1025,17 +1426,21 @@ class ClientImpl implements Client {
 
   /** Peers on a validated reset: stop sharing to the old identity, close its circles, rotate. */
   private applyResetIn(tx: Tx, old: AccountPin, newIdentityId: Uint8Array): void {
-    tx.delete("pins", toHex(old.identityId));
+    const accountHex = toHex(old.accountId);
+    tx.delete("pins", accountHex);
     tx.delete("quarantine", old.accountName);
-    for (const [k, c] of tx.list("certificates")) if (c.identityId === toHex(old.identityId)) tx.put("certificates", k, { ...c, current: false });
+    for (const [k, c] of tx.list("certificates")) if (c.identityId === accountHex) tx.put("certificates", k, { ...c, current: false });
+    // Every identity of the chain is retired; the root remembers the reset, so no successor of
+    // the old account is ever a recipient again.
+    for (const [k, r] of tx.list("identities")) if (r.accountId === accountHex) tx.put("identities", k, k === accountHex ? { ...r, retired: true, resetAt: big(this.now()) } : { ...r, retired: true });
     for (const [k, c] of tx.list("circles")) {
-      if (c.ownerIdentityId === toHex(old.identityId)) {
+      if (c.ownerIdentityId === accountHex) {
         t3Circle(tx, { ...c, status: "closed" }, { kind: "leave", circleId: fromHex(k) });
-      } else if (c.members.includes(toHex(old.identityId))) {
-        t3ApplyChange(tx, { kind: "deviceChanged", identityId: old.identityId, certificateHash: newIdentityId });
+      } else if (c.members.includes(accountHex)) {
+        t3ApplyChange(tx, { kind: "deviceChanged", identityId: old.accountId, certificateHash: newIdentityId });
       }
     }
-    forgetAuthorIn(tx, old.identityId);
+    forgetAuthorIn(tx, old.accountId);
   }
 
   private persistTrustIn(tx: Tx): void {
@@ -1056,12 +1461,13 @@ class ClientImpl implements Client {
     const { pin } = this.requireAccount("left");
     const others = await this.store.read((tx) => tx.list("circles").filter(([, x]) => x.circleId !== toHex(c.circleId) && x.status === "member").flatMap(([, x]) => x.members));
     for (const m of c.members) {
-      if (equalBytes(m, pin.identityId) || others.includes(toHex(m))) continue;
+      if (equalBytes(m, pin.accountId) || others.includes(toHex(m))) continue;
       await forgetAuthor(this.store, m);
     }
   }
 
   private async retire(): Promise<void> {
+    this.retired = true;
     await this.store.transaction((tx) => {
       const meta = tx.get("meta", META);
       if (meta) tx.put("meta", META, { ...meta, state: "RETIRED" });
@@ -1094,12 +1500,36 @@ class ClientImpl implements Client {
     return newestSlot(this.store, identityId, kind, this.now());
   }
 
+  keyChanges(options: { accountId?: Uint8Array; limit?: number } = {}): Promise<KeyChangeEntry[]> {
+    const limit = Math.max(1, Math.min(500, Math.floor(options.limit ?? 50)));
+    const who = options.accountId ? toHex(options.accountId) : undefined;
+    return this.store.read((tx) =>
+      tx
+        .list("keyChanges")
+        .map(([, r]) => r)
+        .filter((r) => who === undefined || r.accountId === who)
+        // Newest first; two changes accepted in one transaction order by generation.
+        .sort((x, y) => (unbig(y.acceptedAt) > unbig(x.acceptedAt) ? 1 : unbig(y.acceptedAt) < unbig(x.acceptedAt) ? -1 : unbig(y.generation) > unbig(x.generation) ? 1 : unbig(y.generation) < unbig(x.generation) ? -1 : 0))
+        .slice(0, limit)
+        .map((r) => ({
+          accountId: fromHex(r.accountId),
+          accountName: r.accountName,
+          previousIdentityId: fromHex(r.previousIdentityId),
+          newIdentityId: fromHex(r.newIdentityId),
+          generation: unbig(r.generation),
+          reason: r.reason,
+          successionId: r.successionId === undefined ? undefined : fromHex(r.successionId),
+          acceptedAt: unbig(r.acceptedAt)
+        }))
+    );
+  }
+
 
 
   // Circles ---------------------------------------------------------------------------------------
 
   private async listCircles(): Promise<CircleSummary[]> {
-    const self = this.selfPin?.identityId;
+    const self = this.selfPin?.accountId;
     const now = this.now();
     return this.store.read((tx) =>
       tx.list("circles").map(([, r]) => {
@@ -1117,6 +1547,7 @@ class ClientImpl implements Client {
    * the state, so a change that landed in the rows reaches the vault however the process dies.
    */
   private async syncVault(): Promise<void> {
+    if (!this.vaultEnabled) return;
     const { account, pin } = this.requireAccount("vault");
     const recoveryKey = await this.secrets.get("recoveryKey");
     const accountSeed = await this.secrets.get("accountSeed");
@@ -1195,10 +1626,13 @@ class ClientImpl implements Client {
   private async createCircle(): Promise<{ circleId: Uint8Array }> {
     const { account, pin } = this.requireAccount("createCircle");
     const circleId = newCircleId();
-    const genesis = createCircleSnapshot({ identityId: pin.identityId, accountSecretKey: account.account.secretKey }, circleId);
-    const state = acceptSnapshot(pinCircle(circleId, pin.identityId, true, "member"), genesis, pin.accountKey, pin.identityId, this.now());
+    const genesis = createCircleSnapshot({ identityId: pin.accountId, accountSecretKey: account.account.secretKey }, circleId);
+    const state = acceptSnapshot(pinCircle(circleId, pin.accountId, true, "member"), genesis, pin.accountKey, pin.accountId, this.now());
     if (state.outcome !== "ACCEPTED") throw new KavachError("STORAGE_FAILURE", "createCircle");
-    await this.store.transaction((tx) => t3Circle(tx, { ...circleToRow(state.state), pending: { snapshot: toHex(genesis), revision: "1" } }));
+    await this.store.transaction((tx) => {
+      t3Circle(tx, { ...circleToRow(state.state), pending: { snapshot: toHex(genesis), revision: "1" } });
+      this.recordPreferenceIn(tx, circleId, true);
+    });
     const published = await this.publishPendingSnapshot(circleId);
     if (published !== "COMMITTED") throw new KavachError("STORAGE_FAILURE", "createCircle", published);
     await this.store.transaction((tx) => {
@@ -1206,6 +1640,7 @@ class ClientImpl implements Client {
       t9MarkVault(tx);
     });
     await this.syncVault();
+    await this.pushPreferencesQuietly();
     this.emit({ kind: "circleChanged", circleId, revision: 1n, status: "member" });
     return { circleId };
   }
@@ -1214,6 +1649,7 @@ class ClientImpl implements Client {
     this.requireAccount("requestJoin");
     await this.store.transaction((tx) => {
       const existing = tx.get("circles", toHex(circleId));
+      if (!existing || existing.status === "left") this.recordPreferenceIn(tx, circleId, shareOnApproval);
       if (!existing) t3Circle(tx, circleToRow(pinCircle(circleId, ownerIdentityId, shareOnApproval, "requested")));
       else if (existing.status === "left") {
         // An explicit rejoin: the pinned owner and the revision reached stay, so no older snapshot
@@ -1226,17 +1662,28 @@ class ClientImpl implements Client {
     await this.syncVault();
     const outcome = await this.transport.directory.requestJoin(circleId);
     if (outcome.status !== "COMMITTED" && outcome.status !== "ALREADY_COMMITTED") throw new KavachError("STORAGE_FAILURE", "requestJoin", outcome.status);
+    await this.pushPreferencesQuietly();
+  }
+
+  /** The host's copy of a preference, best effort now and by sync later. */
+  private async pushPreferencesQuietly(): Promise<void> {
+    if (!acceptsSuccession(this.policy)) return;
+    try {
+      await this.pushPreferences();
+    } catch {
+      /* retried by sync */
+    }
   }
 
   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 }, 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: [] };
-    await this.acceptMemberCertificate(resolved.certificate, resolved.resetReceipt, report);
-    const requester = pinFromCertificate(expectType<AccountDevice>(verifyDocument(resolved.certificate), DocumentType.AccountDevice));
-    const pinned = await this.pinFor(requester.identityId);
-    if (!pinned) throw new KavachError("ACCOUNT_KEY_CHANGED", "approve", "requester's key is quarantined");
-    return this.changeMembership(circleId, { admit: requester.identityId });
+    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: [] };
+    await this.acceptMemberCertificate(resolved, report);
+    const requester = resolvedAccountId(resolved);
+    const pinned = await this.pinFor(requester);
+    if (!pinned || !equalBytes(pinned.certificateHash, expectType<AccountDevice>(verifyDocument(resolved.certificate), DocumentType.AccountDevice).bodyHash)) throw new KavachError("ACCOUNT_KEY_CHANGED", "approve", "requester's key is quarantined");
+    return this.changeMembership(circleId, { admit: requester });
   }
 
   private async changeMembership(circleId: Uint8Array, change: { admit: Uint8Array } | { remove: Uint8Array } | { close: true }): Promise<{ revision: bigint }> {
@@ -1251,7 +1698,7 @@ class ClientImpl implements Client {
       }
       const state = rowToCircle(row);
       if (state.status === "closed") return { revision: state.revision };
-      const successor = successorSnapshot(state, change, { identityId: pin.identityId, accountSecretKey: account.account.secretKey });
+      const successor = successorSnapshot(state, change, { identityId: pin.accountId, accountSecretKey: account.account.secretKey });
       if (!successor) {
         if (!("close" in change)) return { revision: state.revision };
         // Nobody but the owner to tell: the close is local, and the vault entry goes with it.
@@ -1289,7 +1736,7 @@ class ClientImpl implements Client {
     const expectedRevision = unbig(pending.revision) - 1n;
     const outcome = await this.transport.directory.publishOwnedCircle({ circleId, expectedRevision, expectedHash: expectedRevision === state.revision ? state.bodyHash : undefined, newSnapshot: successor });
     if (outcome.status === "COMMITTED" || outcome.status === "ALREADY_COMMITTED") {
-      const accepted = acceptSnapshot(state, successor, pin.accountKey, pin.identityId, this.now());
+      const accepted = acceptSnapshot(state, successor, pin.accountKey, pin.accountId, this.now());
       if (accepted.outcome !== "ACCEPTED" && accepted.outcome !== "DUPLICATE") throw new KavachError("STORAGE_FAILURE", stage, "the successor was refused locally");
       let next = pending.close ? { ...accepted.state, status: "closed" as const } : accepted.state;
       await this.store.transaction((tx) => {
@@ -1301,7 +1748,7 @@ class ClientImpl implements Client {
       });
       const after = new Set(next.members.map(toHex));
       for (const m of state.members) {
-        if (after.has(toHex(m)) || equalBytes(m, pin.identityId)) continue;
+        if (after.has(toHex(m)) || equalBytes(m, pin.accountId)) continue;
         const stillElsewhere = await this.store.read((tx) => tx.list("circles").some(([, c]) => c.circleId !== toHex(circleId) && c.status === "member" && c.members.includes(toHex(m))));
         if (!stillElsewhere) await forgetAuthor(this.store, m);
       }
@@ -1310,7 +1757,7 @@ class ClientImpl implements Client {
       return "COMMITTED";
     }
     if (outcome.status === "CONFLICT" && outcome.current) {
-      const accepted = acceptSnapshot(state, outcome.current, pin.accountKey, pin.identityId, this.now());
+      const accepted = acceptSnapshot(state, outcome.current, pin.accountKey, pin.accountId, this.now());
       await this.store.transaction((tx) => t3Circle(tx, { ...circleToRow(accepted.outcome === "ACCEPTED" ? accepted.state : state), pending: undefined }));
       return "CONFLICT";
     }
@@ -1321,7 +1768,7 @@ class ClientImpl implements Client {
     const { pin } = this.requireAccount("leave");
     const row = await this.store.read((tx) => tx.get("circles", toHex(circleId)));
     if (!row) return;
-    if (row.ownerIdentityId === toHex(pin.identityId)) throw new KavachError("NOT_AUTHORIZED", "leave", "the owner closes instead");
+    if (row.ownerIdentityId === toHex(pin.accountId)) throw new KavachError("NOT_AUTHORIZED", "leave", "the owner closes instead");
     const state = rowToCircle(row);
     await this.store.transaction((tx) => {
       t3Circle(tx, circleToRow({ ...state, enabled: false, status: "left" }), { kind: "leave", circleId });
@@ -1341,8 +1788,57 @@ class ClientImpl implements Client {
     }
     await this.store.transaction((tx) => {
       t3Circle(tx, { ...row, enabled }, { kind: enabled ? "enable" : "disable", circleId });
+      this.recordPreferenceIn(tx, circleId, enabled);
     });
     await this.syncVault();
+    await this.pushPreferencesQuietly();
+  }
+
+  /** The user's latest action on a circle's preference, with the local sequence that a host response must name to clear it. */
+  private recordPreferenceIn(tx: Tx, circleId: Uint8Array, enabled: boolean): void {
+    const key = toHex(circleId);
+    const row = tx.get("preferences", key) ?? { circleId: key, enabled, revision: "0", pending: undefined, nextSequence: "1" };
+    const sequence = row.nextSequence;
+    tx.put("preferences", key, { ...row, enabled, pending: { enabled, sequence }, nextSequence: big(unbig(sequence) + 1n) });
+  }
+
+  /**
+   * Send pending preference changes to the host (amendment A1, section 7). On CONFLICT the
+   * device's latest persisted action wins, read from the store at retry time, and is written again
+   * at the served revision; a response clears only the sequence it answered.
+   */
+  private async pushPreferences(report?: SyncReport): Promise<void> {
+    if (!acceptsSuccession(this.policy) || !this.selfPin) return;
+    const pending = await this.store.read((tx) => tx.list("preferences").filter(([, p]) => p.pending !== undefined).map(([, p]) => p.circleId));
+    for (const key of pending) {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const row = await this.store.read((tx) => tx.get("preferences", key));
+        if (!row?.pending) break;
+        const sent = row.pending;
+        const outcome = await this.transport.directory.setSharingPreference(fromHex(key), sent.enabled, unbig(row.revision));
+        if (outcome.status === "COMMITTED" || outcome.status === "ALREADY_COMMITTED") {
+          await this.store.transaction((tx) => {
+            const live = tx.get("preferences", key);
+            if (!live) return;
+            const cleared = live.pending?.sequence === sent.sequence ? undefined : live.pending;
+            // A late success for an older request never moves the revision back.
+            const revision = outcome.revision > unbig(live.revision) ? big(outcome.revision) : live.revision;
+            tx.put("preferences", key, { ...live, revision, pending: cleared });
+          });
+          break;
+        }
+        if (outcome.status === "CONFLICT") {
+          // Adopt the served revision; the latest persisted action is re-sent against it.
+          await this.store.transaction((tx) => {
+            const live = tx.get("preferences", key);
+            if (live) tx.put("preferences", key, { ...live, revision: big(outcome.revision) });
+          });
+          continue;
+        }
+        if (report) report.errors.push({ operation: "preference", code: outcome.status === "UNAUTHORIZED" ? "NOT_AUTHORIZED" : "NETWORK", stage: "preference", retryable: outcome.status !== "UNAUTHORIZED" });
+        break;
+      }
+    }
   }
 
   /** Close: the successor names only the owner; its publication forgets the members and removes the vault entry. */
@@ -1350,6 +1846,301 @@ class ClientImpl implements Client {
     await this.changeMembership(circleId, { close: true });
   }
 
+  // Account recovery (amendment A1) ---------------------------------------------------------------
+
+  async prepareReplacement(): 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);
+    if (opened.kind !== "fresh") throw new KavachError("MALFORMED", stage, "an account already exists on this device");
+    const existing = await this.store.read((tx) => tx.get("replacement", "pending"));
+    const roots = await this.secrets.get("pendingReplacement");
+    if (existing && !existing.stale && roots && roots.length === RESET_ROOTS_BYTES) return proposalOf(existing);
+    const [resolved] = await this.transport.directory.resolveAccounts([this.accountName]);
+    if (!resolved) throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, "unknown account");
+    const current = expectType<AccountDevice>(verifyDocument(resolved.certificate), DocumentType.AccountDevice, stage);
+    const accountId = resolvedAccountId(resolved);
+    // Fresh roots: nothing from the old device, nothing from the host. The certificate is at the
+    // next generation under the new key; the vault is fresh at revision 1 so that identity
+    // continuity works on the next replacement.
+    const accountSeed = newAccountSeed();
+    const device = newDevice();
+    const recoveryKey = newRecoveryKey();
+    const instanceId = randomBytes(16);
+    const successionId = randomBytes(16);
+    const account = openAccount(this.accountName, accountSeed, accountId);
+    const generation = current.generation + 1n;
+    const certificate = certify(account, device, generation);
+    const pin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice, stage), undefined, accountId);
+    const vault = this.vaultEnabled ? buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: 1n }, { accountSeed, lastDeviceGeneration: generation, lastCertificateHash: pin.certificateHash, entries: [] }, recoveryKey) : undefined;
+    // T11: roots in the secret store, the exact bytes in the store, before anything is sent.
+    await this.secrets.set("pendingReplacement", concat(accountSeed, device.deviceSeed, recoveryKey, instanceId, device.deviceId));
+    const row: ReplacementRow = {
+      successionId: toHex(successionId),
+      accountName: this.accountName,
+      accountId: toHex(accountId),
+      expectedCertificateHash: toHex(current.bodyHash),
+      expectedGeneration: big(current.generation),
+      certificate: toHex(certificate),
+      vault: vault ? toHex(vault.wire) : undefined,
+      vaultHash: vault ? toHex(vault.hash) : undefined,
+      deviceId: toHex(device.deviceId),
+      stale: false,
+      conflictGeneration: undefined
+    };
+    await this.store.transaction((tx) => tx.put("replacement", "pending", row));
+    await this.emitState();
+    return proposalOf(row);
+  }
+
+  async completeReplacement(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 };
+    const row = await this.store.read((tx) => tx.get("replacement", "pending"));
+    if (!row || row.successionId !== toHex(input.successionId)) throw new KavachError("MALFORMED", stage, "no such prepared replacement on this device");
+    if (row.stale) throw new KavachError("REPLACEMENT_CONFLICT", stage, row.conflictGeneration === undefined ? "the account moved" : `the account is at generation ${row.conflictGeneration}`);
+    const roots = await this.secrets.get("pendingReplacement");
+    if (!roots || roots.length !== RESET_ROOTS_BYTES) throw new KavachError("RECOVERY_REQUIRED", stage, "replacement prepared without its roots");
+    let outcome: Awaited<ReturnType<Directory["succeedAccount"]>>;
+    try {
+      outcome = await this.transport.directory.succeedAccount({
+        accountName: this.accountName,
+        expectedCertificateHash: fromHex(row.expectedCertificateHash),
+        newCertificate: fromHex(row.certificate),
+        newVault: row.vault === undefined ? undefined : fromHex(row.vault),
+        successionId: input.successionId,
+        authorization: input.authorization
+      });
+    } catch (e) {
+      if (!isKavachError(e, "NETWORK")) throw e;
+      // Unknown: the chain says whether ours committed. Never a second identity.
+      const link = await this.findOwnLink(row).catch(() => undefined);
+      if (!link) throw new KavachError("SUCCESSION_PENDING", stage, "the commit's outcome is unknown; call again with the same proposal");
+      outcome = { status: "COMMITTED", succession: link.wire };
+    }
+    if (outcome.status === "CONFLICT") {
+      // Definitive: the current certificate moved under the proposal, and the succession id is
+      // not on the chain (that answers first). The proposal can never commit: it is marked stale
+      // and its keys, never activated anywhere, are discarded.
+      let current: bigint | undefined;
+      try {
+        current = outcome.current ? expectType<AccountDevice>(verifyDocument(outcome.current), DocumentType.AccountDevice, stage).generation : undefined;
+      } catch {
+        current = undefined;
+      }
+      await this.store.transaction((tx) => tx.put("replacement", "pending", { ...row, stale: true, conflictGeneration: current === undefined ? undefined : big(current) }));
+      await this.secrets.delete("pendingReplacement");
+      await this.emitState();
+      throw new KavachError("REPLACEMENT_CONFLICT", stage, current === undefined ? "the account moved" : `the account is at generation ${current}`);
+    }
+    if (outcome.status === "UNAUTHORIZED") throw new KavachError("AUTHORIZATION_REQUIRED", stage, "the host refused the authorization; obtain a fresh one for the same proposal");
+    if ((outcome.status !== "COMMITTED" && outcome.status !== "ALREADY_COMMITTED") || !outcome.succession) {
+      throw new KavachError("SUCCESSION_PENDING", stage, `host answered ${outcome.status}`);
+    }
+    return this.activateReplacement(row, roots, outcome.succession);
+  }
+
+  /** Our own link on the host's chain, if the proposal committed: the one naming our succession id and certificate. */
+  private async findOwnLink(row: ReplacementRow): Promise<SuccessionLink | undefined> {
+    const page = await this.transport.directory.getSuccessions(fromHex(row.accountId), unbig(row.expectedGeneration), 8);
+    for (const l of page.successions) {
+      try {
+        const doc = expectType<AccountSuccession>(parseDocument(l.wire), DocumentType.AccountSuccession, "resume");
+        if (toHex(doc.successionId) === row.successionId && equalBytes(l.certificate, fromHex(row.certificate))) return l;
+      } catch {
+        /* not ours */
+      }
+    }
+    return undefined;
+  }
+
+  /** The reset-key list, fetched when the one held is not fresh. */
+  private async ensureResetList(): Promise<void> {
+    const now = this.now();
+    if (this.trust.fresh(now)) return;
+    const wire = await this.transport.directory.getResetKeyList();
+    if (!wire) return;
+    this.trust.install(wire, now);
+    await this.persistTrust();
+  }
+
+  /**
+   * Activate: verify the returned succession exactly as a peer would, against the previous state
+   * pinned from the host, then the T1 header under the new identity with the account id carried
+   * from the proposal. A succession that does not verify leaves the proposal intact.
+   */
+  private async activateReplacement(row: ReplacementRow, roots: Uint8Array, succession: Uint8Array): Promise<{ identityId: Uint8Array; generation: bigint }> {
+    const stage = "completeReplacement";
+    await this.ensureResetList();
+    const previousWire = await this.transport.directory.getCertificate(fromHex(row.expectedCertificateHash));
+    if (!previousWire) throw new KavachError("METADATA_REQUIRED", stage, "the previous certificate is not served");
+    const previous = expectType<AccountDevice>(verifyDocument(previousWire), DocumentType.AccountDevice, stage);
+    if (toHex(previous.bodyHash) !== row.expectedCertificateHash) throw new KavachError("SUCCESSION_BINDING", stage, "the served certificate is not the expected one");
+    const accountId = fromHex(row.accountId);
+    const previousPin = pinFromCertificate(previous, undefined, accountId);
+    // The account's earlier successions, if any: the chain from the root to the previous identity,
+    // verified through the one chain path and kept, so this device holds every key the account
+    // has signed with (an owned circle's snapshot from before an earlier replacement) and can
+    // follow its own chain later (to learn of its retirement).
+    const [me] = await this.transport.directory.resolveAccounts([this.accountName]);
+    // The evidence must be there before anything is written: without the account's resolution the
+    // history is unknown, not empty, and the proposal stays for the next call. An empty history is
+    // right only when the previous identity is the account root.
+    if (!me) throw new KavachError("METADATA_REQUIRED", stage, "the account's history is not served; the proposal stays");
+    const served = me.successions ?? [];
+    const ownSuccession = authenticateSuccession(succession, this.trust, this.now());
+    if (served.length === 0 && me.successionsNext === undefined && !equalBytes(previousPin.identityId, accountId)) throw new KavachError("METADATA_REQUIRED", stage, "the account's earlier successions are not served; the proposal stays");
+    // Bounded by the generation this device's own succession left from, on every page alike.
+    const history = served.length > 0 || me.successionsNext !== undefined ? (await this.followChain({ accountId, accountName: this.accountName, finalIdentityId: previousPin.identityId, untilGeneration: ownSuccession.previousGeneration, firstPage: served, next: me.successionsNext })).verified : [];
+    const accountSeed = roots.subarray(0, 32);
+    const deviceSeed = roots.subarray(32, 64);
+    const recoveryKey = roots.subarray(64, 96);
+    const instanceId = roots.subarray(96, 112);
+    const deviceId = roots.subarray(112, 128);
+    const account = openAccount(this.accountName, accountSeed, accountId);
+    const device = deviceFromSeed(deviceSeed, deviceId);
+    const certificate = fromHex(row.certificate);
+    const doc = expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice, stage);
+    const pin = pinFromCertificate(doc, undefined, accountId);
+    // Roots first, then the store: a crash in between leaves a device the next call finishes.
+    await t1Secrets(this.secrets, { accountSeed, deviceSeed, recoveryKey, instanceId });
+    await this.store.transaction((tx) => {
+      // The previous state as a first contact pins it, then the succession as a peer verifies it:
+      // nothing is written unless the document binds this account, this generation and this key.
+      tx.put("pins", toHex(accountId), pinToRow(previousPin));
+      tx.put("certificates", toHex(previousPin.certificateHash), { identityId: toHex(accountId), certificateHash: toHex(previousPin.certificateHash), signingKey: toHex(previousPin.signingKey), boxKey: toHex(previousPin.boxKey), streamId: toHex(previousPin.streamId), generation: big(previous.generation), wire: toHex(previousWire), current: true });
+      recordChainIn(tx, history, this.now());
+      rootIdentityIn(tx, accountId, this.accountName, me?.rootCertificate);
+      const effect = applySuccession(tx, { wire: succession, newCertificate: certificate, policy: this.policy, trust: this.trust, now: this.now() });
+      if (!equalBytes(effect.newIdentityId, account.identityId) || toHex(effect.accountId) !== row.accountId) throw new KavachError("SUCCESSION_BINDING", stage, "the succession does not name this device's key");
+      this.persistTrustIn(tx);
+      t1Header(tx, { account, device, certificate, instanceId, generation: doc.generation });
+      if (row.vault !== undefined && row.vaultHash !== undefined) t9Vault(tx, { revision: "1", hash: row.vaultHash, wire: row.vault, pending: false, dirty: false });
+      t3ApplyChange(tx, { kind: "ownActivation" });
+      t1Activate(tx);
+      const meta = tx.get("meta", META);
+      if (meta) tx.put("meta", META, { ...meta, bootstrap: { complete: false } });
+      tx.delete("replacement", "pending");
+    });
+    await this.secrets.delete("pendingReplacement");
+    this.account = account;
+    this.device = device;
+    this.selfPin = pin;
+    this.retired = false;
+    try {
+      await this.provider?.save(this.accountName, pin.identityId, recoveryKey);
+    } catch {
+      /* reported by recoveryStatus() */
+    }
+    await this.emitState();
+    return { identityId: pin.identityId, generation: pin.generation };
+  }
+
+  /**
+   * Discovery after account recovery (amendment A1, section 5): the host lists the account's
+   * circles page by page; each is pinned only when its snapshot verifies under the owner's
+   * verified chain and names this account as the host says. Discovery is not permission to share:
+   * the circle is enabled only if the served preference says so. Never writes membership; an
+   * owner's successor republishes the served snapshot at the next revision.
+   */
+  private async bootstrap(report: SyncReport, state: NonNullable<MetaRow["bootstrap"]>): Promise<{ circles: number; pending: number; failed: number }> {
+    const out = { circles: 0, pending: 0, failed: 0 };
+    // A circle that could not be adopted is kept with what the host served and retried by every
+    // sync; a failure never advances past it silently, and never undoes another circle.
+    let retry: BootstrapRetryRow[] = state.retry ?? [];
+    let cursor = state.cursor;
+    let pagesDone = state.pagesDone === true;
+    const adopt = async (c: CircleListing): Promise<boolean> => {
+      try {
+        const r = await this.adoptListing(c, report);
+        if (r === "member") out.circles++;
+        else if (r === "pending") out.pending++;
+        return true;
+      } catch (e) {
+        out.failed++;
+        report.errors.push(syncError("bootstrap", e, { circleId: c.circleId }));
+        return false;
+      }
+    };
+    const save = (done: boolean): Promise<void> =>
+      this.store.transaction((tx) => {
+        const meta = tx.get("meta", META);
+        if (!meta) return;
+        const bootstrap = done && retry.length === 0 ? { complete: true } : { ...(cursor === undefined ? {} : { cursor }), complete: false, retry, pagesDone: done };
+        tx.put("meta", META, { ...meta, bootstrap });
+        t9MarkVault(tx);
+      });
+    const stillFailing: BootstrapRetryRow[] = [];
+    for (const r of retry) {
+      const listing: CircleListing = { circleId: fromHex(r.circleId), ownerAccountId: fromHex(r.ownerAccountId), role: r.role, snapshot: r.snapshot === undefined ? undefined : fromHex(r.snapshot), enabled: r.enabled, preferenceRevision: unbig(r.preferenceRevision) };
+      if (!(await adopt(listing))) stillFailing.push(r);
+    }
+    retry = stillFailing;
+    for (let pages = 0; !pagesDone && pages < 64; pages++) {
+      let page;
+      try {
+        page = await this.transport.directory.listCircles(cursor);
+      } catch (e) {
+        // What landed stays; the cursor says where to resume on the next sync.
+        report.errors.push(syncError("bootstrap", e));
+        await save(false);
+        return out;
+      }
+      for (const c of page.circles) {
+        if (!(await adopt(c))) retry.push({ circleId: toHex(c.circleId), ownerAccountId: toHex(c.ownerAccountId), role: c.role, snapshot: c.snapshot === undefined ? undefined : toHex(c.snapshot), enabled: c.enabled, preferenceRevision: big(c.preferenceRevision) });
+      }
+      cursor = page.cursor;
+      if (cursor === undefined) pagesDone = true;
+      await save(pagesDone);
+    }
+    await save(pagesDone);
+    return out;
+  }
+
+  private async adoptListing(c: CircleListing, report: SyncReport): Promise<"member" | "pending" | "skipped"> {
+    const stage = "bootstrap";
+    const { pin, account } = this.requireAccount(stage);
+    const key = toHex(c.circleId);
+    const existing = await this.store.read((tx) => tx.get("circles", key));
+    if (existing && (existing.revision !== "0" || existing.status === "requested")) return "skipped"; // a restart between pages
+    if (!c.snapshot) return "skipped"; // closed: nothing to pin, nothing to reopen
+    const ownerIsMe = equalBytes(c.ownerAccountId, pin.accountId);
+    let ownerPin = ownerIsMe ? pin : await this.pinFor(c.ownerAccountId);
+    if (!ownerPin) {
+      const [r] = await this.transport.directory.resolveIdentities([c.ownerAccountId]);
+      if (r) await this.acceptMemberCertificate(r, report);
+      ownerPin = await this.pinFor(c.ownerAccountId);
+    }
+    if (!ownerPin) throw new KavachError("METADATA_REQUIRED", stage, "the circle's owner cannot be resolved");
+    const enabled = c.enabled === true;
+    const base = pinCircle(c.circleId, c.ownerAccountId, enabled, c.role === "pending" ? "requested" : "member");
+    const accepted = await this.acceptSnapshotFrom(base, c.snapshot, ownerPin, this.now());
+    if (accepted.outcome !== "ACCEPTED") throw new KavachError("MALFORMED", stage, "an empty snapshot");
+    let state = accepted.state;
+    const named = c.role === "owner" ? equalBytes(state.ownerIdentityId, pin.accountId) : c.role === "member" ? state.members.some((m) => equalBytes(m, pin.accountId)) : true;
+    if (!named) throw new KavachError("NOT_AUTHORIZED", stage, "the snapshot does not name this account as the host says");
+    if (c.role === "pending") state = { ...state, status: "requested" };
+    // The successor owner republishes what it was served at the next revision; the host's
+    // compare-and-swap decides.
+    const republish = ownerIsMe ? buildCircleSnapshot({ circleId: c.circleId, ownerIdentityId: pin.accountId, revision: state.revision + 1n, members: state.members }, account.account.secretKey) : undefined;
+    await this.store.transaction((tx) => {
+      const row = circleToRow(state);
+      t3Circle(tx, republish ? { ...row, pending: { snapshot: toHex(republish), revision: big(state.revision + 1n) } } : row, { kind: "snapshot", circleId: c.circleId, revision: state.revision });
+      if (state.status === "member") t3ApplyChange(tx, { kind: "join", circleId: c.circleId });
+      tx.put("preferences", key, { circleId: key, enabled, revision: big(c.preferenceRevision), pending: undefined, nextSequence: "1" });
+    });
+    this.emit({ kind: "circleChanged", circleId: c.circleId, revision: state.revision, status: state.status });
+    if (republish) {
+      try {
+        await this.publishPendingSnapshot(c.circleId);
+      } catch (e) {
+        report.errors.push(syncError("publishSnapshot", e));
+      }
+    }
+    return state.status === "requested" ? "pending" : "member";
+  }
+
   // Reset -----------------------------------------------------------------------------------------
 
   async resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
@@ -1363,13 +2154,13 @@ class ClientImpl implements Client {
     const certificate = certify(account, device, 1n);
     const newPin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice));
     const recoveryKey = newRecoveryKey();
-    const vault = buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: 1n }, { accountSeed, lastDeviceGeneration: 1n, lastCertificateHash: newPin.certificateHash, entries: [] }, recoveryKey);
+    const vault = this.vaultEnabled ? buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: 1n }, { accountSeed, lastDeviceGeneration: 1n, lastCertificateHash: newPin.certificateHash, entries: [] }, recoveryKey) : undefined;
     const resetId = randomBytes(16);
     const instanceId = randomBytes(16);
     // Persisted before it is sent: the host may commit the new identity and the response be lost,
     // and the only keys that can continue are these. Roots in the secret store, wires in the store.
     await this.secrets.set("pendingReset", concat(accountSeed, device.deviceSeed, recoveryKey, instanceId, device.deviceId));
-    await this.store.transaction((tx) => tx.put("pendingReset", "pending", { resetId: toHex(resetId), oldIdentityId: toHex(pin.identityId), certificate: toHex(certificate), vault: toHex(vault.wire), vaultHash: toHex(vault.hash) }));
+    await this.store.transaction((tx) => tx.put("pendingReset", "pending", { resetId: toHex(resetId), oldIdentityId: toHex(pin.identityId), certificate: toHex(certificate), vault: vault ? toHex(vault.wire) : undefined, vaultHash: vault ? toHex(vault.hash) : undefined }));
     return this.resumeReset(stage, options.reauthProof);
   }
 
@@ -1380,7 +2171,7 @@ class ClientImpl implements Client {
     if (!row || !roots || roots.length !== RESET_ROOTS_BYTES) throw new KavachError("RECOVERY_REQUIRED", stage, "reset pending without its roots");
     const certificate = fromHex(row.certificate);
     expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice, stage);
-    const outcome = await this.transport.directory.resetAccount({ accountName: this.accountName, expectedOldIdentityId: fromHex(row.oldIdentityId), newCertificate: certificate, newVault: fromHex(row.vault), resetId: fromHex(row.resetId), reauthProof: reauthProof ?? new Uint8Array() });
+    const outcome = await this.transport.directory.resetAccount({ accountName: this.accountName, expectedOldIdentityId: fromHex(row.oldIdentityId), newCertificate: certificate, newVault: row.vault === undefined ? undefined : fromHex(row.vault), resetId: fromHex(row.resetId), reauthProof: reauthProof ?? new Uint8Array() });
     if ((outcome.status !== "COMMITTED" && outcome.status !== "ALREADY_COMMITTED") || !outcome.receipt) throw new KavachError("NOT_AUTHORIZED", stage, `host refused reset: ${outcome.status}`);
     return this.finishReset(stage, row, roots);
   }
@@ -1402,11 +2193,11 @@ class ClientImpl implements Client {
     const newPin = pinFromCertificate(expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice, stage));
     await t1Secrets(this.secrets, { accountSeed, deviceSeed, recoveryKey, instanceId });
     await this.store.transaction((tx) => {
-      for (const table of ["meta", "self", "pins", "certificates", "quarantine", "circles", "revision", "vault", "epochs", "stream", "outbox", "history", "historyIndex", "enqueueKeys", "newest", "readerEpochs", "subscriptions", "unresolved", "activation", "pendingReset"] as const) {
+      for (const table of ["meta", "self", "pins", "certificates", "quarantine", "circles", "revision", "vault", "epochs", "stream", "outbox", "history", "historyIndex", "enqueueKeys", "newest", "successions", "identities", "keyChanges", "replacement", "preferences", "chainProgress", "readerEpochs", "subscriptions", "unresolved", "activation", "pendingReset"] as const) {
         for (const [k] of tx.list(table)) tx.delete(table, k);
       }
       t1Header(tx, { account, device, certificate, instanceId, generation: 1n });
-      t9Vault(tx, { revision: "1", hash: row.vaultHash, wire: row.vault, pending: false, dirty: false });
+      if (row.vault !== undefined && row.vaultHash !== undefined) t9Vault(tx, { revision: "1", hash: row.vaultHash, wire: row.vault, pending: false, dirty: false });
       t1Activate(tx);
     });
     await this.secrets.delete("pendingReset");
@@ -1414,7 +2205,7 @@ class ClientImpl implements Client {
     this.device = device;
     this.selfPin = newPin;
     try {
-      await this.provider.save(this.accountName, newPin.identityId, recoveryKey);
+      await this.provider?.save(this.accountName, newPin.identityId, recoveryKey);
     } catch {
       /* reported by recoveryStatus() */
     }