@interop/wallet-core 0.66.0 → 0.68.0

package/dist/clientAnnex/log.js

@@ -51,12 +51,10 @@
 import { createDID, deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
 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, assertPublishedLogDid, concludeWithPublishedLog, currentLogParameters, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, pinOfLog, putLogResource, readPublishedLogOrThrow, updateKeySigner, WebvhLogConflictError, withLogConflictRetry } from '../webvh/didWebvh.js';
-import { signAccountEntry } from '../webvh/accountEntry.js';
+import { clientAnnexRung, ladderRung } from './ladder.js';
+import { assertCarryOverCommitments, assertPublishedLogDid, concludeWithPublishedLog, currentLogParameters, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, putLogResource, readPublishedLog, readPublishedLogOrThrow, updateKeySigner, withLogConflictRetry, withThreadedHeadOnce } from '../webvh/didWebvh.js';
+import { accountEntryHead, 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';
@@ -121,27 +119,6 @@ export function assertGenerationId(generationId) {
             'base64url characters).');
     }
 }
-/**
- * The pin-slot key for one annex generation's log -- host-free like every
- * pin-slot key, keyed by the auxiliary Space id and the generation id.
- * A transient session keeps this slot in an in-memory pin store (a
- * client-local pin is the wrong lifetime for a disposable log, and a
- * transient session must not create client-local state on a read); an
- * enrolled client's store clears annex slots when the generation is
- * collected.
- *
- * @param options {object}
- * @param options.spaceId {string}   the auxiliary annex Space's id
- * @param options.generationId {string}   the generation collection's name
- * @returns {string}
- */
-export function clientAnnexLogPinId({ spaceId, generationId }) {
-    return resourceLogPinId({
-        spaceId,
-        collectionId: generationId,
-        resourceId: DID_LOG_RESOURCE
-    });
-}
 /**
  * The WAS-backed store an annex generation's ceremonies read and publish
  * through with controller-tier signing (an enrolled client). A transient
@@ -153,17 +130,20 @@ export function clientAnnexLogPinId({ spaceId, generationId }) {
  * @param options.was {WasClient}
  * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.generationId {string}   the generation collection's name
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pins; the store derives each log's slot
  * @param [options.capability] {IZcap}   an invocation capability every request
  *   rides (the sibling delegation, where the caller is not an enrolled
  *   invoker); absent, requests invoke the root capability
  * @returns {WebvhLogResourceStore}
  */
-export function clientAnnexLogStore({ was, spaceId, generationId, capability }) {
+export function clientAnnexLogStore({ was, spaceId, generationId, pinStore, capability }) {
     assertGenerationId(generationId);
     return wasWebvhLogStore({
         was,
         spaceId,
         collectionId: generationId,
+        pinStore,
         ...(capability !== undefined ? { capability } : {})
     });
 }
@@ -315,6 +295,8 @@ export async function ensureClientAnnexSpace({ was, spaceId, controller }) {
  * @param options.nextKeyHashes {string[]}   every standing credential's
  *   rung-0 hash, the minting credential's included
  * @param options.signer {Signer}   the minting credential's rung-0 signer
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pins; the store derives each log's slot
  * @returns {Promise<PublishedWebvhLog & { generationId: string;
  *   spaceDescription?: SpaceDescription }>}   the published head of the
  *   genesis log, which a stage building the generation's next entry can
@@ -324,7 +306,7 @@ export async function ensureClientAnnexSpace({ was, spaceId, controller }) {
  *   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 }) {
+export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore }) {
     const spaceDescription = await ensureClientAnnexSpace({
         was,
         spaceId,
@@ -338,7 +320,8 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
         generationId,
         updateKeyPublicKeyMultibase,
         nextKeyHashes,
-        signer
+        signer,
+        pinStore
     });
     return { ...published, spaceDescription };
 }
