@plane31/blind-relay 0.1.3 → 0.2.0

package/dist/client.js

@@ -6,7 +6,7 @@
 import { concat, equalBytes, fromHex, toHex } from "./bytes.js";
 import { resolveAudience } from "./audience.js";
 import { acceptSnapshot, checkMemberResolution, createCircleSnapshot, newCircleId, pinCircle, successorSnapshot } from "./circle.js";
-import { DocumentType, expectType, parseVaultHeader, verifyDocument } from "./codec.js";
+import { DocumentType, buildCircleSnapshot, expectType, parseDocument, parseVaultHeader, verifyDocument } from "./codec.js";
 import { randomBytes, ready } from "./crypto.js";
 import { prepareEpoch, resolvePublish } from "./epoch.js";
 import { KavachError, isKavachError } from "./errors.js";
@@ -14,10 +14,11 @@ import { acceptCertificate, certify, deviceFromSeed, newAccountSeed, newDevice,
 import { ensureHistoryIndex } from "./historyIndex.js";
 import { ensureSlots, forgetAuthor, forgetAuthorIn, history, historyPage, newest, newestSlot, purgeHistory, receive as receiveRecord, syncStream } from "./inbox.js";
 import { drain, enqueue, outboxCount, outboxCounts, purgeOutbox } from "./outbox.js";
-import { kindOf, validatePolicy } from "./policy.js";
+import { acceptsSuccession, allowsContinuity, kindOf, validatePolicy } from "./policy.js";
 import { ResetTrust } from "./reset.js";
 import { big, circleToRow, pinToRow, rowToCircle, rowToPin, rowToPrepared, unbig } from "./rows.js";
 import { META, REVISION, STREAM, VAULT, openStore, t1Activate, t1Header, t1Secrets, t2PrepareActivation, t3ApplyChange, t3Circle, t4PersistPrepared, t5Committed, t8OwnerSnapshot, t9MarkVault, t9Vault } from "./transactions.js";
+import { applySuccession, authenticateSuccession, pinnedState, recordChainIn, rootIdentityIn, rootState, sameTransition, transitionOf, validateTransition, verifyChain } from "./succession.js";
 import { buildVault, encodeRecoveryCode, newRecoveryKey, openVault, recoverAccount, removeEntry, upsertEntry } from "./vault.js";
 /** accountSeed, deviceSeed, recoveryKey, instanceId and deviceId of a pending reset, in the secret store. */
 const RESET_ROOTS_BYTES = 32 * 3 + 16 + 16;
@@ -37,14 +38,27 @@ function sameEntries(a, b) {
     const key = (es) => es.map((e) => `${toHex(e.circleId)}:${toHex(e.ownerIdentityId)}:${e.sharingEnabled ? 1 : 0}`).sort().join(",");
     return key(a) === key(b);
 }
+function proposalOf(row) {
+    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) {
+    const first = r.successions?.[0];
+    if (first)
+        return expectType(parseDocument(first.wire), DocumentType.AccountSuccession, "resolve").accountId;
+    const doc = expectType(verifyDocument(r.certificate), DocumentType.AccountDevice, "resolve");
+    return pinFromCertificate(doc).identityId;
+}
 export const DEFAULT_CATCH_UP = { maxRecords: 500, maxMs: 5_000 };
-function syncError(operation, e) {
-    return e instanceof KavachError ? { operation, code: e.code, stage: e.stage, retryable: e.retryable } : { operation, code: "UNEXPECTED", stage: operation, retryable: false };
+function syncError(operation, e, extra = {}) {
+    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 = 86400000n;
 export async function open(options) {
     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;
@@ -57,13 +71,21 @@ class ClientImpl {
     secrets;
     transport;
     provider;
+    /** A vault exists only where a recovery provider does: a recovery-only profile without one has no path that reads it. */
+    get vaultEnabled() {
+        return this.provider !== undefined;
+    }
     now;
     listeners = new Set();
     account;
+    /** Retired by a succession or a later device: nothing is written from here again. */
+    retired = false;
     device;
     selfPin;
     trust;
     syncing;
+    /** The current sync's reading budget: records, and the links of a succession chain, count against it. */
+    syncBudget;
     backupChecked = false;
     circles;
     constructor(options, policy) {
@@ -93,14 +115,16 @@ class ClientImpl {
         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);
         }
@@ -140,13 +164,15 @@ class ClientImpl {
         return () => this.listeners.delete(listener);
     }
     requireAccount(stage) {
+        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 };
     }
     selfView() {
         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 };
     }
     outboxDeps() {
         const { device, pin } = this.requireAccount("outbox");
@@ -155,7 +181,7 @@ class ClientImpl {
             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, recordKind) => this.emit({ kind: "queued", recordId, recordKind }),
                 accepted: (recordId) => this.emit({ kind: "accepted", recordId }),
@@ -185,9 +211,11 @@ class ClientImpl {
     // State -----------------------------------------------------------------------------------------
     async getState() {
         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: [], circles: [] };
-        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: [], circles: [] };
+        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();
@@ -209,7 +237,7 @@ class ClientImpl {
     async waitingFor() {
         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();
             for (const [, c] of tx.list("circles"))
@@ -235,9 +263,15 @@ class ClientImpl {
             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,
@@ -272,8 +306,8 @@ class ClientImpl {
         const pin = pinFromCertificate(expectType(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.
@@ -285,7 +319,8 @@ class ClientImpl {
             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;
@@ -293,7 +328,7 @@ class ClientImpl {
         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() */
@@ -302,9 +337,15 @@ class ClientImpl {
         return { identityId: pin.identityId };
     }
     async recoveryStatus() {
+        if (!this.provider)
+            return { status: "unsupported", backupState: "unavailable", reason: "no recovery provider on a recovery-only profile" };
         return this.provider.status();
     }
     async recoveryCode() {
+        // 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");
@@ -324,6 +365,8 @@ class ClientImpl {
             // 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");
@@ -331,7 +374,13 @@ class ClientImpl {
         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,
@@ -340,12 +389,12 @@ class ClientImpl {
             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(verifyDocument(certificate), DocumentType.AccountDevice));
+        const pin = pinFromCertificate(expectType(verifyDocument(certificate), DocumentType.AccountDevice), undefined, accountId);
         const header = parseVaultHeader(vaultWire);
         const nextVault = buildVault({ accountName: this.accountName, accountKey: account.account.publicKey, vaultRevision: header.vaultRevision + 1n }, { accountSeed: recovered.vault.accountSeed, lastDeviceGeneration: generation, lastCertificateHash: pin.certificateHash, entries: recovered.vault.entries }, recovered.recoveryKey);
         const instanceId = pending?.instanceId ?? randomBytes(16);
@@ -353,6 +402,8 @@ class ClientImpl {
             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),
@@ -387,7 +438,7 @@ class ClientImpl {
             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));
             }
@@ -398,7 +449,7 @@ class ClientImpl {
         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() */
@@ -418,14 +469,15 @@ class ClientImpl {
         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)
+        const [self, meta] = await this.store.read((tx) => [tx.get("self", "self"), tx.get("meta", META)]);
+        if (!accountSeed || !deviceSeed || !recoveryKey || !instanceId || !self || !meta)
             throw new KavachError("RECOVERY_REQUIRED", stage, "activation pending without its roots");
-        const account = openAccount(this.accountName, accountSeed);
+        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(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");
@@ -457,7 +509,7 @@ class ClientImpl {
      * asks the provider and saves again when it has nothing for this identity.
      */
     async ensureBackup() {
-        if (this.backupChecked || !this.selfPin)
+        if (this.backupChecked || !this.selfPin || !this.provider)
             return;
         this.backupChecked = true;
         try {
@@ -503,7 +555,7 @@ class ClientImpl {
     /** After commit: the device's own record is stored like any author's, so one subscription covers self and others. */
     enqueued(kind, r) {
         if (!r.duplicate && this.selfPin)
-            this.emit({ kind: "recordStored", recordKind: kind, authorIdentityId: this.selfPin.identityId, recordId: r.recordId, tookSlot: r.own });
+            this.emit({ kind: "recordStored", recordKind: kind, authorIdentityId: this.selfPin.accountId, recordId: r.recordId, tookSlot: r.own });
         return { recordId: r.recordId, duplicate: r.duplicate };
     }
     // Epochs ----------------------------------------------------------------------------------------
@@ -511,7 +563,15 @@ class ClientImpl {
         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);
         });
@@ -552,7 +612,7 @@ class ClientImpl {
             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,
@@ -605,13 +665,32 @@ class ClientImpl {
     }
     async runSync(options) {
         const report = {
-            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));
@@ -643,12 +722,26 @@ class ClientImpl {
         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;
@@ -674,10 +767,9 @@ class ClientImpl {
         // 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 = {
-            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 = 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)));
@@ -708,7 +800,16 @@ class ClientImpl {
         if (me) {
             const theirs = expectType(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();
@@ -733,7 +834,7 @@ class ClientImpl {
         // 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")
@@ -755,18 +856,18 @@ class ClientImpl {
         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)))
+            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);
+                await this.acceptMemberCertificate(r, report);
         }
         const memberIds = new Map();
         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;
@@ -774,7 +875,7 @@ class ClientImpl {
             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
@@ -821,7 +922,7 @@ class ClientImpl {
             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)
@@ -830,9 +931,8 @@ class ClientImpl {
                     const [acct] = await this.transport.directory.resolveAccounts([r.accountName]);
                     if (!acct)
                         continue;
-                    const leaver = pinFromCertificate(expectType(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));
@@ -840,28 +940,308 @@ class ClientImpl {
                 }
             }
         }
-        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();
             for (const r of resolved) {
-                const doc = expectType(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(verifyDocument(r.certificate), DocumentType.AccountDevice, "sync");
+                byIdentity.set(toHex(resolvedAccountId(r)), { accountName: r.accountName, accountKey: r.accountKey });
+                await this.acceptMemberCertificate(r, report);
             }
             checkMemberResolution(byIdentity);
         }
     }
-    async pinFor(identityId) {
-        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.
+     */
+    async supersededBySuccession(pin, me, report) {
+        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.
+     */
+    async acceptSnapshotFrom(c, wire, ownerPin, now, report, resolved = false) {
+        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;
+        }
+    }
+    async pinFor(accountId) {
+        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. */
-    async acceptMemberCertificate(wire, resetReceipt, report) {
+    /**
+     * 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.
+     */
+    async followChain(input) {
+        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) => input.untilGeneration === undefined || expectType(parseDocument(l.wire), DocumentType.AccountSuccession, stage).newGeneration <= input.untilGeneration;
+        const unseen = (links) => links.filter(within).filter((l) => {
+            const doc = expectType(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 = [];
+        let cursor;
+        let pending;
+        // Only links this device has not recorded are verified, and only they count against the budget.
+        const verifyMore = (links) => {
+            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(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 = () => 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 = () => 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 = [];
+            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. */
+    reportAccepted(accepted, report) {
+        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 });
+        }
+    }
+    securityCodeOf(e) {
+        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. */
+    async acceptMemberCertificate(resolved, report) {
+        const wire = resolved.certificate;
+        const resetReceipt = resolved.resetReceipt;
         const doc = expectType(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 = [];
+        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);
@@ -881,24 +1261,33 @@ class ClientImpl {
         }
         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(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 });
+            this.emit({ kind: "deviceChanged", identityId: p.accountId, generation: p.generation });
     }
     async onKeyChanged(current, wire, receipt, report) {
         if (receipt) {
@@ -934,20 +1323,26 @@ class ClientImpl {
     }
     /** Peers on a validated reset: stop sharing to the old identity, close its circles, rotate. */
     applyResetIn(tx, old, newIdentityId) {
-        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))
+            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);
     }
     persistTrustIn(tx) {
         const rows = this.trust.toRows();
@@ -968,12 +1363,13 @@ class ClientImpl {
         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)))
+            if (equalBytes(m, pin.accountId) || others.includes(toHex(m)))
                 continue;
             await forgetAuthor(this.store, m);
         }
     }
     async retire() {
+        this.retired = true;
         await this.store.transaction((tx) => {
             const meta = tx.get("meta", META);
             if (meta)
@@ -1002,9 +1398,30 @@ class ClientImpl {
     newest(identityId, kind) {
         return newestSlot(this.store, identityId, kind, this.now());
     }
+    keyChanges(options = {}) {
+        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 ---------------------------------------------------------------------------------------
     async listCircles() {
-        const self = this.selfPin?.identityId;
+        const self = this.selfPin?.accountId;
         const now = this.now();
         return this.store.read((tx) => tx.list("circles").map(([, r]) => {
             const c = rowToCircle(r);
@@ -1019,6 +1436,8 @@ class ClientImpl {
      * the state, so a change that landed in the rows reaches the vault however the process dies.
      */
     async syncVault() {
+        if (!this.vaultEnabled)
+            return;
         const { account, pin } = this.requireAccount("vault");
         const recoveryKey = await this.secrets.get("recoveryKey");
         const accountSeed = await this.secrets.get("accountSeed");
@@ -1101,11 +1520,14 @@ class ClientImpl {
     async createCircle() {
         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);
@@ -1114,6 +1536,7 @@ class ClientImpl {
             t9MarkVault(tx);
         });
         await this.syncVault();
+        await this.pushPreferencesQuietly();
         this.emit({ kind: "circleChanged", circleId, revision: 1n, status: "member" });
         return { circleId };
     }
@@ -1121,6 +1544,8 @@ class ClientImpl {
         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") {
@@ -1136,18 +1561,30 @@ class ClientImpl {
         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. */
+    async pushPreferencesQuietly() {
+        if (!acceptsSuccession(this.policy))
+            return;
+        try {
+            await this.pushPreferences();
+        }
+        catch {
+            /* retried by sync */
+        }
     }
     async approve(circleId, accountName) {
         const [resolved] = await this.transport.directory.resolveAccounts([accountName]);
         if (!resolved)
             throw new KavachError("METADATA_REQUIRED", "approve", "unknown account");
-        const report = { 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(verifyDocument(resolved.certificate), DocumentType.AccountDevice));
-        const pinned = await this.pinFor(requester.identityId);
-        if (!pinned)
+        const report = { 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(verifyDocument(resolved.certificate), DocumentType.AccountDevice).bodyHash))
             throw new KavachError("ACCOUNT_KEY_CHANGED", "approve", "requester's key is quarantined");
-        return this.changeMembership(circleId, { admit: requester.identityId });
+        return this.changeMembership(circleId, { admit: requester });
     }
     async changeMembership(circleId, change) {
         const { account, pin } = this.requireAccount("changeMembership");
@@ -1163,7 +1600,7 @@ class ClientImpl {
             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 };
@@ -1205,7 +1642,7 @@ class ClientImpl {
         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" } : accepted.state;
@@ -1219,7 +1656,7 @@ class ClientImpl {
             });
             const after = new Set(next.members.map(toHex));
             for (const m of state.members) {
-                if (after.has(toHex(m)) || equalBytes(m, pin.identityId))
+                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)
@@ -1231,7 +1668,7 @@ class ClientImpl {
             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";
         }
@@ -1242,7 +1679,7 @@ class ClientImpl {
         const row = await this.store.read((tx) => tx.get("circles", toHex(circleId)));
         if (!row)
             return;
-        if (row.ownerIdentityId === toHex(pin.identityId))
+        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) => {
@@ -1263,13 +1700,393 @@ class ClientImpl {
         }
         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. */
+    recordPreferenceIn(tx, circleId, enabled) {
+        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.
+     */
+    async pushPreferences(report) {
+        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. */
     async closeCircle(circleId) {
         await this.changeMembership(circleId, { close: true });
     }
+    // Account recovery (amendment A1) ---------------------------------------------------------------
+    async prepareReplacement() {
+        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(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(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 = {
+            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) {
+        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;
+        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;
+            try {
+                current = outcome.current ? expectType(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. */
+    async findOwnLink(row) {
+        const page = await this.transport.directory.getSuccessions(fromHex(row.accountId), unbig(row.expectedGeneration), 8);
+        for (const l of page.successions) {
+            try {
+                const doc = expectType(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. */
+    async ensureResetList() {
+        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.
+     */
+    async activateReplacement(row, roots, succession) {
+        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(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(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.
+     */
+    async bootstrap(report, state) {
+        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 = state.retry ?? [];
+        let cursor = state.cursor;
+        let pagesDone = state.pagesDone === true;
+        const adopt = async (c) => {
+            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) => 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 = [];
+        for (const r of retry) {
+            const listing = { 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;
+    }
+    async adoptListing(c, report) {
+        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) {
         const stage = "resetAccount";
@@ -1284,13 +2101,13 @@ class ClientImpl {
         const certificate = certify(account, device, 1n);
         const newPin = pinFromCertificate(expectType(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);
     }
     /** Send (or re-send) the persisted reset with its own reset id, and finish locally once the host holds it. */
@@ -1301,7 +2118,7 @@ class ClientImpl {
             throw new KavachError("RECOVERY_REQUIRED", stage, "reset pending without its roots");
         const certificate = fromHex(row.certificate);
         expectType(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);
@@ -1323,12 +2140,13 @@ class ClientImpl {
         const newPin = pinFromCertificate(expectType(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"]) {
+            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"]) {
                 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");
@@ -1336,7 +2154,7 @@ class ClientImpl {
         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() */