@interop/wallet-core 0.62.0 → 0.65.0

package/dist/clientAnnex/log.js

@@ -52,11 +52,13 @@ import { createDID, deriveNextKeyHash, updateDID } from '@interop/did-method-web
 import { rootCapabilityId, spaceItems, spacePath, toUrl } from '@interop/was-client/paths';
 import { base64urlnopad } from '@scure/base';
 import { DID_LOG_RESOURCE } from '../space/collections.js';
+import { plaintextCollection } from '../space/plaintextCollection.js';
 import { resourceLogPinId } from '@interop/vh-resource-log';
 import { clientAnnexRung } from './ladder.js';
-import { assertCarryOverCommitments, concludeWithPublishedLog, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, pinOfLog, publishUpdatedLog, putLogResource, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } from '../webvh/didWebvh.js';
-import { delegationKeyInDocument } from '../webvh/listClients.js';
-import { delegationProofKeyId, STANDING_ZCAP_TTL_MS, zcapExpiring } from '../webvh/standingZcap.js';
+import { assertCarryOverCommitments, assertPublishedLogDid, concludeWithPublishedLog, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, pinOfLog, putLogResource, readPublishedLogOrThrow, updateKeySigner, WebvhLogConflictError, withLogConflictRetry } from '../webvh/didWebvh.js';
+import { signAccountEntry } from '../webvh/accountEntry.js';
+import { relationIds } from '../resourceLog/document.js';
+import { STANDING_ZCAP_TTL_MS, standingZcapStale } from '../webvh/standingZcap.js';
 import { wasWebvhLogStore } from '../webvh/wasIdStore.js';
 /**
  * The Space Description `type` array of the auxiliary annex Space, set at
@@ -256,24 +258,30 @@ export async function createClientAnnexLog({ wasServerUrl, spaceId, generationId
  * @param options.controller {string}   the Space controller (the account
  *   did:webvh where it exists; a bootstrap did:key on a ladder-anchored signup,
  *   promoted the same way the account Space's controller is)
- * @returns {Promise<void>}
+ * @returns {Promise<SpaceDescription>}   the Space Description this call read
+ *   (the Space already existed) or wrote (it did not), so a caller flipping
+ *   the controller straight afterwards can hand it back as `current` instead
+ *   of paying for a second read.
  */
 export async function ensureClientAnnexSpace({ was, spaceId, controller }) {
     const space = was.space(spaceId);
     const current = await space.describe();
     if (current === null) {
-        await space.configure({
+        // `current: null` is the answer this read just produced, so was-client
+        // skips its own pre-merge describe rather than repeating it.
+        return space.configure({
+            current: null,
             controller,
             type: CLIENT_ANNEX_SPACE_TYPE,
             force: true
         });
-        return;
     }
     if (!current.type?.includes(DELEGATED_CLIENTS_SPACE_TYPE)) {
         throw new Error(`The Space "${spaceId}" exists but is not typed as the ` +
             'delegated-clients auxiliary Space; its type is immutable, so it ' +
             'cannot hold client-annex generations.');
     }
+    return current;
 }
 /**
  * Mints a fresh annex generation with controller-tier signing: ensures
@@ -308,12 +316,19 @@ export async function ensureClientAnnexSpace({ was, spaceId, controller }) {
  *   rung-0 hash, the minting credential's included
  * @param options.signer {Signer}   the minting credential's rung-0 signer
  * @returns {Promise<{ did: string; generationId: string; log: DIDLog;
- *   doc: DIDDoc }>}
+ *   doc: DIDDoc; spaceDescription?: SpaceDescription }>}   `spaceDescription`
+ *   is the auxiliary Space's Description as the ensure read or wrote it, so a
+ *   caller flipping the controller afterwards need not re-read it. Always
+ *   present here, since this minter always runs the ensure.
  */
 export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
-    await ensureClientAnnexSpace({ was, spaceId, controller });
+    const spaceDescription = await ensureClientAnnexSpace({
+        was,
+        spaceId,
+        controller
+    });
     const generationId = mintGenerationId();
-    return publishClientAnnexGenesis({
+    const published = await publishClientAnnexGenesis({
         was,
         wasServerUrl,
         spaceId,
@@ -322,6 +337,7 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
         nextKeyHashes,
         signer
     });
+    return { ...published, spaceDescription };
 }
 /**
  * The shared genesis-publish tail of both generation minters: creates the
@@ -343,14 +359,17 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
  */
 async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, capability }) {
     // The generation collection must exist before its first resource PUT; a
-    // fresh random generation id means this is always a create. Plaintext on
-    // purpose:
-    // the server resolves the annex DID out of its own storage, and the
-    // collection is capability-gated rather than encrypted.
-    await was
-        .space(spaceId, capability !== undefined ? { capability } : {})
-        .collection(generationId, { encryption: 'plaintext' })
-        .configure({ name: generationId, force: true });
+    // fresh random generation id means this is always a create, so the truthful
+    // `current: null` skips was-client's pre-merge describe of a Collection
+    // that cannot exist. Plaintext on purpose: the server resolves the annex
+    // DID out of its own storage, and the collection is capability-gated rather
+    // than encrypted.
+    await plaintextCollection({
+        was,
+        spaceId,
+        collectionId: generationId,
+        capability
+    }).configure({ current: null, name: generationId, force: true });
     const created = await createClientAnnexLog({
         wasServerUrl,
         spaceId,
@@ -404,15 +423,18 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
  *   covers the collections beneath the Space, never the Space Description,
  *   and a standing sibling delegation presupposes the auxiliary Space
  * @returns {Promise<{ did: string; generationId: string; log: DIDLog;
- *   doc: DIDDoc }>}
+ *   doc: DIDDoc; spaceDescription?: SpaceDescription }>}   `spaceDescription`
+ *   is the auxiliary Space's Description as the ensure read or wrote it, so a
+ *   caller flipping the controller afterwards need not re-read it. Present
+ *   exactly when the ensure ran, so absent under a supplied `capability`.
  */
 export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, extraNextKeyHashes = [], capability }) {
-    if (capability === undefined) {
-        await ensureClientAnnexSpace({ was, spaceId, controller });
-    }
+    const spaceDescription = capability === undefined
+        ? await ensureClientAnnexSpace({ was, spaceId, controller })
+        : undefined;
     const generationId = mintGenerationId();
     const rung = await clientAnnexRung({ ladderSeed, generationId });
-    return publishClientAnnexGenesis({
+    const published = await publishClientAnnexGenesis({
         was,
         wasServerUrl,
         spaceId,
@@ -425,6 +447,10 @@ export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, s
         signer: await updateKeySigner({ seed: rung.seed }),
         ...(capability !== undefined ? { capability } : {})
     });
+    return {
+        ...published,
+        ...(spaceDescription !== undefined ? { spaceDescription } : {})
+    };
 }
 /**
  * The type IRI of the account document's delegated-clients service entry --
@@ -481,6 +507,61 @@ export function delegatedClientsPointer({ doc }) {
     }
     return undefined;
 }
+/**
+ * Every auxiliary annex Space the account log's `#DelegatedClients` pointer
+ * has ever named, oldest first and one entry per Space. A pointer entry is
+ * append-only: a superseded value stops being current but its Space survives
+ * the move, so an enumeration that reads only the resolved document (the
+ * {@link delegatedClientsPointer} case) misses every Space a generation swap
+ * has left behind. Several generations of one Space collapse to the entry
+ * that named it first.
+ *
+ * The account deletion ceremony is the reader: it must name each auxiliary
+ * Space it is about to destroy, and the log is the only durable record of
+ * the superseded ones. Each entry carries the annex DID and its host beside
+ * the Space id, because an account that has migrated hosts leaves entries
+ * this deployment cannot address: deleting `spaceId` on the CURRENT host
+ * would address a Space that is not the one the entry names, and a 404 there
+ * would otherwise read as a clean deletion. Such an entry is the caller's to
+ * report as a residue.
+ *
+ * The acting unlock record's own `delegatedClients` sibling target is NOT
+ * included here; a caller that wants it unions it in itself, since a torn
+ * establishment can converge on a Space no pointer entry ever named.
+ *
+ * An entry carrying no document state, and an endpoint that does not parse
+ * as a client-annex DID, are skipped rather than refused: the walk is an
+ * enumeration aid, and a caller cannot act on an id it could not read.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the VERIFIED account log
+ * @returns {Array<{ did: string, host: string, spaceId: string }>}   the
+ *   Spaces, in log order
+ */
+export function delegatedClientsSpaceHistory({ log }) {
+    const spaces = [];
+    for (const entry of log) {
+        if (entry?.state === undefined || entry.state === null) {
+            continue;
+        }
+        const pointed = delegatedClientsPointer({ doc: entry.state });
+        if (pointed === undefined) {
+            continue;
+        }
+        let parts;
+        try {
+            parts = clientAnnexDidParts({ did: pointed });
+        }
+        catch {
+            continue;
+        }
+        if (spaces.some(space => space.spaceId === parts.spaceId)) {
+            continue;
+        }
+        spaces.push({ did: pointed, host: parts.host, spaceId: parts.spaceId });
+    }
+    return spaces;
+}
 /**
  * The account document's `service` array with the delegated-clients pointer
  * set to `clientAnnexDid`. An existing pointer entry is re-pointed in place,
@@ -901,33 +982,42 @@ function withGenerationDelegationEntry({ doc, clientAnnexDid, delegation }) {
         ];
 }
 /**
- * Parses the auxiliary Space id and generation id out of an annex DID
- * string. Both are permanent substrings of every annex DID by
+ * Parses the host, the auxiliary Space id and the generation id out of an
+ * annex DID string. All three are permanent substrings of every annex DID by
  * construction: the generation id is the final path segment of the annex
  * DID (`did:webvh:<scid>:<host>:...:space:<spaceId>:<generationId>`), and it
  * is the generation-identifying half of the annex rung HKDF
  * labels, so this parse is what lets an enrollee derive its writing key from
  * the pointer alone -- no log read, no registry.
  *
+ * The host is the method-specific id's second segment, percent-decoded (a
+ * port rides as `%3A` inside the one segment). A caller enumerating Spaces
+ * out of a log compares it against the deployment it is talking to: an
+ * account that has migrated hosts carries entries naming the old one, which
+ * this deployment cannot address.
+ *
  * @param options {object}
  * @param options.did {string}   an annex did:webvh string
- * @returns {{ spaceId: string, generationId: string }}
+ * @returns {{ host: string, spaceId: string, generationId: string }}
  */
 export function clientAnnexDidParts({ did }) {
     const parts = did.split(':');
     const generationId = parts[parts.length - 1];
     const spaceId = parts[parts.length - 2];
+    const host = parts[3];
     if (parts.length < 7 ||
         parts[0] !== 'did' ||
         parts[1] !== 'webvh' ||
         parts[parts.length - 3] !== 'space' ||
         generationId === undefined ||
         spaceId === undefined ||
-        spaceId.length === 0) {
+        spaceId.length === 0 ||
+        host === undefined ||
+        host.length === 0) {
         throw new Error(`Not a client annex did:webvh: "${did}".`);
     }
     assertGenerationId(generationId);
-    return { spaceId, generationId };
+    return { host: decodeURIComponent(host), spaceId, generationId };
 }
 /**
  * Thrown when the published annex log commits neither the writing
@@ -944,6 +1034,37 @@ export class ClientAnnexRungUncommittedError extends Error {
         this.name = 'ClientAnnexRungUncommittedError';
     }
 }
+/**
+ * Derives a generation's rung-0 key for a ladder and admits it as the writer
+ * of the entry about to be built: it must stand revealed in the log's
+ * `updateKeys`, or its hash must stand committed in `nextKeyHashes`.
+ *
+ * The one implementation of the annex's writer-admission rule, which every
+ * entry builder in this module applies before it mints anything. Annex
+ * entries verify against the log's own hash-commitment chain, so a key that
+ * is neither revealed nor committed can never be made to verify mid-log --
+ * the caller supplies only the refusal message, since what a locked-out
+ * credential should do next differs per ceremony.
+ *
+ * @param options {object}
+ * @param options.ladderSeed {Uint8Array}   the acting credential's ladder seed
+ * @param options.generationId {string}
+ * @param options.updateKeys {string[]}   the keys the entry will be verified
+ *   against (the retired members already excluded, where a ceremony excludes
+ *   them)
+ * @param options.nextKeyHashes {string[]}   likewise
+ * @param options.message {string}   the refusal's message
+ * @returns {Promise<{ seed: Uint8Array; keyMultibase: string }>}
+ */
+async function admitActingRung({ ladderSeed, generationId, updateKeys, nextKeyHashes, message }) {
+    const rung = await clientAnnexRung({ ladderSeed, generationId });
+    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
+    if (!updateKeys.includes(rung.keyMultibase) &&
+        !nextKeyHashes.includes(rungHash)) {
+        throw new ClientAnnexRungUncommittedError(message);
+    }
+    return rung;
+}
 /**
  * Reads and resolves the published annex log through the narrow seam, or
  * throws when the generation's `did.jsonl` is missing (an unpointed or
@@ -957,18 +1078,14 @@ export class ClientAnnexRungUncommittedError extends Error {
  * @returns {Promise<PublishedWebvhLog>}
  */
 async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }) {
-    // readPublishedLog only calls getIdResourceRaw, so the narrow seam is safe.
-    const published = await readPublishedLog({
+    return readPublishedLogOrThrow({
         idStore: store,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
         ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
+        ...(logId !== undefined ? { logId } : {}),
+        missingMessage: 'client annex: did.jsonl is missing; the generation was never minted ' +
+            'or has been collected.'
     });
-    if (!published) {
-        throw new Error('client annex: did.jsonl is missing; the generation was never minted or ' +
-            'has been collected.');
-    }
-    return published;
 }
 /**
  * TRANSIENT ENROLLMENT: publishes one per-visit verification method into a
@@ -1032,27 +1149,56 @@ async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }
  *   transient session passes an in-memory store)
  * @param [options.logId] {string}   the generation's pin-slot key, from
  *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ * @param [options.published] {PublishedWebvhLog}   a head the caller already
+ *   read and verified under this same pin slot, so the enrollment builds its
+ *   entry on it instead of spending a second round trip on the same log (the
+ *   transient visit's one-read composition). The FIRST attempt alone rides it:
+ *   a lost compare-and-swap means the head is stale by definition, so the
+ *   conflict retry re-reads under the pin. That threaded attempt is EXTRA
+ *   rather than one of the retry's three: a caller who saved a read is left
+ *   with the same conflict budget as one who did not
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-export async function enrollClientAnnexTransientClient(options) {
-    return withLogConflictRetry(() => enrollClientAnnexTransientClientOnce(options));
+export async function enrollClientAnnexTransientClient({ published: threadedHead, ...rest }) {
+    if (threadedHead !== undefined) {
+        try {
+            return await enrollClientAnnexTransientClientOnce({
+                ...rest,
+                published: threadedHead
+            });
+        }
+        catch (err) {
+            // A lost compare-and-swap on the threaded head says only that the head
+            // is stale; the retry below re-reads under the pin with its whole
+            // budget. Every other failure is the caller's.
+            if (!(err instanceof WebvhLogConflictError)) {
+                throw err;
+            }
+        }
+    }
+    return withLogConflictRetry(() => enrollClientAnnexTransientClientOnce(rest));
 }
 /**
  * One attempt of {@link enrollClientAnnexTransientClient}, re-invoked by the
  * conflict retry (with the same signing key -- static rung 0 has no
- * advanced-rung retry shape).
+ * advanced-rung retry shape) and with no threaded head after the first.
  *
  * @param options {object}   see {@link enrollClientAnnexTransientClient}
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generationId, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId }) {
+async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generationId, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, published: alreadyRead }) {
     assertGenerationId(generationId);
-    const published = await readClientAnnexLogOrThrow({
-        store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
+    const published = alreadyRead !== undefined
+        ? assertPublishedLogDid({
+            published: alreadyRead,
+            ...(expectedDid !== undefined ? { expectedDid } : {})
+        })
+        : await readClientAnnexLogOrThrow({
+            store,
+            ...(expectedDid !== undefined ? { expectedDid } : {}),
+            ...(pinStore !== undefined ? { pinStore } : {}),
+            ...(logId !== undefined ? { logId } : {})
+        });
     const { did, doc } = published;
     const vmId = `${did}#${transientKeyMultibase}`;
     // Already enrolled (a completed earlier run): the VM and everything the
@@ -1062,14 +1208,15 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
     if (existingMethods.some(method => method.id === vmId)) {
         return { did, doc, log: published.log };
     }
-    const rung = await clientAnnexRung({ ladderSeed, generationId });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    const revealed = published.updateKeys.includes(rung.keyMultibase);
-    if (!revealed && !published.nextKeyHashes.includes(rungHash)) {
-        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither this credential's rung-0 key nor " +
+    const rung = await admitActingRung({
+        ladderSeed,
+        generationId,
+        updateKeys: published.updateKeys,
+        nextKeyHashes: published.nextKeyHashes,
+        message: "client annex: the log commits neither this credential's rung-0 key nor " +
             'its hash; a credential bound mid-generation cannot write the ' +
-            'annex until a writer commits its hash or the next GC swap does.');
-    }
+            'annex until a writer commits its hash or the next GC swap does.'
+    });
     // A non-rotating entry re-states `updateKeys`, which the resolver checks
     // against the previous entry's commitments -- genesis enforces the
     // carry-over convention, and this refuses a log that lost it anyway.
@@ -1125,6 +1272,13 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
     // The log only -- an annex has no did:web projection -- conditional on
     // the read this entry was built on.
     await putLogResource({ store, log: updated.log, ifMatch: published.etag });
+    // Advance the pin to what this entry just published, so a host serving the
+    // pre-entry log straight afterwards is refused as a rollback on the next
+    // read (equal-to-pin would otherwise be accepted, and a later stage built on
+    // the stale head would miss this entry).
+    if (pinStore && logId !== undefined) {
+        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
+    }
     return { did: updated.did, doc: updated.doc, log: updated.log };
 }
 /**
@@ -1140,16 +1294,19 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
  * entry is appended ({@link delegatedClientsServiceEntry}). Every other
  * service entry, the verification methods, and the relationship arrays are
  * preserved untouched. Idempotent: a document already pointing at the DID is
- * a no-op on the log (it still heals a lagging `did.json`).
+ * a no-op on the log (and, unless `logOnly`, it republishes `did.json` from
+ * the resolved log, which the enrolled-client caller has the authority to
+ * do).
  *
  * @param options {object}
  * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store; with
  *   `logOnly`, only its log read and `did.jsonl` PUT are used, so the narrow
  *   delegated seam satisfies it
- * @param options.updateKeys {ClientWebvhUpdateKeys}   this enrolled client's
- *   update-key seeds -- or the ladder-rung idiom on a ladder-anchored
- *   account (`{ updateSeed: rung0.seed, stagedSeed: rung1.seed }`), as the
- *   credential-anchored genesis and the transient-recovery continuation pass
+ * @param options.signer {AccountLogSigner}   who signs the pointer entry:
+ *   this enrolled client's update-key seeds -- or the ladder-rung idiom on a
+ *   ladder-anchored account (`{ updateSeed: rung0.seed, stagedSeed:
+ *   rung1.seed }`), as the credential-anchored genesis and the
+ *   transient-recovery continuation pass
  * @param options.clientAnnexDid {string}   the generation to point at
  * @param [options.expectedDid] {string}   the account DID the log must
  *   resolve to, from the account pointer
@@ -1161,24 +1318,56 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
  * @param [options.logOnly] {boolean}   publish `did.jsonl` only, never the
  *   `did.json` projection -- the transient-recovery continuation writing
  *   through the record's bridge delegation, whose narrow scope covers nothing
- *   but the log. The projection heals at the next authorized write (the log
- *   is the source of truth)
- * @returns {Promise<{ did: string, doc: DIDDoc }>}
+ *   but the log. The projection then lags until some caller holding an
+ *   `id`-collection writer runs `ensureDidWebProjection` over the resolved
+ *   log; on a client-less account that is a transient visit under its
+ *   generation delegation. The log stays the source of truth meanwhile, and
+ *   the server reads it rather than the projection, so the lag is a `did:web`
+ *   verifier's concern alone
+ * @param [options.published] {PublishedWebvhLog}   a head the caller already
+ *   read and verified under this same pin slot, so the pointer entry builds
+ *   on it instead of spending a second round trip on the log the caller just
+ *   read or published (the establishment's one-read composition). The FIRST
+ *   attempt alone rides it: a lost compare-and-swap means the head is stale
+ *   by definition, so the conflict retry re-reads under the pin. That
+ *   threaded attempt is EXTRA rather than one of the retry's three: a caller
+ *   who saved a read is left with the same conflict budget as one who did not
+ * @returns {Promise<{ did: string, doc: DIDDoc,
+ *   published: PublishedWebvhLog }>}   `published` is the head this call
+ *   leaves standing: the post-entry one, paired with its publish's own ETag,
+ *   when the entry was appended; the head it stood on verbatim when the
+ *   document already pointed at the DID
  */
-export async function setDelegatedClientsPointer(options) {
-    return withLogConflictRetry(() => setDelegatedClientsPointerOnce(options));
+export async function setDelegatedClientsPointer({ published: threadedHead, ...rest }) {
+    if (threadedHead !== undefined) {
+        try {
+            return await setDelegatedClientsPointerOnce({
+                ...rest,
+                published: threadedHead
+            });
+        }
+        catch (err) {
+            // A lost compare-and-swap on the threaded head says only that the head
+            // is stale; the retry below re-reads under the pin with its whole
+            // budget. Every other failure is the caller's.
+            if (!(err instanceof WebvhLogConflictError)) {
+                throw err;
+            }
+        }
+    }
+    return withLogConflictRetry(() => setDelegatedClientsPointerOnce(rest));
 }
 /**
  * ONE attempt of {@link setDelegatedClientsPointer}, re-invoked by that
  * function's conflict retry and exported for a caller that runs its own.
  * A caller whose retry loop also attributes the signing rung must use this
  * form: the wrapper's inner retry would re-invoke the attempt with the SAME
- * `updateKeys`, and a rung a racing ceremony consumed meanwhile can never
+ * signer, and a rung a racing ceremony consumed meanwhile can never
  * become authorized by re-reading, so the attempt would fail on the plain
  * not-authorized refusal instead of surfacing the conflict the caller's loop
  * knows how to re-attribute from.
  *
- * A caller that already read the head its `updateKeys` were attributed
+ * A caller that already read the head its signer was attributed
  * against passes it as `published`, and the entry is built on exactly that
  * head. A racing entry landing in between then loses the CAS on the PUT and
  * surfaces as a {@link WebvhLogConflictError}, which is what a re-attributing
@@ -1189,72 +1378,64 @@ export async function setDelegatedClientsPointer(options) {
  * @param [options.published] {PublishedWebvhLog}   the verified head to build
  *   this entry on, when the caller has already read it under the same pin;
  *   absent, the attempt reads the head itself
- * @returns {Promise<{ did: string, doc: DIDDoc }>}
+ * @returns {Promise<{ did: string, doc: DIDDoc,
+ *   published: PublishedWebvhLog }>}
  */
-export async function setDelegatedClientsPointerOnce({ idStore, updateKeys, clientAnnexDid, expectedDid, pinStore, logId, logOnly = false, published: alreadyRead }) {
+export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAnnexDid, expectedDid, pinStore, logId, logOnly = false, published: alreadyRead }) {
     // Refuses a malformed target before anything is read or written.
     clientAnnexDidParts({ did: clientAnnexDid });
-    const published = alreadyRead ??
-        (await readPublishedLog({
-            idStore,
-            ...(expectedDid !== undefined ? { expectedDid } : {}),
-            ...(pinStore !== undefined ? { pinStore } : {}),
-            ...(logId !== undefined ? { logId } : {})
-        }));
-    if (!published) {
-        throw new Error('did:webvh: did.jsonl is missing; nothing to point at a client annex.');
-    }
-    const { did, doc } = published;
-    if (delegatedClientsPointer({ doc }) === clientAnnexDid) {
-        if (!logOnly) {
-            await concludeWithPublishedLog({ idStore, published });
-        }
-        return { did, doc };
-    }
-    // The entry is signed by this client's active update key; a log that does
-    // not authorize it (a rotation torn elsewhere) must heal first.
-    const activeKey = await updateKeyMultibase({ seed: updateKeys.updateSeed });
-    if (!published.updateKeys.includes(activeKey)) {
-        throw new Error("did:webvh: the published log does not authorize this client's active " +
-            'update key; finalize the pending rotation before re-pointing the ' +
-            'delegated-clients entry.');
-    }
-    await assertCarryOverCommitments({ published });
-    const services = servicesPointedAtClientAnnex({
-        doc,
-        accountDid: did,
-        clientAnnexDid
-    });
-    const signer = await updateKeySigner({ seed: updateKeys.updateSeed });
-    const updated = await updateDID({
-        log: published.log,
+    let settled;
+    const outcome = await signAccountEntry({
+        idStore,
         signer,
-        alsoKnownAsWeb: true,
-        // Re-stated unchanged (the library requires them explicitly while
-        // prerotation is active); the carry-over commitments are what make the
-        // re-statement resolvable.
-        updateKeys: published.updateKeys,
-        nextKeyHashes: published.nextKeyHashes,
-        services
+        ...(alreadyRead !== undefined ? { published: alreadyRead } : {}),
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {}),
+        missingMessage: 'did:webvh: did.jsonl is missing; nothing to point at a client annex.',
+        verb: 're-pointing the delegated-clients entry',
+        logOnly,
+        build: async ({ published }) => {
+            const { did, doc } = published;
+            if (delegatedClientsPointer({ doc }) === clientAnnexDid) {
+                if (!logOnly && signer.kind === 'client') {
+                    await concludeWithPublishedLog({ idStore, published });
+                }
+                // The head verbatim: the projection PUT touches no log, so this
+                // read's own ETag is still the log's validator.
+                settled = { did, doc, published };
+                return undefined;
+            }
+            return {
+                services: servicesPointedAtClientAnnex({
+                    doc,
+                    accountDid: did,
+                    clientAnnexDid
+                })
+            };
+        }
     });
-    if (logOnly) {
-        await putLogResource({
-            store: idStore,
-            log: updated.log,
-            ifMatch: published.etag
-        });
-    }
-    else {
-        await publishUpdatedLog({ idStore, updated, ifMatch: published.etag });
-    }
-    // Advance the pin to what this entry just published, so a host serving the
-    // pre-entry log straight afterwards is refused as a rollback on the next
-    // read (equal-to-pin would otherwise be accepted, and a composition built
-    // on the stale head would re-heal and mint litter).
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
+    if (settled) {
+        return settled;
     }
-    return { did: updated.did, doc: updated.doc };
+    const updated = outcome.updated;
+    return {
+        did: updated.did,
+        doc: updated.doc,
+        // The post-entry head, from what `updateDID` already resolved plus this
+        // publish's own validator: the update-key parameters are the ones the
+        // entry re-stated unchanged above, so nothing is re-resolved or re-read.
+        published: {
+            log: updated.log,
+            did: updated.did,
+            // Detached from the entry's own `state`, as every other producer of
+            // this type is, so a consumer editing the document cannot edit the log.
+            doc: structuredClone(updated.doc),
+            updateKeys: updated.meta.updateKeys,
+            nextKeyHashes: updated.meta.nextKeyHashes,
+            ...(outcome.etag !== undefined ? { etag: outcome.etag } : {})
+        }
+    };
 }
 /**
  * The whole transient-enrollment ceremony as the enrollee runs it: resolve
@@ -1291,9 +1472,15 @@ export async function setDelegatedClientsPointerOnce({ idStore, updateKeys, clie
  * @param [options.maxRounds] {number}   how many pointer moves to chase
  *   before giving up (a GC pass is quarterly, so more than one mid-ceremony
  *   move means something else is wrong)
+ * @param [options.published] {PublishedWebvhLog}   a generation head the
+ *   caller already read and verified under this same pin store (the readiness
+ *   stage's, when it published nothing to that log). Round 0 alone rides it,
+ *   and only when it is the generation the account document points at NOW: a
+ *   head for any other generation is ignored and the round reads fresh, as
+ *   every later round does
  * @returns {Promise<{ clientAnnexDid: string, doc: DIDDoc, log: DIDLog }>}
  */
-export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds = 3 }) {
+export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds = 3, published: threadedHead }) {
     let accountDoc = await readAccountDocument();
     for (let round = 0; round < maxRounds; round++) {
         const clientAnnexDid = delegatedClientsPointer({ doc: accountDoc });
@@ -1304,12 +1491,19 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
         const { spaceId, generationId } = clientAnnexDidParts({
             did: clientAnnexDid
         });
+        // Round 0's threaded head, and only for the generation the pointer names:
+        // a head read before a GC swap belongs to the abandoned generation and
+        // says nothing about the one this round enrolls into.
+        const head = round === 0 && threadedHead?.did === clientAnnexDid
+            ? threadedHead
+            : undefined;
         const enrolled = await enrollClientAnnexTransientClient({
             store: storeForGenerationId(generationId),
             ladderSeed,
             generationId,
             transientKeyMultibase,
             expectedDid: clientAnnexDid,
+            ...(head !== undefined ? { published: head } : {}),
             ...(mintDelegation !== undefined
                 ? { mintGenerationDelegation: mintDelegation }
                 : {}),
@@ -1332,8 +1526,8 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * RENEW PRECEDES MINT: the blocking pre-mint stage a transient App Connect
  * approval runs before delegating any grant. Reads the annex document
  * and hands back its embedded generation delegation -- renewing it first
- * when it is expired or inside the 30-day renewal window ({@link
- * zcapExpiring}): a fresh delegation is minted through the caller's closure
+ * when it is stale under the house policy ({@link standingZcapStale}): a
+ * fresh delegation is minted through the caller's closure
  * (ladder-signed -- the renewal must not depend on the very delegation it
  * replaces; published through the store, which in a transient session is
  * the credential's sibling delegation, so even a hard-expired delegation is
@@ -1344,14 +1538,16 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * same way (the GC ceremony's own install stage and the first-VM install
  * make this rare; a heal, not a policy).
  *
- * Beside the expiry axis, an `accountDoc` adds the SIGNER-DEATH axis: a
- * standing delegation whose proof key is no longer in the supplied verified
- * account document has rotted under the current-key-set rule (the enrolled
- * client that minted it was revoked, or the ladder VM that signed it left
- * with the first self-enrollment) and is replaced the same way. No
- * revocation POST accompanies the replacement: a rotted chain no longer
- * verifies at the revocation endpoint, and the expiry-renewal path never
- * revoked either.
+ * That policy is three axes. Expiry -- past, or inside the 30-day renewal
+ * window. SIGNER DEATH, which an `accountDoc` adds: a standing delegation
+ * whose proof key is no longer in the supplied verified account document has
+ * rotted under the current-key-set rule (the enrolled client that minted it
+ * was revoked, or the ladder VM that signed it left with the first
+ * self-enrollment). And RETIREMENT, the projected post-edit reading a caller
+ * asks for with `retiringKeyMultibases`, for a key still listed whose
+ * authority the ceremony is about to end. No revocation POST accompanies the
+ * replacement: a rotted chain no longer verifies at the revocation endpoint,
+ * and the expiry-renewal path never revoked either.
  *
  * Failure is the caller's failure: a renewal that cannot complete throws,
  * and the App Connect approval fails with the standard retryable-ceremony
@@ -1380,64 +1576,96 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * @param [options.accountDoc] {PublishedKeyDocument}   the locally VERIFIED
  *   account document; supplied, a standing delegation whose proof key it no
  *   longer lists is replaced (the signer-death axis above)
- * @param [options.force] {boolean}   replace the embedded delegation
- *   unconditionally, however healthy it looks -- the last-client
- *   forget's replacement stage, where the standing delegation has just been
- *   revoked server-side (a state no client-side predicate can read)
+ * @param [options.retiringKeyMultibases] {string[]}   keys whose authority is
+ *   about to end, read as a projected post-edit document: a standing
+ *   delegation one of them signed is replaced even though the served document
+ *   still lists the key. The last-client transition's replacement stage names
+ *   its own ladder VM (whose delegations it revokes server-side in the next
+ *   breath, a state no client-side predicate can read) and the client its
+ *   removal entry has yet to strike
  * @param [options.now] {number}   epoch milliseconds, for tests
- * @returns {Promise<{ delegation: IZcap, renewed: boolean }>}
+ * @param [options.published] {PublishedWebvhLog}   a head the caller already
+ *   read and verified under this same pin slot, so the stage builds on it
+ *   instead of spending a second round trip on the same log (the transient
+ *   visit's one-read composition). The FIRST attempt alone rides it: a lost
+ *   compare-and-swap means the head is stale by definition, so the conflict
+ *   retry re-reads under the pin. That threaded attempt is EXTRA rather than
+ *   one of the retry's three: a caller who saved a read is left with the same
+ *   conflict budget as one who did not
+ * @returns {Promise<{ delegation: IZcap, renewed: boolean,
+ *   published?: PublishedWebvhLog }>}   `published` is the verified head this
+ *   pass stood on -- the one read, or the one handed in -- and is present
+ *   ONLY when `renewed` is false. The two store implementations differ on
+ *   what a renewal's publish hands back: the controller-tier store forwards
+ *   the PUT's own ETag, while the delegated store discards the response and
+ *   yields none. This stage takes either, and cannot tell which from here, so
+ *   it stays conservative and passes no post-renewal head on; a caller
+ *   wanting one reads for itself
  */
-export async function ensureGenerationDelegationCurrent(options) {
-    return withLogConflictRetry(() => ensureGenerationDelegationCurrentOnce(options));
+export async function ensureGenerationDelegationCurrent({ published: threadedHead, ...rest }) {
+    if (threadedHead !== undefined) {
+        try {
+            return await ensureGenerationDelegationCurrentOnce({
+                ...rest,
+                published: threadedHead
+            });
+        }
+        catch (err) {
+            // A lost compare-and-swap on the threaded head says only that the head
+            // is stale; the retry below re-reads under the pin with its whole
+            // budget. Every other failure is the caller's.
+            if (!(err instanceof WebvhLogConflictError)) {
+                throw err;
+            }
+        }
+    }
+    return withLogConflictRetry(() => ensureGenerationDelegationCurrentOnce(rest));
 }
 /**
  * One attempt of {@link ensureGenerationDelegationCurrent}, re-invoked by the
  * conflict retry (with the same signing key -- static rung 0 has no
- * advanced-rung retry shape).
+ * advanced-rung retry shape) and with no threaded head after the first.
  *
  * @param options {object}   see {@link ensureGenerationDelegationCurrent}
- * @returns {Promise<{ delegation: IZcap, renewed: boolean }>}
+ * @returns {Promise<{ delegation: IZcap, renewed: boolean,
+ *   published?: PublishedWebvhLog }>}
  */
-async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, generationId, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, accountDoc, force = false, now }) {
+async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, generationId, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, accountDoc, retiringKeyMultibases = [], now, published: alreadyRead }) {
     assertGenerationId(generationId);
-    const published = await readClientAnnexLogOrThrow({
-        store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
+    const published = alreadyRead !== undefined
+        ? assertPublishedLogDid({
+            published: alreadyRead,
+            ...(expectedDid !== undefined ? { expectedDid } : {})
+        })
+        : await readClientAnnexLogOrThrow({
+            store,
+            ...(expectedDid !== undefined ? { expectedDid } : {}),
+            ...(pinStore !== undefined ? { pinStore } : {}),
+            ...(logId !== undefined ? { logId } : {})
+        });
     const { did, doc } = published;
     const standing = embeddedGenerationDelegation({ doc });
-    const signerRotted = standing !== undefined &&
-        accountDoc !== undefined &&
-        !delegationKeyInDocument({
-            doc: accountDoc,
-            ...(delegationProofKeyId(standing) !== undefined
-                ? { delegationKeyId: delegationProofKeyId(standing) }
-                : {})
-        });
-    if (!force &&
-        standing !== undefined &&
-        !signerRotted &&
-        !zcapExpiring({
-            ...(standing.expires !== undefined
-                ? { expires: standing.expires }
-                : {}),
+    if (standing !== undefined &&
+        !standingZcapStale({
+            zcap: standing,
+            ...(accountDoc !== undefined ? { doc: accountDoc } : {}),
+            retiringKeyMultibases,
             ...(now !== undefined ? { now } : {})
         })) {
-        return { delegation: standing, renewed: false };
+        return { delegation: standing, renewed: false, published };
     }
     // The rung refusal precedes the mint: nothing is delegated for a writer
     // who cannot publish the entry that would carry it.
-    const rung = await clientAnnexRung({ ladderSeed, generationId });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    const revealed = published.updateKeys.includes(rung.keyMultibase);
-    if (!revealed && !published.nextKeyHashes.includes(rungHash)) {
-        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither this credential's rung-0 key nor " +
+    const rung = await admitActingRung({
+        ladderSeed,
+        generationId,
+        updateKeys: published.updateKeys,
+        nextKeyHashes: published.nextKeyHashes,
+        message: "client annex: the log commits neither this credential's rung-0 key nor " +
             'its hash; a credential bound mid-generation cannot renew the ' +
             'generation delegation until a writer commits its hash or the next ' +
-            'GC swap does.');
-    }
+            'GC swap does.'
+    });
     await assertCarryOverCommitments({ published });
     const fresh = await mintDelegation({ clientAnnexDid: did });
     const signer = await updateKeySigner({ seed: rung.seed });
@@ -1457,6 +1685,13 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, genera
         })
     });
     await putLogResource({ store, log: updated.log, ifMatch: published.etag });
+    // Advance the pin to what this entry just published, so a host serving the
+    // pre-entry log straight afterwards is refused as a rollback on the next
+    // read (equal-to-pin would otherwise be accepted, and a later stage built on
+    // the stale head would miss this entry).
+    if (pinStore && logId !== undefined) {
+        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
+    }
     return { delegation: fresh, renewed: true };
 }
 /**
@@ -1527,17 +1762,15 @@ async function retireClientAnnexRungOnce({ store, retiredLadderSeed, actingLadde
     }
     // The acting rung must be committed AFTER the retired members are
     // excluded, so the retired credential can never sign its own strike.
-    const acting = await clientAnnexRung({
+    const acting = await admitActingRung({
         ladderSeed: actingLadderSeed,
-        generationId
-    });
-    const actingHash = await deriveNextKeyHash(acting.keyMultibase);
-    const revealed = remainingKeys.includes(acting.keyMultibase);
-    if (!revealed && !remainingHashes.includes(actingHash)) {
-        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither the acting credential's rung-0 " +
+        generationId,
+        updateKeys: remainingKeys,
+        nextKeyHashes: remainingHashes,
+        message: "client annex: the log commits neither the acting credential's rung-0 " +
             'key nor its hash (or it is the retired rung itself); the strike ' +
-            'needs a distinct committed writer -- swap the generation instead.');
-    }
+            'needs a distinct committed writer -- swap the generation instead.'
+    });
     await assertCarryOverCommitments({ published });
     const signer = await updateKeySigner({ seed: acting.seed });
     const updated = await updateDID({
@@ -1617,17 +1850,15 @@ async function commitClientAnnexRungOnce({ store, boundLadderSeed, actingLadderS
         // generation the bound credential itself minted.
         return { committed: false };
     }
-    const acting = await clientAnnexRung({
+    const acting = await admitActingRung({
         ladderSeed: actingLadderSeed,
-        generationId
-    });
-    const actingHash = await deriveNextKeyHash(acting.keyMultibase);
-    const revealed = published.updateKeys.includes(acting.keyMultibase);
-    if (!revealed && !published.nextKeyHashes.includes(actingHash)) {
-        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither the acting credential's rung-0 " +
+        generationId,
+        updateKeys: published.updateKeys,
+        nextKeyHashes: published.nextKeyHashes,
+        message: "client annex: the log commits neither the acting credential's rung-0 " +
             'key nor its hash; a commit entry needs a committed writer -- the ' +
-            'bound credential stays locked out until the next GC swap.');
-    }
+            'bound credential stays locked out until the next GC swap.'
+    });
     await assertCarryOverCommitments({ published });
     const signer = await updateKeySigner({ seed: acting.seed });
     const updated = await updateDID({