@@ -355,6 +338,8 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
  * @param options.updateKeyPublicKeyMultibase {string}
  * @param options.nextKeyHashes {string[]}
  * @param options.signer {Signer}
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pins; the store derives each log's slot
  * @param [options.capability] {IZcap}   an invocation capability the
  *   collection create and the genesis publish ride (a delegated minter)
  * @returns {Promise<PublishedWebvhLog & { generationId: string }>}   the
@@ -367,7 +352,7 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
  *   for itself rather than degrade its compare-and-swap to an unconditional
  *   write.
  */
-async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, capability }) {
+async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore, capability }) {
     // The generation collection must exist before its first resource PUT; a
     // 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
@@ -393,6 +378,7 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
             was,
             spaceId,
             generationId,
+            pinStore,
             ...(capability !== undefined ? { capability } : {})
         }),
         log: created.log,
@@ -427,6 +413,8 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
  *   only when the Space does not exist yet
  * @param options.ladderSeed {Uint8Array}   the minting credential's ladder
  *   seed, from its unlock record
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pins; the store derives each log's slot
  * @param [options.extraNextKeyHashes] {string[]}   the OTHER standing
  *   credentials' rung-0 hashes for this generation id, when the account has
  *   more
@@ -446,7 +434,7 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
  *   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 }) {
+export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, pinStore, extraNextKeyHashes = [], capability }) {
     const spaceDescription = capability === undefined
         ? await ensureClientAnnexSpace({ was, spaceId, controller })
         : undefined;
@@ -463,6 +451,7 @@ export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, s
             ...extraNextKeyHashes
         ],
         signer: await updateKeySigner({ seed: rung.seed }),
+        pinStore,
         ...(capability !== undefined ? { capability } : {})
     });
     return {
@@ -624,8 +613,8 @@ export const DELEGATED_CLIENTS_DELEGATION_ACTIONS = ['GET', 'PUT'];
 /**
  * The sibling delegation's lifetime: the house standing-zcap value (one
  * year; see `standingZcap.ts`). It rots on exactly the account bridge's axis
- * -- same signer, same current-key-set rule, same renewal window -- so the
- * re-mint pass that refreshes the bridge refreshes it too.
+ * -- same signer, same current-key-set rule, same renewal window -- so
+ * whatever refreshes the bridge refreshes it too.
  */
 export const DELEGATED_CLIENTS_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
 /**
@@ -676,15 +665,14 @@ export async function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl,
     }));
 }
 /**
- * Builds the annex-side sibling-delegation minter the enrolled-client record
- * re-mint orchestrator (`recovery/remintRecoveryDelegations`) takes as an
- * injected closure -- the boundary keeping that base orchestrator free of
- * annex imports. The returned closure reads the auxiliary annex Space id off
- * the verified document's delegated-clients service entry (the annex DID
- * string embeds it) and mints a fresh {@link mintDelegatedClientsDelegation}
- * to the named controller; it resolves `undefined` while the document points
- * at no generation, which the orchestrator reads as "carry the old sealed
- * member verbatim".
+ * Builds the annex-side sibling-delegation minter a record re-bind takes as
+ * an injected closure -- the boundary keeping a caller outside this subpath
+ * free of annex imports. The returned closure reads the auxiliary annex Space
+ * id off the verified document's delegated-clients service entry (the annex
+ * DID string embeds it) and mints a fresh
+ * {@link mintDelegatedClientsDelegation} to the named controller; it resolves
+ * `undefined` while the document points at no generation, which a caller
+ * reads as "carry the old sealed member verbatim".
  * @param options {object}
  * @param options.doc {object}   the locally verified account document
  * @param options.zcapClient {ZcapClient}   the acting client's promoted
@@ -963,7 +951,7 @@ export async function revokeTreatingAlreadyRevokedAsSuccess({ revoke, delegation
         await revoke(delegation);
     }
     catch (err) {
-        if (err.name === 'ValidationError') {
+        if (err?.name === 'ValidationError') {
             return;
         }
         throw err;
@@ -1086,25 +1074,51 @@ async function admitActingRung({ ladderSeed, generationId, updateKeys, nextKeyHa
 /**
  * Reads and resolves the published annex log through the narrow seam, or
  * throws when the generation's `did.jsonl` is missing (an unpointed or
- * deleted generation -- nothing to enroll into).
+ * deleted generation -- nothing to enroll into). The read runs under the
+ * store's own chain-head pin.
  *
  * @param options {object}
  * @param options.store {ClientAnnexWriteStore}
  * @param [options.expectedDid] {string}
- * @param [options.pinStore] {ResourceLogPinStore}
- * @param [options.logId] {string}
  * @returns {Promise<PublishedWebvhLog>}
  */
-async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }) {
+async function readClientAnnexLogOrThrow({ store, expectedDid }) {
     return readPublishedLogOrThrow({
         idStore: store,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {}),
         missingMessage: 'client annex: did.jsonl is missing; the generation was never minted ' +
             'or has been collected.'
     });
 }
