@interop/wallet-core 0.61.0 → 0.65.0

package/dist/clientAnnex/heal.js

@@ -1,12 +1,30 @@
 import { WasClient } from '@interop/was-client';
-import { effectiveParameters, readPublishedLog } from '../webvh/didWebvh.js';
-import { delegationKeyInDocument, ladderVmIds } from '../webvh/listClients.js';
-import { delegationProofKeyId, zcapExpiring } from '../webvh/standingZcap.js';
+import { spacePath } from '@interop/was-client/paths';
+import { currentLogParameters, readPublishedLog, readPublishedLogOrThrow, WebvhLogConflictError, withLogConflictRetry } from '../webvh/didWebvh.js';
+import { ladderVmIds } from '../resourceLog/document.js';
+import { standingZcapStale } from '../webvh/standingZcap.js';
+import { delegateLogWrite } from '../recovery/recoveryDelegation.js';
 import { accountLogPinId } from '../webvh/verifyLog.js';
 import { mintSpaceId } from '../genesis/accountGenesis.js';
 import { attributeLadderRung, ladderRung, ladderVmKeyMultibase } from './ladder.js';
+import { revealLadderRungWebvh } from './ladderAnchored.js';
 import { ladderVmAgent, ladderVmZcapClient } from './zcap.js';
-import { clientAnnexDidParts, clientAnnexLogPinId, clientAnnexLogStore, delegatedClientsDelegationSpaceId, delegatedClientsPointer, ensureGenerationDelegationCurrent, mintCredentialClientAnnexGeneration, mintDelegatedClientsDelegation, mintGenerationDelegation, setDelegatedClientsPointer } from './log.js';
+import { mintSpaceRootVerbCapability } from './spaceCapability.js';
+import { clientAnnexDidParts, clientAnnexLogPinId, clientAnnexLogStore, delegatedClientsDelegationSpaceId, delegatedClientsPointer, ensureClientAnnexSpace, ensureGenerationDelegationCurrent, mintCredentialClientAnnexGeneration, mintDelegatedClientsDelegation, mintGenerationDelegation, setDelegatedClientsPointerOnce } from './log.js';
+/**
+ * The HTTP status a raw signed request's rejection carries, when it carries
+ * one. `WasClient.request` applies no error mapping, so the status is all a
+ * caller has to dispatch on, and different transports hang it in different
+ * places (`status`, or `response.status`).
+ *
+ * @param err {unknown}
+ * @returns {number | undefined}
+ */
+function rawRequestStatus(err) {
+    const raw = err;
+    const status = raw?.status ?? raw?.response?.status;
+    return typeof status === 'number' ? status : undefined;
+}
 /**
  * The typed refusal of {@link ensureCredentialClientAnnexGeneration}: the
  * account is not in a shape this visit can mend, and nothing was written.
@@ -81,13 +99,18 @@ export function ladderSignedGenerationDelegationMinter({ accountDid, ladderSeed,
  *   -- the storage client for the fresh-Space arm, signing as the ladder
  *   VM's bare did:key (the caller wires the transport; the agent is derived
  *   here from the ladder seed)
- * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store (a
- *   bridge-delegated one suffices: pointer entries publish with
- *   `logOnly: true`)
+ * @param options.delegation {IZcap}   the record's bridge delegation (PUT on
+ *   the account's `did.jsonl`), renewed here when it is stale
+ * @param options.idStoreFor {Function}
+ *   `({ delegation }) => WebvhIdStore` -- builds the ACCOUNT log's store over
+ *   the usable bridge (a bridge-delegated store suffices: pointer entries
+ *   publish with `logOnly: true`). Called once, after the bridge renewal, so
+ *   a pointer entry never rides a lapsed delegation
  * @param options.onRebindRecord {Function}
- *   `({ delegatedClients }) => Promise<void>` -- REQUIRED: re-seals the
- *   unlock record with the fresh sibling delegation; called whenever one was
- *   minted, after the generation and pointer are durable
+ *   `({ delegation, delegatedClients }) => Promise<void>` -- REQUIRED:
+ *   re-seals the unlock record with the usable bridge and sibling
+ *   delegations; called whenever either was freshly minted, after the
+ *   generation and pointer are durable
  * @param [options.delegatedClients] {IZcap}   the record's sibling
  *   delegation, when the record carries one
  * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
@@ -101,7 +124,8 @@ export function ensureCredentialClientAnnexGeneration(options) {
     // into the record would strand the very credential this ensure serves.
     if (typeof options.onRebindRecord !== 'function') {
         throw new TypeError('ensureCredentialClientAnnexGeneration requires onRebindRecord: a ' +
-            'fresh sibling delegation must be re-sealed into the unlock record.');
+            'fresh bridge or sibling delegation must be re-sealed into the ' +
+            'unlock record.');
     }
     return ensureCredentialClientAnnexGenerationChecked(options);
 }
@@ -111,14 +135,17 @@ export function ensureCredentialClientAnnexGeneration(options) {
  * @param options {object}   see {@link ensureCredentialClientAnnexGeneration}
  * @returns {Promise<ClientAnnexGenerationEnsureOutcome>}
  */