+/**
+ * Reads and resolves a generation's published annex log, or resolves
+ * `undefined` when its `did.jsonl` does not exist -- even under a held pin.
+ *
+ * The pinned read refuses an absent log under a held pin as a `rollback`,
+ * which is right for the account log: a full truncation is never "not yet
+ * provisioned". A generation is different. It is deleted by design (the GC
+ * collect, an abandoned annex Space), and every arm that tells a dead or
+ * absent generation from a live one -- the readiness ensure's re-point, the
+ * last-client transition's `log-unreadable` escape, the GC's orphan collect
+ * -- is gated on that absence. A client that read the generation earlier and
+ * still holds its pin would otherwise be refused exactly where it must mend,
+ * with nothing that ever drops the slot. So the read runs in the pinned
+ * read's absence-tolerant mode: a genuinely absent log is absence (the pin
+ * left standing), and a log that is served and falls behind the pin stays
+ * refused, so a served prefix is never mistaken for a missing log.
+ *
+ * @param options {object}
+ * @param options.store {ClientAnnexWriteStore}
+ * @param [options.expectedDid] {string}
+ * @returns {Promise<PublishedWebvhLog | undefined>}
+ */
+export async function readClientAnnexLogOrAbsent({ store, expectedDid }) {
+    return readPublishedLog({
+        idStore: store,
+        absentUnderPin: 'absent',
+        ...(expectedDid !== undefined ? { expectedDid } : {})
+    });
+}
 /**
  * TRANSIENT ENROLLMENT: publishes one per-visit verification method into a
  * annex generation's log -- one atomic entry, signed by the writing
@@ -1162,11 +1176,8 @@ async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }
  *   by genesis (a genesis-embedded signed zcap can never verify -- its
  *   `controller` embeds the SCID the genesis hash derives from)
  * @param [options.expectedDid] {string}   the annex DID the log must
- *   resolve to, from the account document's pointer
- * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
- *   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
+ *   resolve to, from the account document's pointer. The read and the publish
+ *   run under the store's own chain-head pin
  * @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
@@ -1178,23 +1189,10 @@ async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
 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));
+    return withThreadedHeadOnce({
+        published: threadedHead,
+        attempt: published => enrollClientAnnexTransientClientOnce({ ...rest, published })
+    });
 }
 /**
  * One attempt of {@link enrollClientAnnexTransientClient}, re-invoked by the
@@ -1204,7 +1202,7 @@ export async function enrollClientAnnexTransientClient({ published: threadedHead
  * @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, published: alreadyRead }) {
+async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generationId, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, published: alreadyRead }) {
     assertGenerationId(generationId);
     const published = alreadyRead !== undefined
         ? assertPublishedLogDid({
@@ -1213,9 +1211,7 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
         })
         : await readClientAnnexLogOrThrow({
             store,
-            ...(expectedDid !== undefined ? { expectedDid } : {}),
-            ...(pinStore !== undefined ? { pinStore } : {}),
-            ...(logId !== undefined ? { logId } : {})
+            ...(expectedDid !== undefined ? { expectedDid } : {})
         });
     const { did, doc } = published;
     const vmId = `${did}#${transientKeyMultibase}`;
@@ -1288,24 +1284,28 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
         ...(services !== undefined ? { services } : {})
     });
     // The log only -- an annex has no did:web projection -- conditional on
-    // the read this entry was built on.
+    // the read this entry was built on. The publish advances the store's
+    // chain-head pin to what it just wrote, so a host serving the pre-entry log
+    // straight afterwards is refused as a rollback on the next read.
     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 };
 }
 /**
  * Points the account document's delegated-clients service entry at a
  * annex DID -- the first install after a generation's genesis, and the GC
- * swap's re-point alike. One ordinary document-update entry, signed by an
- * enrolled client's active update key; the annex log always
- * publishes FIRST (see {@link mintClientAnnexGeneration}), so a tear leaves an
- * unpointed, authorization-inert generation, never a dangling pointer.
+ * swap's re-point alike. One ordinary document-update entry on either signer
+ * arm; the annex log always publishes FIRST (see
+ * {@link mintClientAnnexGeneration}), so a tear leaves an unpointed,
+ * authorization-inert generation, never a dangling pointer.
+ *
+ * On the ladder arm the entry is the pointer move a credential-only caller
+ * makes (the transient readiness pass, the establishment's stage 3): the
+ * seam attributes the ladder's current rung per attempt, the rung reveals
+ * itself in the entry it signs, and when it stood only committed the entry
+ * also commits the next rung's hash, so one entry does what a reveal entry
+ * followed by a client-signed pointer entry used to. A lost race re-runs the
+ * attribution from the winner's head, which is what climbs to the winner's
+ * committed rung (retry-up-the-ladder).
  *
  * An existing delegated-clients entry is re-pointed in place, its fragment id
  * preserved verbatim (the id is non-semantic and stable); absent one, a fresh
@@ -1313,34 +1313,34 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
  * 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 (and, unless `logOnly`, it republishes `did.json` from
- * the resolved log, which the enrolled-client caller has the authority to
+ * the resolved log, which a controller-invoking 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.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.signer {AccountLogSigner}   who signs the pointer entry: an
+ *   enrolled client's own update-key seeds (`{ kind: 'client', updateKeys }`,
+ *   the GC swap's re-point and an enrolled client's stage-3 fold), or a
+ *   standing credential's ladder seed (`{ kind: 'ladder', ladderSeed }`),
+ *   under which the acting rung is attributed from the head each attempt
+ *   builds on
  * @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
- * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
- *   pins for the account log
- * @param [options.logId] {string}   the account log's pin-slot key, from
- *   `accountLogPinId({ spaceId })`; required whenever a `pinStore` is
- *   supplied
+ *   resolve to, from the account pointer. The read and the publish run under
+ *   the store's own chain-head pin
  * @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 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`
+ *   `did.json` projection. Defaults per arm, as {@link signAccountEntry}
+ *   does: `true` on the ladder arm, since a transient visit writes through
+ *   the record's bridge delegation, whose narrow scope covers nothing but the
+ *   log, and `false` on the client arm. The establishment's stage 3, a ladder
+ *   signer over a root-invoking store, passes `false` explicitly. A lagging
+ *   projection is republished when 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
@@ -1351,55 +1351,36 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generat
  *   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
+ *   published: PublishedWebvhLog, rung?: LadderRung }>}   `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. `rung` stands on
+ *   the ladder arm alone: the rung the entry was signed with, or, when the
+ *   document already pointed, the ladder's currently attributed rung
  */
 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));
+    return withThreadedHeadOnce({
+        published: threadedHead,
+        attempt: published => setDelegatedClientsPointerOnce({ ...rest, published })
+    });
 }
 /**
  * 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
- * 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 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
- * loop retries -- rather than as the not-authorized refusal a fresh read of
- * the winner's head would produce.
+ * function's conflict retry and exported for a caller that runs its own
+ * retry around it.
+ *
+ * A caller that already read the head 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} for the retry to re-run.
  *
  * @param options {object}   see {@link setDelegatedClientsPointer}, plus:
  * @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,
- *   published: PublishedWebvhLog }>}
+ * @returns {Promise<PointerEntryOutcome>}
  */
-export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAnnexDid, expectedDid, pinStore, logId, logOnly = false, published: alreadyRead }) {
+export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAnnexDid, expectedDid, logOnly = signer.kind === 'ladder', published: alreadyRead }) {
     // Refuses a malformed target before anything is read or written.
     clientAnnexDidParts({ did: clientAnnexDid });
     let settled;
@@ -1408,15 +1389,13 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
         signer,
         ...(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 }) => {
+        build: async ({ published, rung, state }) => {
             const { did, doc } = published;
             if (delegatedClientsPointer({ doc }) === clientAnnexDid) {
-                if (!logOnly && signer.kind === 'client') {
+                if (!logOnly) {
                     await concludeWithPublishedLog({ idStore, published });
                 }
                 // The head verbatim: the projection PUT touches no log, so this
@@ -1424,7 +1403,20 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
                 settled = { did, doc, published };
                 return undefined;
             }
+            // A ladder rung standing only as a committed hash reveals itself
+            // through the seam's reveal union; this entry commits the next rung
+            // beside it, so the ladder stays prerotated past the move. An already
+            // revealed rung re-states the parameters verbatim.
+            const commitHashes = signer.kind === 'ladder' && state === 'committed'
+                ? [
+                    await deriveNextKeyHash((await ladderRung({
+                        ladderSeed: signer.ladderSeed,
+                        index: rung.index + 1
+                    })).keyMultibase)
+                ]
+                : undefined;
             return {
+                ...(commitHashes !== undefined ? { commitHashes } : {}),
                 services: servicesPointedAtClientAnnex({
                     doc,
                     accountDid: did,
@@ -1433,8 +1425,9 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
             };
         }
     });
+    const ladderRungPart = outcome.rung !== undefined ? { rung: outcome.rung } : {};
     if (settled) {
-        return settled;
+        return { ...settled, ...ladderRungPart };
     }
     const updated = outcome.updated;
     return {
@@ -1443,16 +1436,8 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
         // 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 } : {})
-        }
+        published: accountEntryHead({ outcome }),
+        ...ladderRungPart
     };
 }
 /**
@@ -1484,9 +1469,6 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
  *   {@link enrollClientAnnexTransientClient}). The closure receives whichever
  *   annex DID the round enrolls into, so a GC-race re-enroll mints for
  *   the fresh generation
- * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins for the
- *   generation logs (a transient session passes an in-memory store); slot
- *   keys are derived per generation with {@link clientAnnexLogPinId}
  * @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)
@@ -1498,7 +1480,7 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
  *   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, published: threadedHead }) {
+export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, maxRounds = 3, published: threadedHead }) {
     let accountDoc = await readAccountDocument();
     for (let round = 0; round < maxRounds; round++) {
         const clientAnnexDid = delegatedClientsPointer({ doc: accountDoc });
@@ -1506,9 +1488,7 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
             throw new Error('client annex: the account document carries no delegated-clients ' +
                 'service entry; no generation exists to enroll into.');
         }
-        const { spaceId, generationId } = clientAnnexDidParts({
-            did: clientAnnexDid
-        });
+        const { 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.
@@ -1524,9 +1504,6 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
             ...(head !== undefined ? { published: head } : {}),
             ...(mintDelegation !== undefined
                 ? { mintGenerationDelegation: mintDelegation }
-                : {}),
-            ...(pinStore !== undefined
-                ? { pinStore, logId: clientAnnexLogPinId({ spaceId, generationId }) }
                 : {})
         });
         // The GC-race re-read: an unchanged pointer means the enrollment stands
@@ -1544,9 +1521,10 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * The fresh-generation block every separate-pointer-entry caller runs: mint
  * a generation in the annex Space, install its generation delegation, then
  * append the account document's pointer entry naming it. The pointer write is
- * the injected step (`point`): the establishment signs it as a client under
- * a rung the caller attributed, the transient visit moves it as the ladder
- * with its reveal-and-retry form. A caller with a step that must land
+ * the injected step (`point`): an enrolled client signs it under its own
+ * update keys, and a credential-only caller (the establishment, the
+ * transient visit) moves it as the ladder, one rung-signed entry per attempt. A
+ * caller with a step that must land
  * between the install and the pointer entry (the establishment's bootstrap
  * arm, whose Space still answers to its creation controller until it flips
  * it to the account DID) supplies `beforePointerEntry`.
@@ -1572,25 +1550,26 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  *   `({ clientAnnexDid }) => Promise<IZcap>`
  * @param options.point {Function}   `(clientAnnexDid) => Promise<T>` -- the
  *   pointer entry, whose result rides the return verbatim
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pins; the store derives each log's slot
  * @param [options.capability] {IZcap}   the sibling delegation the annex
  *   writes ride, for a caller holding a standing invocation authority
  * @param [options.beforePointerEntry] {Function}
  *   `({ minted }) => Promise<void>` -- runs after the install and before the
  *   pointer entry, with the mint's published head (its `spaceDescription`
  *   included)
- * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins; the
- *   generation's slot is derived here
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @returns {Promise<{ clientAnnexDid: string, generationDelegation: IZcap,
  *   pointed: T }>}
  */