-async function ensureCredentialClientAnnexGenerationChecked({ wasServerUrl, spaceId, account, ladderSeed, standingClient, bootstrapWasFor, idStore, onRebindRecord, delegatedClients, pinStore, now }) {
+async function ensureCredentialClientAnnexGenerationChecked({ wasServerUrl, spaceId, account, ladderSeed, standingClient, bootstrapWasFor, delegation, idStoreFor, onRebindRecord, delegatedClients, pinStore, now }) {
     // The gate: everything below signs as the ladder (the delegations as the
     // ladder VM, the annex entries as its per-generation rung), so unless THIS
     // ladder's VM stands in the document under the ladder-VM relation
     // asymmetry (`capabilityDelegation` without `capabilityInvocation` -- the
     // authority the mends actually exercise, which mere key presence says
     // nothing about), every mend is unverifiable. The honest refusal, before
-    // anything is written.
+    // anything is written. A standing credential's VM stands whether or not the
+    // account has enrolled clients, so this fires only for a document that
+    // never carried it -- a torn establishment, or another credential's
+    // account.
     const vmKey = await ladderVmKeyMultibase({ ladderSeed });
     if (!ladderVmIds({ doc: account.doc }).includes(`${account.did}#${vmKey}`)) {
         throw new ClientAnnexGenerationUnavailableError({
@@ -144,231 +171,420 @@ async function ensureCredentialClientAnnexGenerationChecked({ wasServerUrl, spac
         spaceId,
         ...(now !== undefined ? { now } : {})
     });
-    if (annexSpaceId === undefined) {
-        // THE FRESH-SPACE ARM: neither the pointer nor a sibling names a Space.
-        // The pre-flight attribution runs before anything is minted; the stage
-        // order mirrors the credential-anchored genesis exactly.
-        const updateKeys = await pointerEntryUpdateKeys({
-            ladderSeed,
-            log: account.log
+    // THE BRIDGE RENEWAL, before any arm. The bridge is the credential's one
+    // write path into the account log, and both minting arms end in a pointer
+    // entry that rides it. A stale one is replaced with a ladder-VM-signed
+    // delegation (the gate above proved the VM a document verification
+    // method), and the caller's account-log store is built over whichever
+    // bridge is usable.
+    let bridgeReminted = false;
+    let usableBridge = delegation;
+    if (standingZcapStale({
+        zcap: delegation,
+        doc: account.doc,
+        ...(now !== undefined ? { now } : {})
+    })) {
+        usableBridge = await delegateLogWrite({
+            zcapClient: ladderClient,
+            pointer: { did: account.did, spaceId, host: wasServerUrl },
+            recoveryClientDid: standingClient.did,
+            ...(now !== undefined ? { now } : {})
         });
+        bridgeReminted = true;
+    }
+    const idStore = idStoreFor({ delegation: usableBridge });
+    /**
+     * The record re-seal, through the required `onRebindRecord` seam: the one
+     * call site for every arm, run once the generation and pointer are
+     * durable. It fires whenever either recorded delegation was freshly
+     * minted, and grades a failure by which one that was. A fresh sibling
+     * nothing re-seals would strand the credential, so that throw propagates.
+     * A bridge-only renewal needs nothing from the re-seal: the fresh bridge
+     * is minted offline and already served this visit, so a lost re-seal
+     * leaves no wrong state behind and the next visit re-mints. It is reported
+     * on the outcome instead.
+     *
+     * @param options {object}
+     * @param options.delegatedClients {IZcap}   the usable sibling delegation
+     * @param options.siblingReminted {boolean}   whether that sibling is fresh
+     * @returns {Promise<object>}   the outcome's `bridgeResealError` member,
+     *   present only when a bridge-only re-seal failed
+     */
+    async function resealRecord({ delegatedClients: usableSibling, siblingReminted }) {
+        if (!siblingReminted && !bridgeReminted) {
+            return {};
+        }
+        try {
+            await onRebindRecord({
+                delegation: usableBridge,
+                delegatedClients: usableSibling
+            });
+        }
+        catch (err) {
+            if (siblingReminted) {
+                throw err;
+            }
+            return { bridgeResealError: err };
+        }
+        return {};
+    }
+    /**
+     * The fresh-Space stage, controller-first past the create. The create
+     * itself must name the ladder VM's bare did:key: a storage server
+     * authorizes a Space create against the controller the request body names,
+     * and a root invocation must be signed by that very DID, so a create
+     * naming the account did:webvh is refused. The controller is flipped to
+     * the account DID in the very next request, before anything publishes into
+     * the Space.
+     *
+     * So the stranding window is one request wide. Inside it the stranded
+     * Space is did:key-controlled, which no server orphan sweep can reap,
+     * since a did:key resolves from its own bytes forever. Past the flip it is
+     * account-controlled and reapable. Narrowing the window to that one
+     * request is what this ordering buys; it does not close it.
+     *
+     * The flip preceding the generation mint is load-bearing rather than
+     * cosmetic. The mint and the delegation embed ride the ladder-signed
+     * sibling delegation, and the server admits that chain only once the
+     * Space's controller is the account DID whose document lists the ladder
+     * VM. Minting first and flipping afterwards would need the bootstrap key's
+     * own root invocations, which is the ordering this stage replaced.
+     *
+     * @returns {Promise<string>}   the fresh auxiliary Space's id
+     */
+    async function mintFreshAnnexSpace() {
         const freshSpaceId = mintSpaceId();
         const keyAgent = await ladderVmAgent({ ladderSeed });
         const bootstrapWas = bootstrapWasFor({ keyAgent });
-        const minted = await mintCredentialClientAnnexGeneration({
+        const created = await ensureClientAnnexSpace({
             was: bootstrapWas,
-            wasServerUrl,
             spaceId: freshSpaceId,
-            controller: keyAgent.id,
-            ladderSeed
+            controller: keyAgent.id
+        });
+        // The create's own answer is the current Description, so the flip carries
+        // it as `current` rather than re-reading what this call just wrote.
+        await bootstrapWas
+            .space(freshSpaceId)
+            .configure({ current: created, controller: account.did, force: true });
+        return freshSpaceId;
+    }
+    /**
+     * One Space Description read, judged by its HTTP STATUS alone. A 404 is
+     * `'not-found'`; a 2xx is `'present'`, whatever its body says, since a
+     * Space served with an unreadable body is a present Space and reading it
+     * as absence is exactly what would re-point a live account. Every other
+     * answer -- a transport failure, a 5xx, a 4xx that is not 404 -- throws,
+     * so nothing but a real 404 can ever reach the absence decision.
+     *
+     * The read goes through the raw signed request rather than the
+     * `describe()` handle, whose null-on-404 translation also swallows 401 and
+     * 403 and an unparseable body.
+     *
+     * @param options {object}
+     * @param options.was {WasClient}   the client whose signer invokes
+     * @param options.annexSpaceId {string}
+     * @param [options.capability] {IZcap}   the attached capability; absent
+     *   means a root invocation
+     * @returns {Promise<'present' | 'not-found'>}
+     */
+    async function readSpaceDescription({ was, annexSpaceId, capability }) {
+        let status;
+        try {
+            const response = await was.request({
+                path: spacePath(annexSpaceId),
+                method: 'GET',
+                ...(capability !== undefined ? { capability } : {})
+            });
+            status = response.status;
+        }
+        catch (err) {
+            if (rawRequestStatus(err) === 404) {
+                return 'not-found';
+            }
+            throw err;
+        }
+        if (status >= 200 && status < 300) {
+            return 'present';
+        }
+        if (status === 404) {
+            return 'not-found';
+        }
+        throw new Error(`client annex: the Space Description read for "${annexSpaceId}" ` +
+            `answered ${status}; the visit cannot tell whether the Space is gone.`);
+    }
+    /**
+     * Whether the auxiliary Space itself is gone from the server, asked only
+     * when the pointed generation's log did not read back. A storage server
+     * masks an unauthorized read as the same 404 an absent Space answers, so
+     * ONE 404 is not absence: it is "absent, or this reader has no authority
+     * here". Absence is therefore corroborated by two independent readers, and
+     * the Space is gone only when both answer a real 404.
+     *
+     * The first reader is a ladder-signed GET-only child of the Space's own
+     * root, which the account DID's document backs. The sibling delegation
+     * cannot carry the question: it targets the items subtree beneath the
+     * Space and says nothing about the Space Description.
+     *
+     * The second is a root invocation as the ladder VM's BARE did:key, the
+     * controller a torn establishment leaves behind when its flip never
+     * landed. That reader answers 2xx on exactly the Space the first reader
+     * has no authority over, so the pair covers both controllers a live annex
+     * Space of this credential's can have.
+     *
+     * The residual bound, stated because no read can close it: a server that
+     * does not admit the ladder delegation clause's single-verb predicate
+     * refuses the first probe with the same masked 404, and on an
+     * account-controlled Space the second probe is refused too. Both readers
+     * then say `'not-found'` about a live Space. That is a server older than
+     * the one this arm was built against, and the arm's cost there is a
+     * re-point of a live generation.
+     *
+     * @param options {object}
+     * @param options.annexSpaceId {string}
+     * @param options.was {WasClient}   the standing client's storage client
+     * @returns {Promise<boolean>}
+     */
+    async function annexSpaceAbsent({ annexSpaceId, was }) {
+        const probe = await mintSpaceRootVerbCapability({
+            zcapClient: ladderClient,
+            storageServerUrl: wasServerUrl,
+            spaceId: annexSpaceId,
+            verb: 'GET',
+            controller: standingClient.did,
+            ...(now !== undefined ? { now } : {})
+        });
+        const delegated = await readSpaceDescription({
+            was,
+            annexSpaceId,
+            capability: probe
+        });
+        if (delegated === 'present') {
+            return false;
+        }
+        const bootstrapWas = bootstrapWasFor({
+            keyAgent: await ladderVmAgent({ ladderSeed })
+        });
+        const asBootstrap = await readSpaceDescription({
+            was: bootstrapWas,
+            annexSpaceId
+        });
+        return asBootstrap === 'not-found';
+    }
+    let spaceMinted = false;
+    let pointedSpaceMissing = false;
+    /**
+     * The arms that run inside one auxiliary Space: the sibling delegation,
+     * the pointed generation's renewal, and the fresh-generation mint with its
+     * pointer move. Called once on the resolved Space, and once more on a
+     * fresh Space when the pointed one turns out to be gone -- the replacement
+     * is decided before any write, so nothing is stranded by the re-run.
+     *
+     * @param options {object}
+     * @param options.annexSpaceId {string}   the Space this run works in
+     * @param options.allowSpaceReplacement {boolean}   whether an absent
+     *   pointed generation may be checked against the Space itself, and a
+     *   fresh Space minted when the Space is gone. False on the run that
+     *   already works in a Space this visit created
+     * @param [options.pointer] {string}   the pointed annex DID, when the
+     *   document names one and this run works in its Space
+     * @returns {Promise<ClientAnnexGenerationEnsureOutcome>}
+     */
+    async function runInAnnexSpace({ annexSpaceId, allowSpaceReplacement, pointer }) {
+        // A usable sibling first: absent, targeting a different Space than this
+        // run works in, or stale on either of the standing-zcap axes -- expiry
+        // (past, or inside the renewal window) and signer death (its proof key
+        // no longer under `capabilityDelegation` in the verified account
+        // document, the current-key-set rule) -- a fresh sibling is minted
+        // (local ladder-VM signing, which verifies because the gate above proved
+        // the VM a document verification method) so every annex request below
+        // can ride it.
+        let sibling = delegatedClients;
+        let siblingReminted = false;
+        const siblingStale = sibling !== undefined &&
+            standingZcapStale({
+                zcap: sibling,
+                doc: account.doc,
+                ...(now !== undefined ? { now } : {})
+            });
+        if (sibling === undefined ||
+            siblingSpaceId !== annexSpaceId ||
+            siblingStale) {
+            sibling = await mintDelegatedClientsDelegation({
+                zcapClient: ladderClient,
+                wasServerUrl,
+                clientAnnexSpaceId: annexSpaceId,
+                controller: standingClient.did,
+                ...(now !== undefined ? { now } : {})
+            });
+            siblingReminted = true;
+        }
+        const usableSibling = sibling;
+        const standingWas = new WasClient({
+            serverUrl: wasServerUrl,
+            zcapClient: standingClient.zcapClient
+        });
+        const storeFor = (generationId) => clientAnnexLogStore({
+            was: standingWas,
+            spaceId: annexSpaceId,
+            generationId,
+            capability: usableSibling
+        });
+        const annexPin = (generationId) => pinStore !== undefined
+            ? {
+                pinStore,
+                logId: clientAnnexLogPinId({ spaceId: annexSpaceId, generationId })
+            }
+            : {};
+        // RENEW PRECEDES MINT: a live, verifiable pointed generation is renewed
+        // in place; only a rung this generation never committed falls through to
+        // the fresh mint (the GC swap's no-committed-survivor escape).
+        if (pointer !== undefined) {
+            const parts = clientAnnexDidParts({ did: pointer });
+            const pointedLog = await readPublishedLog({
+                idStore: storeFor(parts.generationId),
+                expectedDid: pointer,
+                ...annexPin(parts.generationId)
+            });
+            if (pointedLog !== undefined) {
+                try {
+                    const ensured = await ensureGenerationDelegationCurrent({
+                        store: storeFor(parts.generationId),
+                        ladderSeed,
+                        generationId: parts.generationId,
+                        mintGenerationDelegation: mintDelegation,
+                        expectedDid: pointer,
+                        accountDoc: account.doc,
+                        // The head just read: on a healthy account this stage spends no
+                        // second round trip on the same log, and hands its head back for
+                        // the enrollment to build on.
+                        published: pointedLog,
+                        ...annexPin(parts.generationId),
+                        ...(now !== undefined ? { now } : {})
+                    });
+                    const resealed = await resealRecord({
+                        delegatedClients: usableSibling,
+                        siblingReminted
+                    });
+                    return {
+                        clientAnnexDid: pointer,
+                        generationDelegation: ensured.delegation,
+                        delegation: usableBridge,
+                        delegatedClients: usableSibling,
+                        generationMinted: false,
+                        spaceMinted,
+                        pointedSpaceMissing,
+                        delegationRenewed: ensured.renewed,
+                        siblingReminted,
+                        bridgeReminted,
+                        ...(ensured.published !== undefined
+                            ? { generationLog: ensured.published }
+                            : {}),
+                        ...resealed
+                    };
+                }
+                catch (err) {
+                    if (err.name !==
+                        'ClientAnnexRungUncommittedError') {
+                        throw err;
+                    }
+                    // This credential's rung was never committed into the pointed
+                    // generation (bound mid-generation): fall through to the fresh
+                    // mint, which commits it with the fresh genesis.
+                }
+            }
+            else if (allowSpaceReplacement &&
+                (await annexSpaceAbsent({ annexSpaceId, was: standingWas }))) {
+                // THE POINTED SPACE IS GONE. A missing generation log inside a live
+                // Space is the fresh-generation arm's case; a missing SPACE is not,
+                // since every write below would land in a Space that does not exist
+                // and the visit would fail on something other than the typed
+                // refusal. The Space is re-minted and the run starts over in it,
+                // before anything has been written.
+                await assertPointerEntryAttributable({ ladderSeed, log: account.log });
+                const freshSpaceId = await mintFreshAnnexSpace();
+                spaceMinted = true;
+                pointedSpaceMissing = true;
+                return runInAnnexSpace({
+                    annexSpaceId: freshSpaceId,
+                    allowSpaceReplacement: false
+                });
+            }
+        }
+        // THE FRESH-GENERATION ARM: pre-flight attribution first (never mint a
+        // generation the pointer entry cannot then name), then the GC swap's
+        // stage order minus its revoke -- mint, install the delegation,
+        // re-point. The fresh genesis commits only the acting credential's annex
+        // rung; other standing credentials' per-generation rungs are re-committed
+        // only by their own later ceremonies (a property of every generation
+        // swap).
+        await assertPointerEntryAttributable({ ladderSeed, log: account.log });
+        const minted = await mintCredentialClientAnnexGeneration({
+            was: standingWas,
+            wasServerUrl,
+            spaceId: annexSpaceId,
+            controller: account.did,
+            ladderSeed,
+            capability: usableSibling
         });
-        // The delegation embeds while the Space still answers to the bootstrap
-        // did:key; the controller flip follows, then the pointer entry.
         const ensured = await ensureGenerationDelegationCurrent({
-            store: clientAnnexLogStore({
-                was: bootstrapWas,
-                spaceId: freshSpaceId,
-                generationId: minted.generationId
-            }),
+            store: storeFor(minted.generationId),
             ladderSeed,
             generationId: minted.generationId,
             mintGenerationDelegation: mintDelegation,
             expectedDid: minted.did,
-            ...(pinStore !== undefined
-                ? {
-                    pinStore,
-                    logId: clientAnnexLogPinId({
-                        spaceId: freshSpaceId,
-                        generationId: minted.generationId
-                    })
-                }
-                : {}),
+            ...annexPin(minted.generationId),
             ...(now !== undefined ? { now } : {})
         });
-        await bootstrapWas
-            .space(freshSpaceId)
-            .configure({ controller: account.did, force: true });
-        await setDelegatedClientsPointer({
+        // No revocation of the superseded generation's delegation is attempted:
+        // a transient visit has no reach that could invoke it (the standing
+        // client is neither the Space controller nor in that delegation's
+        // chain). The pointer move itself retires it on a conforming server --
+        // the inspector clause compares the delegation's controller against the
+        // document's pointer -- and it otherwise rots on its TTL.
+        await movePointerAsLadder({
             idStore,
-            updateKeys,
+            ladderSeed,
             clientAnnexDid: minted.did,
-            expectedDid: account.did,
-            logOnly: true,
+            accountDid: account.did,
             ...(pinStore !== undefined
                 ? { pinStore, logId: accountLogPinId({ spaceId }) }
                 : {})
         });
-        const sibling = await mintDelegatedClientsDelegation({
-            zcapClient: ladderClient,
-            wasServerUrl,
-            clientAnnexSpaceId: freshSpaceId,
-            controller: standingClient.did,
-            ...(now !== undefined ? { now } : {})
+        const resealed = await resealRecord({
+            delegatedClients: usableSibling,
+            siblingReminted
         });
-        await onRebindRecord({ delegatedClients: sibling });
         return {
             clientAnnexDid: minted.did,
             generationDelegation: ensured.delegation,
-            delegatedClients: sibling,
+            delegation: usableBridge,
+            delegatedClients: usableSibling,
             generationMinted: true,
-            spaceMinted: true,
+            spaceMinted,
+            pointedSpaceMissing,
             delegationRenewed: false,
-            siblingReminted: true
+            siblingReminted,
+            bridgeReminted,
+            ...resealed
         };
     }
-    // THE EXISTING-SPACE ARMS. A usable sibling first: absent, targeting a
-    // different Space than the resolved one, or stale on either of the
-    // standing-zcap axes -- expiry (past, or inside the renewal window) and
-    // signer death (its proof key no longer under `capabilityDelegation` in
-    // the verified account document, the current-key-set rule) -- a fresh
-    // sibling is minted (local ladder-VM signing, which verifies because the
-    // gate above proved the VM a document verification method) so every annex
-    // request below can ride it.
-    let sibling = delegatedClients;
-    let siblingReminted = false;
-    const siblingStale = sibling !== undefined &&
-        (zcapExpiring({
-            ...(sibling.expires !== undefined
-                ? { expires: sibling.expires }
-                : {}),
-            ...(now !== undefined ? { now } : {})
-        }) ||
-            !delegationKeyInDocument({
-                doc: account.doc,
-                ...(delegationProofKeyId(sibling) !== undefined
-                    ? { delegationKeyId: delegationProofKeyId(sibling) }
-                    : {})
-            }));
-    if (sibling === undefined ||
-        siblingSpaceId !== annexSpaceId ||
-        siblingStale) {
-        sibling = await mintDelegatedClientsDelegation({
-            zcapClient: ladderClient,
-            wasServerUrl,
-            clientAnnexSpaceId: annexSpaceId,
-            controller: standingClient.did,
-            ...(now !== undefined ? { now } : {})
-        });
-        siblingReminted = true;
-    }
-    const usableSibling = sibling;
-    const standingWas = new WasClient({
-        serverUrl: wasServerUrl,
-        zcapClient: standingClient.zcapClient
-    });
-    const storeFor = (generationId) => clientAnnexLogStore({
-        was: standingWas,
-        spaceId: annexSpaceId,
-        generationId,
-        capability: usableSibling
-    });
-    const annexPin = (generationId) => pinStore !== undefined
-        ? {
-            pinStore,
-            logId: clientAnnexLogPinId({ spaceId: annexSpaceId, generationId })
-        }
-        : {};
-    // RENEW PRECEDES MINT: a live, verifiable pointed generation is renewed in
-    // place; only a rung this generation never committed falls through to the
-    // fresh mint (the GC swap's no-committed-survivor escape).
-    if (pointer !== undefined) {
-        const parts = clientAnnexDidParts({ did: pointer });
-        const pointedLog = await readPublishedLog({
-            idStore: storeFor(parts.generationId),
-            expectedDid: pointer,
-            ...annexPin(parts.generationId)
+    if (annexSpaceId === undefined) {
+        // NEITHER THE POINTER NOR A SIBLING NAMES A SPACE. The pre-flight
+        // attribution runs before any Space or generation is minted (a bridge
+        // delegation mint writes nothing durable).
+        await assertPointerEntryAttributable({ ladderSeed, log: account.log });
+        const freshSpaceId = await mintFreshAnnexSpace();
+        spaceMinted = true;
+        return runInAnnexSpace({
+            annexSpaceId: freshSpaceId,
+            allowSpaceReplacement: false
         });
-        if (pointedLog !== undefined) {
-            try {
-                const ensured = await ensureGenerationDelegationCurrent({
-                    store: storeFor(parts.generationId),
-                    ladderSeed,
-                    generationId: parts.generationId,
-                    mintGenerationDelegation: mintDelegation,
-                    expectedDid: pointer,
-                    accountDoc: account.doc,
-                    ...annexPin(parts.generationId),
-                    ...(now !== undefined ? { now } : {})
-                });
-                if (siblingReminted) {
-                    await onRebindRecord({ delegatedClients: usableSibling });
-                }
-                return {
-                    clientAnnexDid: pointer,
-                    generationDelegation: ensured.delegation,
-                    delegatedClients: usableSibling,
-                    generationMinted: false,
-                    spaceMinted: false,
-                    delegationRenewed: ensured.renewed,
-                    siblingReminted
-                };
-            }
-            catch (err) {
-                if (err.name !== 'ClientAnnexRungUncommittedError') {
-                    throw err;
-                }
-                // This credential's rung was never committed into the pointed
-                // generation (bound mid-generation): fall through to the fresh mint,
-                // which commits it with the fresh genesis.
-            }
-        }
     }
-    // THE FRESH-GENERATION ARM, existing Space: pre-flight attribution first
-    // (never mint a generation the pointer entry cannot then name), then the
-    // GC swap's stage order minus its revoke -- mint, install the delegation,
-    // re-point. The fresh genesis commits only the acting credential's annex
-    // rung; other standing credentials' per-generation rungs are re-committed
-    // only by their own later ceremonies (a property of every generation
-    // swap).
-    const updateKeys = await pointerEntryUpdateKeys({
-        ladderSeed,
-        log: account.log
-    });
-    const minted = await mintCredentialClientAnnexGeneration({
-        was: standingWas,
-        wasServerUrl,
-        spaceId: annexSpaceId,
-        controller: account.did,
-        ladderSeed,
-        capability: usableSibling
-    });
-    const ensured = await ensureGenerationDelegationCurrent({
-        store: storeFor(minted.generationId),
-        ladderSeed,
-        generationId: minted.generationId,
-        mintGenerationDelegation: mintDelegation,
-        expectedDid: minted.did,
-        ...annexPin(minted.generationId),
-        ...(now !== undefined ? { now } : {})
-    });
-    // No revocation of the superseded generation's delegation is attempted:
-    // a transient visit has no reach that could invoke it (the standing client
-    // is neither the Space controller nor in that delegation's chain). The
-    // pointer move itself retires it on a conforming server -- the inspector
-    // clause compares the delegation's controller against the document's
-    // pointer -- and it otherwise rots on its TTL.
-    await setDelegatedClientsPointer({
-        idStore,
-        updateKeys,
-        clientAnnexDid: minted.did,
-        expectedDid: account.did,
-        logOnly: true,
-        ...(pinStore !== undefined
-            ? { pinStore, logId: accountLogPinId({ spaceId }) }
-            : {})
+    return runInAnnexSpace({
+        annexSpaceId,
+        allowSpaceReplacement: true,
+        ...(pointer !== undefined ? { pointer } : {})
     });
-    if (siblingReminted) {
-        await onRebindRecord({ delegatedClients: usableSibling });
-    }
-    return {
-        clientAnnexDid: minted.did,
-        generationDelegation: ensured.delegation,
-        delegatedClients: usableSibling,
-        generationMinted: true,
-        spaceMinted: false,
-        delegationRenewed: false,
-        siblingReminted
-    };
 }
 /**
  * The annex Space, in the settled resolution order: the account document's
@@ -417,11 +633,7 @@ export function resolveClientAnnexSpaceId({ doc, delegatedClients }) {
  * @returns {Promise<ClientWebvhUpdateKeys>}
  */
 export async function pointerEntryUpdateKeys({ ladderSeed, log }) {
-    const params = effectiveParameters(log);
-    const current = params[params.length - 1] ?? {
-        updateKeys: [],
-        nextKeyHashes: []
-    };
+    const current = currentLogParameters({ log });
     const unattributable = () => new ClientAnnexGenerationUnavailableError({
         reason: 'update-key-not-attributable',
         message: "No current account-log update key is a rung of this credential's " +
@@ -446,4 +658,139 @@ export async function pointerEntryUpdateKeys({ ladderSeed, log }) {
     });
     return { updateSeed: attributed.rung.seed, stagedSeed: staged.seed };
 }
+/**
+ * The pre-flight the pointer-moving arms run before minting anything: this
+ * ladder has a rung the pointer entry will be able to sign with, either
+ * standing in `updateKeys` already or committed in `nextKeyHashes` and
+ * revealable by {@link movePointerAsLadder}. A ladder the log carries no rung
+ * of at all, and an ambiguous attribution, refuse here with
+ * {@link ClientAnnexGenerationUnavailableError} before a generation or a
+ * Space is minted.
+ *
+ * @param options {object}
+ * @param options.ladderSeed {Uint8Array}
+ * @param options.log {DIDLog}   the VERIFIED account log
+ * @returns {Promise<void>}
+ */
+async function assertPointerEntryAttributable({ ladderSeed, log }) {
+    const current = currentLogParameters({ log });
+    try {
+        await attributeLadderRung({ ladderSeed, published: current });
+    }
+    catch (err) {
+        if (err.name === 'LadderAttributionError') {
+            throw new ClientAnnexGenerationUnavailableError({
+                reason: 'update-key-not-attributable',
+                message: "The account log carries no rung of this credential's ladder, or " +
+                    'the attribution is ambiguous; the pointer entry could not be ' +
+                    'signed, so nothing is minted.'
+            });
+        }
+        throw err;
+    }
+}
+/**
+ * The `#DelegatedClients` pointer move as a credential-only visit makes it:
+ * reveal this ladder's rung when only its hash stands committed, re-read, and
+ * write the pointer entry signed by the now-revealed rung.
+ *
+ * A self-enrollment's add entry spends the revealed rung, so on any account
+ * that has ever self-enrolled the rung is merely committed and the reveal is
+ * what makes the pointer entry signable at all.
+ *
+ * ACCEPTED CONSEQUENCE (design FW-356, finding R3): the reveal retires
+ * nothing, and the pointer entry re-states `updateKeys` verbatim, so the
+ * acting rung stands in the account log's `updateKeys` afterwards. The price
+ * of a pointer move is therefore a standing account update key in the
+ * credential's hand -- direct document-edit authority through the bridge with
+ * no further reveal -- retired at that credential's next self-enrollment
+ * (whose add entry drops the attributed rung) or at its retirement. This is
+ * documented rather than prevented.
+ *
+ * Both entries run inside ONE conflict retry, and every attempt re-reads the
+ * head and re-attributes the rung from it, so a racing ceremony that consumes
+ * the rung climbs to the winner's committed rung instead of refusing
+ * `update-key-not-attributable` on a rung that is no longer current.
+ *
+ * Three things make that hold. A rung the winner consumed between this
+ * attempt's reveal and its re-read reads back as
+ * `update-key-not-attributable`, which inside this loop is staleness rather
+ * than a refusal -- the pre-flight already found a rung -- so it is raised as
+ * a conflict and the next attempt reveals the winner's committed rung. The pointer entry runs as
+ * {@link setDelegatedClientsPointerOnce} rather than through its retrying
+ * wrapper: the wrapper's inner loop would re-invoke the attempt with the
+ * attribution's stale `updateKeys`, and a rung the racing winner consumed
+ * cannot become authorized by re-reading, so the attempt would end on the
+ * plain not-authorized refusal, which the outer loop does not retry. And the
+ * attempt is handed the very head this attempt attributed against, so a
+ * racing entry landing between the attribution and the PUT loses the CAS and
+ * surfaces as a `WebvhLogConflictError` -- the refusal the outer loop
+ * re-attributes from. The pre-flight guard
+ * ({@link assertPointerEntryAttributable}) therefore cannot fire from
+ * staleness here: it runs on the caller's snapshot before anything is minted,
+ * while every entry this function publishes is built on a head it read
+ * itself.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}   the account log's store, from the
+ *   record's bridge delegation
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param options.clientAnnexDid {string}   the generation to point at
+ * @param options.accountDid {string}   the account DID the log must resolve to
+ * @param [options.pinStore] {ResourceLogPinStore}   the visit's chain-head pins
+ * @param [options.logId] {string}   the account log's pin slot; required
+ *   whenever a `pinStore` is supplied
+ * @returns {Promise<void>}
+ */
+async function movePointerAsLadder({ idStore, ladderSeed, clientAnnexDid, accountDid, pinStore, logId }) {
+    const pin = pinStore !== undefined && logId !== undefined ? { pinStore, logId } : {};
+    await withLogConflictRetry(async () => {
+        await revealLadderRungWebvh({
+            store: idStore,
+            ladderSeed,
+            expectedDid: accountDid,
+            ...pin
+        });
+        // The head the reveal entry just published (or the unchanged head, when
+        // the rung was revealed already), under the same pin.
+        const published = await readPublishedLogOrThrow({
+            idStore,
+            expectedDid: accountDid,
+            ...pin,
+            missingMessage: 'did:webvh: did.jsonl is missing; nothing to point at a client annex.'
+        });
+        // A racing ceremony that consumed the rung between this reveal and this
+        // read leaves the ladder committed-only again, which the attribution
+        // reports as `update-key-not-attributable`. Inside this loop that is a
+        // staleness signal rather than a refusal -- the pre-flight already found
+        // a rung, and a fresh reveal is exactly what the next attempt does -- so
+        // it becomes a conflict for the retry to re-run.
+        let updateKeys;
+        try {
+            updateKeys = await pointerEntryUpdateKeys({
+                ladderSeed,
+                log: published.log
+            });
+        }
+        catch (err) {
+            if (err.name ===
+                'ClientAnnexGenerationUnavailableError' &&
+                err.reason ===
+                    'update-key-not-attributable') {
+                throw new WebvhLogConflictError('did:webvh: a concurrent ceremony consumed the rung this pointer ' +
+                    'move just revealed; the move re-runs from a fresh reveal.', { cause: err });
+            }
+            throw err;
+        }
+        await setDelegatedClientsPointerOnce({
+            idStore,
+            signer: { kind: 'client', updateKeys },
+            clientAnnexDid,
+            expectedDid: accountDid,
+            logOnly: true,
+            published,
+            ...pin
+        });
+    });
+}
 //# sourceMappingURL=heal.js.map