-export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, mintGenerationDelegation, point, capability, beforePointerEntry, pinStore, now }) {
+export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, mintGenerationDelegation, point, pinStore, capability, beforePointerEntry, now }) {
     const minted = await mintCredentialClientAnnexGeneration({
         was,
         wasServerUrl,
         spaceId,
         controller,
         ladderSeed,
+        pinStore,
         ...(capability !== undefined ? { capability } : {})
     });
     const ensured = await ensureGenerationDelegationCurrent({
@@ -1598,6 +1577,7 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
             was,
             spaceId,
             generationId: minted.generationId,
+            pinStore,
             ...(capability !== undefined ? { capability } : {})
         }),
         ladderSeed,
@@ -1605,15 +1585,6 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
         mintGenerationDelegation,
         expectedDid: minted.did,
         ...(minted.etag !== undefined ? { published: minted } : {}),
-        ...(pinStore !== undefined
-            ? {
-                pinStore,
-                logId: clientAnnexLogPinId({
-                    spaceId,
-                    generationId: minted.generationId
-                })
-            }
-            : {}),
         ...(now !== undefined ? { now } : {})
     });
     if (beforePointerEntry !== undefined) {
@@ -1672,11 +1643,8 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
  *   `({ clientAnnexDid }) => Promise<IZcap>` -- mints the replacement
  *   delegation (ladder-signed in a transient session)
  * @param [options.expectedDid] {string}   the annex DID the log must
- *   resolve to, from the account document's pointer
- * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
- *   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
+ *   resolve to, from the account document's pointer. The read and the publish
+ *   run under the store's own chain-head pin
  * @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)
@@ -1707,23 +1675,10 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
  *   wanting one reads for itself
  */
 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));
+    return withThreadedHeadOnce({
+        published: threadedHead,
+        attempt: published => ensureGenerationDelegationCurrentOnce({ ...rest, published })
+    });
 }
 /**
  * One attempt of {@link ensureGenerationDelegationCurrent}, re-invoked by the
@@ -1734,7 +1689,7 @@ export async function ensureGenerationDelegationCurrent({ published: threadedHea
  * @returns {Promise<{ delegation: IZcap, renewed: boolean,
  *   published?: PublishedWebvhLog }>}
  */
-async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, generationId, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, accountDoc, retiringKeyMultibases = [], now, published: alreadyRead }) {
+async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, generationId, mintGenerationDelegation: mintDelegation, expectedDid, accountDoc, retiringKeyMultibases = [], now, published: alreadyRead }) {
     assertGenerationId(generationId);
     const published = alreadyRead !== undefined
         ? assertPublishedLogDid({
@@ -1743,9 +1698,7 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, genera
         })
         : await readClientAnnexLogOrThrow({
             store,
-            ...(expectedDid !== undefined ? { expectedDid } : {}),
-            ...(pinStore !== undefined ? { pinStore } : {}),
-            ...(logId !== undefined ? { logId } : {})
+            ...(expectedDid !== undefined ? { expectedDid } : {})
         });
     const { did, doc } = published;
     const standing = embeddedGenerationDelegation({ doc });
@@ -1788,14 +1741,10 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, genera
             delegation: fresh
         })
     });
+    // The publish advances the store's chain-head pin to what it just wrote, so
+    // a host serving the pre-entry log straight afterwards is refused as a
+    // rollback on the next read.
     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 };
 }
 /**
@@ -1826,10 +1775,8 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, genera
  *   ladder seed, whose committed rung 0 signs the strike entry
  * @param options.generationId {string}   the generation collection's name
  * @param [options.expectedDid] {string}   the annex DID the log must
- *   resolve to, from the account document's pointer
- * @param [options.pinStore] {ResourceLogPinStore}
- * @param [options.logId] {string}   the generation's pin-slot key, from
- *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ *   resolve to, from the account document's pointer. The read and the publish
+ *   run under the store's own chain-head pin
  * @returns {Promise<{ struck: boolean }>}
  */
 export async function retireClientAnnexRung(options) {
@@ -1843,13 +1790,11 @@ export async function retireClientAnnexRung(options) {
  * @param options {object}   see {@link retireClientAnnexRung}
  * @returns {Promise<{ struck: boolean }>}
  */
-async function retireClientAnnexRungOnce({ store, retiredLadderSeed, actingLadderSeed, generationId, expectedDid, pinStore, logId }) {
+async function retireClientAnnexRungOnce({ store, retiredLadderSeed, actingLadderSeed, generationId, expectedDid }) {
     assertGenerationId(generationId);
     const published = await readClientAnnexLogOrThrow({
         store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
+        ...(expectedDid !== undefined ? { expectedDid } : {})
     });
     const retired = await clientAnnexRung({
         ladderSeed: retiredLadderSeed,
@@ -1918,10 +1863,8 @@ async function retireClientAnnexRungOnce({ store, retiredLadderSeed, actingLadde
  *   login credential's ladder seed, whose committed rung 0 signs the entry
  * @param options.generationId {string}   the generation collection's name
  * @param [options.expectedDid] {string}   the annex DID the log must
- *   resolve to, from the account document's pointer
- * @param [options.pinStore] {ResourceLogPinStore}
- * @param [options.logId] {string}   the generation's pin-slot key, from
- *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ *   resolve to, from the account document's pointer. The read and the publish
+ *   run under the store's own chain-head pin
  * @returns {Promise<{ committed: boolean }>}
  */
 export async function commitClientAnnexRung(options) {
@@ -1935,13 +1878,11 @@ export async function commitClientAnnexRung(options) {
  * @param options {object}   see {@link commitClientAnnexRung}
  * @returns {Promise<{ committed: boolean }>}
  */
-async function commitClientAnnexRungOnce({ store, boundLadderSeed, actingLadderSeed, generationId, expectedDid, pinStore, logId }) {
+async function commitClientAnnexRungOnce({ store, boundLadderSeed, actingLadderSeed, generationId, expectedDid }) {
     assertGenerationId(generationId);
     const published = await readClientAnnexLogOrThrow({
         store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore !== undefined ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
+        ...(expectedDid !== undefined ? { expectedDid } : {})
     });
     const bound = await clientAnnexRung({
         ladderSeed: boundLadderSeed,