@interop/wallet-core 0.62.0 → 0.66.0

package/dist/unlock/standingWebvh.js

@@ -28,15 +28,17 @@
  * one-entry forget -- live in `clientAnnex/ladderAnchored.ts`. What stays
  * here is the verify-side half every wallet needs regardless of account configuration.
  */
-import { deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
-import { assertCarryOverCommitments, MULTIKEY_COMMITMENT_VM_TYPE, MULTIKEY_VM_TYPE, ladderVerificationMethod, publishUpdatedLog, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } from '../webvh/didWebvh.js';
-import { ladderVmIds } from '../webvh/listClients.js';
+import { deriveNextKeyHash } from '@interop/did-method-webvh';
+import { MULTIKEY_COMMITMENT_VM_TYPE, MULTIKEY_VM_TYPE, ladderVerificationMethod, readPublishedLogOrThrow, withLogConflictRetry } from '../webvh/didWebvh.js';
+import { signAccountEntry } from '../webvh/accountEntry.js';
+import { preEntryProjectionPublisher } from '../webvh/didWebProjection.js';
+import { ladderVmIds, relationIds } from '../resourceLog/document.js';
 // The one deliberate base-side dependency on the annex subpath, pinned as an
 // exception in the lint rule: this module resolves a credential's CURRENT
 // ladder inventory from the log itself (the shared attribution helpers in
 // `clientAnnex/ladder.ts`), never touching the annex log machinery, and
 // derives the credential's ladder VM from its seed at the install.
-import { attributeLadderInventory, LadderAttributionError, ladderVmKeyMultibase } from '../clientAnnex/ladder.js';
+import { attributeLadderInventory, LadderAttributionError, ladderVmIdsIntroducedWithCredential, ladderVmKeyMultibase } from '../clientAnnex/ladder.js';
 /**
  * The ladder inventory the removal edit resolved from the log diverges from
  * what the caller was told one read earlier. A ceremony that names its
@@ -62,6 +64,54 @@ export class LadderInventoryDriftError extends Error {
         this.attributed = attributed;
     }
 }
+/**
+ * A retirement whose ladder attribution could not claim the retired
+ * credential's ladder VM, refused with nothing written. The shape is the
+ * seedless strike claiming nothing: the credential still stands in the
+ * document, the walk struck no ladder VM, and ladder VMs stand there that it
+ * could not claim. A leftover VM would keep the retired credential's
+ * delegation authority alive -- under `capabilityDelegation` it can still
+ * sign a DELETE-only capability on the account Space -- and nothing
+ * downstream can tell such a leftover from a sibling credential's standing
+ * VM, so the retirement is the one place the state can be closed
+ * (`decisions/0015`).
+ *
+ * `unclaimedLadderVmIds` names every ladder VM the walk left unclaimed, and
+ * `anchorKeyMultibase` the update key the walk was anchored on (a recovery
+ * code's revocation anchors on the rung-0 multibase the registry recorded at
+ * issuance). On a
+ * multi-credential account that list carries the siblings' VMs beside the
+ * retired credential's, since telling them apart is exactly what the walk
+ * could not do. `retryableWithLadderSeed` says whether a retry supplying the
+ * credential's ladder seed can let attribution succeed. The gate raises this
+ * error only from a seedless claim (a seeded one either strikes the derived
+ * VM or proves there is none), so the hint is `true` from this library; the
+ * member is the wallets' read for the retry they offer.
+ * Matched on `name` (the error crosses app-injected seams that may resolve
+ * to another copy of this package).
+ */
+export class UnclaimedLadderVmRetirementError extends Error {
+    unclaimedLadderVmIds;
+    retryableWithLadderSeed;
+    anchorKeyMultibase;
+    constructor({ unclaimedLadderVmIds, retryableWithLadderSeed, anchorKeyMultibase }) {
+        super("did:webvh: the retirement cannot claim the retired credential's ladder " +
+            `VM (standing unclaimed: ${unclaimedLadderVmIds.join(', ')}` +
+            (anchorKeyMultibase === undefined
+                ? ''
+                : `; anchored on ${anchorKeyMultibase}`) +
+            '); nothing was published and the credential still stands. ' +
+            (retryableWithLadderSeed
+                ? "Retry with the credential's ladder seed in hand."
+                : 'No retry with the ladder seed can claim it.'));
+        this.name = 'UnclaimedLadderVmRetirementError';
+        this.unclaimedLadderVmIds = unclaimedLadderVmIds;
+        this.retryableWithLadderSeed = retryableWithLadderSeed;
+        if (anchorKeyMultibase !== undefined) {
+            this.anchorKeyMultibase = anchorKeyMultibase;
+        }
+    }
+}
 /**
  * The verification-method id a credential's key-agreement entry publishes
  * under: `<did>#<multibase>` for a verbatim key (indistinguishable by id from
@@ -111,6 +161,191 @@ export async function attributeUnlockLadderInventory({ log, did, unlockKeys, lad
         ...(ladderSeed ? { ladderSeed } : {})
     });
 }
+/**
+ * What of the document's ladder VMs a credential's attribution claims: the
+ * VM its seed derives (when the ceremony holds one), plus every VM the log
+ * attributes to its ladder. Resolved once here and shared by the removal
+ * edit, the retirement ceremony's pre-edit stage, and the read-only
+ * pre-flight, so the three agree on what is struck and what is left.
+ *
+ * `struck` is what the removal edit strikes: the derived id when it stands,
+ * and the attributed ids. `unclaimed` is every ladder VM standing in the
+ * document that neither the seed nor the attribution claims -- on a
+ * multi-credential account, the siblings' VMs at least. A supplied seed also
+ * cross-checks the attribution: a log attributing a VM the seed does not
+ * derive refuses with {@link LadderAttributionError}.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the document the attribution ran over
+ * @param options.did {string}   the account DID
+ * @param options.inventory {LadderStandingInventory}   the credential's
+ *   attributed ladder inventory ({@link attributeUnlockLadderInventory})
+ * @param [options.ladderSeed] {Uint8Array}   the credential's ladder seed
+ * @returns {Promise<{ ladderVmId?: string, struck: string[], unclaimed:
+ *   string[] }>}   the seed-derived VM id when a seed was held
+ */
+export async function ladderVmClaimOf({ doc, did, inventory, ladderSeed }) {
+    const ladderVmId = ladderSeed
+        ? `${did}#${await ladderVmKeyMultibase({ ladderSeed })}`
+        : undefined;
+    if (ladderVmId !== undefined) {
+        const foreign = inventory.ladderVmIds.filter(id => id !== ladderVmId);
+        if (foreign.length > 0) {
+            throw new LadderAttributionError("The published log attributes a ladder VM this credential's seed " +
+                'does not derive; refusing to strike on an ambiguous ' +
+                'attribution.');
+        }
+    }
+    const standing = ladderVmIds({ doc });
+    const struck = new Set();
+    if (ladderVmId !== undefined && standing.includes(ladderVmId)) {
+        struck.add(ladderVmId);
+    }
+    for (const id of inventory.ladderVmIds) {
+        struck.add(id);
+    }
+    const claimed = new Set([
+        ...struck,
+        ...(ladderVmId !== undefined ? [ladderVmId] : [])
+    ]);
+    return {
+        ...(ladderVmId !== undefined ? { ladderVmId } : {}),
+        struck: [...struck],
+        unclaimed: standing.filter(id => !claimed.has(id))
+    };
+}
+/**
+ * The retirement gate (`decisions/0015`): refuses, with
+ * {@link UnclaimedLadderVmRetirementError}, a retirement of a
+ * ladder-carrying credential whose SEEDLESS claim struck nothing while a
+ * ladder VM that COULD BE THIS CREDENTIAL'S stands unclaimed and the
+ * credential itself still stands in the document. Deliberately narrower than
+ * "`unclaimed` is non-empty", which every retirement on a healthy
+ * multi-credential account produces, and narrower again than the standing
+ * unclaimed set: a sibling credential's VM is nothing this retirement could
+ * leave behind.
+ *
+ * Which unclaimed VMs are candidates is
+ * {@link ladderVmIdsIntroducedWithCredential}'s question, read off the log's
+ * entry shapes rather than off an attribution that has already refused: a VM
+ * introduced by the entry that introduced this credential's `keyAgreement`
+ * member, or by the entry that committed or authorized its anchor (the split
+ * bind, whose key and authority entries sit two versions apart). None, and
+ * the credential never had a VM to leave standing, so the retirement
+ * completes and strikes what it can. That is the torn issuance's orphan -- a
+ * credential with a `keyAgreement` member, no ladder VM, and no committed
+ * rung -- which previously could never be removed at all, since a sibling's
+ * standing VM refused it forever.
+ *
+ * Two shapes pass ahead of that. A credential whose `keyAgreement` member is
+ * already gone is a completed retirement re-running. And a claim resolved
+ * WITH the seed never refuses: the derived VM is either standing (and
+ * struck) or absent, and an absent derived VM is proof the credential has
+ * nothing to claim -- the last-client transition torn between its strike and
+ * reinstall entries leaves exactly that, and a seeded retirement there must
+ * complete rather than wait on the transition's re-run. So the error's retry
+ * hint is `true` whenever this gate raises it.
+ *
+ * The caller decides whether the credential carries a ladder.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the verified log the claim was resolved over
+ * @param options.doc {DIDDoc}   the document the claim was resolved over
+ * @param options.credentialVmId {string}   the credential's `keyAgreement`
+ *   verification-method id ({@link unlockKeyVmId})
+ * @param options.claim {{ ladderVmId?: string, struck: string[], unclaimed:
+ *   string[] }}   from {@link ladderVmClaimOf}
+ * @param [options.anchorKeyMultibase] {string}   the update key the walk was
+ *   anchored on: the candidate reading's second anchor form, and named in
+ *   the refusal
+ * @returns {Promise<void>}
+ */
+export async function assertLadderVmClaimed({ log, doc, credentialVmId, claim, anchorKeyMultibase }) {
+    const credentialStands = (doc.verificationMethod ?? []).some(method => method.id === credentialVmId);
+    if (!credentialStands ||
+        claim.ladderVmId !== undefined ||
+        claim.struck.length > 0 ||
+        claim.unclaimed.length === 0) {
+        return;
+    }
+    const candidates = await ladderVmIdsIntroducedWithCredential({
+        log,
+        credentialVmId,
+        ...(anchorKeyMultibase !== undefined ? { anchorKeyMultibase } : {})
+    });
+    const unclaimed = claim.unclaimed.filter(id => candidates.includes(id));
+    if (unclaimed.length === 0) {
+        return;
+    }
+    throw new UnclaimedLadderVmRetirementError({
+        unclaimedLadderVmIds: unclaimed,
+        retryableWithLadderSeed: true,
+        ...(anchorKeyMultibase !== undefined ? { anchorKeyMultibase } : {})
+    });
+}
+/**
+ * The retirement gate run read-only, before anything is written: one pinned
+ * read of the account log, the credential's ladder attribution, and
+ * {@link assertLadderVmClaimed} over the result. A caller that establishes a
+ * replacement credential before it retires the old one (a passphrase change,
+ * a tap-confirmed passkey removal) runs this first, so a gate refusal lands
+ * the way an invalid-input check does -- nothing established, no
+ * pending-shaped registry entry written -- rather than after establishment,
+ * where the refusal would leave a torn state no seedless repair can clear.
+ * The in-ceremony gate stays as defense in depth, and it is what answers a
+ * log entry landing between the pre-flight and the retirement: the
+ * pre-flight's verdict holds for the head it read, and nothing binds the two
+ * reads.
+ *
+ * @param options {object}
+ * @param options.idStore {UnlockLogStore}   the account's `id` collection
+ *   read side
+ * @param options.unlockKeys {StandingUnlockKeys}   the credential's recorded
+ *   public inventory
+ * @param [options.ladderSeed] {Uint8Array}   the credential's ladder seed,
+ *   when the caller holds it
+ * @param [options.expectedDid] {string}   the account DID the log must
+ *   resolve to
+ * @param [options.pinStore] {ResourceLogPinStore}   the caller's chain-head
+ *   pins
+ * @param [options.logId] {string}   the account log's pin slot; required
+ *   whenever a `pinStore` is supplied
+ * @returns {Promise<LadderVmRemovalReport>}   what the retirement would
+ *   strike and what it would leave unclaimed
+ */
+export async function preflightUnlockCredentialRetirement({ idStore, unlockKeys, ladderSeed, expectedDid, pinStore, logId }) {
+    const published = await readPublishedLogOrThrow({
+        idStore,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {}),
+        missingMessage: 'did:webvh: did.jsonl is missing; nothing to retire from.'
+    });
+    const { did, doc } = published;
+    const inventory = await attributeUnlockLadderInventory({
+        log: published.log,
+        did,
+        unlockKeys,
+        ...(ladderSeed ? { ladderSeed } : {})
+    });
+    const claim = await ladderVmClaimOf({
+        doc,
+        did,
+        inventory,
+        ...(ladderSeed ? { ladderSeed } : {})
+    });
+    await assertLadderVmClaimed({
+        log: published.log,
+        doc,
+        credentialVmId: unlockKeyVmId({
+            did,
+            keyAgreement: unlockKeys.keyAgreement
+        }),
+        claim,
+        anchorKeyMultibase: unlockKeys.updateKeyMultibase
+    });
+    return { struck: claim.struck, unclaimed: claim.unclaimed };
+}
 /**
  * The credential's `keyAgreement` verification method: an ordinary unmarked
  * entry carrying either the key verbatim (a `Multikey` with
@@ -144,34 +379,6 @@ export function unlockKeyVerificationMethod({ did, keyAgreement }) {
         publicKeyCommitment: keyAgreement.commitment
     };
 }
-/**
- * Reads and resolves the published log through the narrow store seam.
- *
- * @param options {object}
- * @param options.store {UnlockLogStore}
- * @param [options.expectedDid] {string}   the account DID the log must resolve
- *   to, where the caller holds one
- * @param [options.pinStore] {ResourceLogPinStore}   the caller's chain-head
- *   pins; a served log that is a rollback, a fork, or an identity switch
- *   against the pinned head is refused (`ResourceLogContinuityError`)
- * @param [options.logId] {string}   the account log's pin slot
- *   (`accountLogPinId({ spaceId })`); required whenever a `pinStore` is
- *   supplied
- * @returns {Promise<PublishedWebvhLog>}
- */
-export async function readLogOrThrow({ store, expectedDid, pinStore, logId }) {
-    // readPublishedLog only calls getIdResourceRaw, so the narrow seam is safe.
-    const published = await readPublishedLog({
-        idStore: store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
-    if (!published) {
-        throw new Error('did:webvh: did.jsonl is missing; nothing to enroll into.');
-    }
-    return published;
-}
 /**
  * BIND (run by an enrolled client, root authority): publishes a standing
  * credential's split configuration into the document -- one entry adding the
@@ -187,8 +394,13 @@ export async function readLogOrThrow({ store, expectedDid, pinStore, logId }) {
  * idempotence against the SAME seed, finds the completed stage and publishes
  * nothing -- where a mint-when-absent would publish a second VM that no
  * anchored attribution could later strike. A credential with no ladder at all
- * (a recovery code, whose inventory is one key-agreement method and one
- * update key) passes `null` and gets no VM.
+ * passes `null` and gets no VM.
+ *
+ * `part` splits the bind across two entries where a ceremony needs the
+ * credential's decryption material to precede its authority: `'key'`
+ * publishes the `keyAgreement` member alone, `'authority'` installs the
+ * ladder VM and commits the rung-0 hash, and `'all'` (the default) is the one
+ * merged entry every other caller writes.
  *
  * Idempotent: an inventory already published is a no-op, so re-running a torn
  * bind converges. The entry publishes conditionally on the log this call
@@ -197,13 +409,16 @@ export async function readLogOrThrow({ store, expectedDid, pinStore, logId }) {
  *
  * @param options {object}
  * @param options.idStore {WebvhIdStore}
- * @param options.updateKeys {ClientWebvhUpdateKeys}   the BINDING client's own
- *   did:webvh update-key seeds
+ * @param options.signer {AccountLogSigner}   who signs the entry: the BINDING
+ *   client's own did:webvh update-key seeds, or the acting credential's
+ *   ladder seed
  * @param options.unlockKeys {StandingUnlockKeys}   the credential's public
  *   inventory
  * @param options.ladderSeed {Uint8Array | null}   the credential's ladder
  *   seed, whose VM this entry installs; `null` for a credential that carries
  *   no ladder
+ * @param [options.part] {string}   `'all'` (the default), `'key'`, or
+ *   `'authority'` -- see above
  * @param [options.expectedDid] {string}   the account DID the log must resolve
  *   to, from the caller's stored account pointer
  * @param [options.pinStore] {ResourceLogPinStore}   the caller's chain-head
@@ -276,6 +491,15 @@ export async function publishUnlockKey(options) {
  * @param options {object}   see {@link publishUnlockKey}, plus:
  * @param [options.ladderSeed] {Uint8Array}   the retired credential's ladder
  *   seed, when in hand
+ * @param [options.projectionStore] {object}   an `id`-collection store the
+ *   caller may write through (a transient session's, bound to its generation
+ *   delegation; an enrolled client's own root-invoking store). Supplied, the
+ *   post-strike `did:web` projection is PUT through it immediately BEFORE
+ *   this entry publishes, which is what keeps a ladder-signed removal from
+ *   leaving `did.json` naming the retired credential. Best-effort: a failed
+ *   PUT is warned and the removal proceeds. Omitted, the ladder arm leaves
+ *   the projection to the next visit's `ensureDidWebProjection` and the
+ *   client arm publishes it after the entry, as before
  * @param [options.expectedLadderVmIds] {string[]}   the ladder VM ids the
  *   caller already resolved for this credential, from its own read of the
  *   log. Supplied, this edit's own attribution must match them as a set --
@@ -283,6 +507,14 @@ export async function publishUnlockKey(options) {
  *   {@link LadderInventoryDriftError} before writing anything. That is what
  *   ties the retirement's stage-0 read (whose list the dependent-record
  *   re-mint pass acted on) to this one, which is otherwise independent
+ * @param [options.requireLadderVmClaim] {boolean}   the credential carries a
+ *   ladder, so its VM must be claimed: the edit refuses with
+ *   {@link UnclaimedLadderVmRetirementError} before writing when the claim
+ *   struck nothing while ladder VMs stand unclaimed and the credential still
+ *   stands ({@link assertLadderVmClaimed}). The retirement ceremony sets it,
+ *   and so does a recovery code's removal, whose inventory carries the code's
+ *   own ladder VM. The refusal names the recorded update key the walk was
+ *   anchored on
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog, ladderVm:
  *   LadderVmRemovalReport }>}   see {@link publishUnlockKey}, plus the ladder
  *   VM report: what this entry struck, and what stands unclaimed after it
@@ -299,189 +531,216 @@ export async function removeUnlockKey(options) {
  * @param options {object}   see {@link publishUnlockKey}, plus `polarity`
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-async function setUnlockKeyInventoryOnce({ idStore, updateKeys, unlockKeys, ladderSeed, expectedLadderVmIds, expectedDid, pinStore, logId, verb, polarity }) {
-    const published = await readLogOrThrow({
-        store: idStore,
+async function setUnlockKeyInventoryOnce({ idStore, signer, projectionStore, unlockKeys, ladderSeed, part = 'all', expectedLadderVmIds, requireLadderVmClaim, expectedDid, pinStore, logId, verb, polarity }) {
+    let ladderVmReport = { struck: [], unclaimed: [] };
+    const outcome = await signAccountEntry({
+        idStore,
+        signer,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
         ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
-    const { did, doc } = published;
-    const keyHash = await deriveNextKeyHash(unlockKeys.updateKeyMultibase);
-    const vmId = unlockKeyVmId({ did, keyAgreement: unlockKeys.keyAgreement });
-    const vmPresent = (doc.verificationMethod ?? []).some(method => method.id === vmId);
-    // The remove polarity strikes the ladder's CURRENT inventory, resolved from
-    // the log with the recorded key as anchor -- never just the recorded key's
-    // hash, which a self-enrollment since the bind leaves stale (see
-    // {@link removeUnlockKey}). The credential's own verification-method id
-    // goes along: it is what tells the walk a climb from a spend, so the
-    // removal never annexes the commitment a spend handed to its replacement.
-    const inventory = polarity === 'remove'
-        ? await attributeUnlockLadderInventory({
-            log: published.log,
-            did,
-            unlockKeys,
-            ...(ladderSeed ? { ladderSeed } : {})
-        })
-        : { revealedKeys: [], committedHashes: [], ladderVmIds: [] };
-    const removedHashes = new Set(inventory.committedHashes);
-    const removedKeys = new Set(inventory.revealedKeys);
-    // The credential's ladder VM: installed by the publish polarity in this
-    // same entry, struck by the remove polarity in this same entry. The
-    // derived id is what the install publishes; the removal takes it from the
-    // seed when the ceremony holds one and from the log's attribution
-    // otherwise, so a seedless retirement still ends the credential's
-    // delegation authority.
-    const ladderVmKey = ladderSeed
-        ? await ladderVmKeyMultibase({ ladderSeed })
-        : undefined;
-    const ladderVmId = ladderVmKey === undefined ? undefined : `${did}#${ladderVmKey}`;
-    const standingLadderVmIds = ladderVmIds({ doc });
-    const struckLadderVmIds = new Set();
-    if (polarity === 'remove') {
-        if (ladderVmId !== undefined) {
-            const foreign = inventory.ladderVmIds.filter(id => id !== ladderVmId);
-            if (foreign.length > 0) {
-                throw new LadderAttributionError("The published log attributes a ladder VM this credential's seed " +
-                    'does not derive; refusing to strike on an ambiguous ' +
-                    'attribution.');
+        ...(logId !== undefined ? { logId } : {}),
+        missingMessage: 'did:webvh: did.jsonl is missing; nothing to enroll into.',
+        verb: verb ?? 'changing an unlock credential',
+        // The post-strike projection, published while the caller's store can
+        // still write it and before the entry the ladder arm cannot publish it
+        // with. Only the removal polarity is ever handed one: a publish adds
+        // inventory, which the served projection under-lists until some later
+        // writer refreshes it -- the safe direction.
+        ...(projectionStore
+            ? {
+                beforePublish: preEntryProjectionPublisher({
+                    store: projectionStore
+                })
             }
-            if (standingLadderVmIds.includes(ladderVmId)) {
-                struckLadderVmIds.add(ladderVmId);
+            : {}),
+        build: async ({ published }) => {
+            const { did, doc } = published;
+            const keyHash = await deriveNextKeyHash(unlockKeys.updateKeyMultibase);
+            const vmId = unlockKeyVmId({ did, keyAgreement: unlockKeys.keyAgreement });
+            const vmPresent = (doc.verificationMethod ?? []).some(method => method.id === vmId);
+            // The remove polarity strikes the ladder's CURRENT inventory, resolved
+            // from the log with the recorded key as anchor -- never just the
+            // recorded key's hash, which a self-enrollment since the bind leaves
+            // stale (see {@link removeUnlockKey}). The credential's own
+            // verification-method id goes along: it is what tells the walk a climb
+            // from a spend, so the removal never annexes the commitment a spend
+            // handed to its replacement.
+            const inventory = polarity === 'remove'
+                ? await attributeUnlockLadderInventory({
+                    log: published.log,
+                    did,
+                    unlockKeys,
+                    ...(ladderSeed ? { ladderSeed } : {})
+                })
+                : { revealedKeys: [], committedHashes: [], ladderVmIds: [] };
+            const removedHashes = new Set(inventory.committedHashes);
+            const removedKeys = new Set(inventory.revealedKeys);
+            // The credential's ladder VM: installed by the publish polarity in this
+            // same entry, struck by the remove polarity in this same entry. The
+            // derived id is what the install publishes; the removal takes it from
+            // the seed when the ceremony holds one and from the log's attribution
+            // otherwise, so a seedless retirement still ends the credential's
+            // delegation authority.
+            const ladderVmKey = ladderSeed
+                ? await ladderVmKeyMultibase({ ladderSeed })
+                : undefined;
+            const ladderVmId = ladderVmKey === undefined ? undefined : `${did}#${ladderVmKey}`;
+            const standingLadderVmIds = ladderVmIds({ doc });
+            const claim = polarity === 'remove'
+                ? await ladderVmClaimOf({
+                    doc,
+                    did,
+                    inventory,
+                    ...(ladderSeed ? { ladderSeed } : {})
+                })
+                : { struck: [], unclaimed: [] };
+            if (polarity === 'remove') {
+                // The drift check, before any write: this edit's own attribution
+                // against the list the caller resolved a read earlier. A concurrent
+                // ceremony, or a host serving two different log versions to the two
+                // reads, would otherwise let the strike diverge from what the
+                // caller's dependent-record pass already acted on.
+                if (expectedLadderVmIds !== undefined) {
+                    const attributed = new Set(inventory.ladderVmIds);
+                    const expected = new Set(expectedLadderVmIds);
+                    const sameSet = attributed.size === expected.size &&
+                        [...expected].every(id => attributed.has(id));
+                    if (!sameSet) {
+                        throw new LadderInventoryDriftError({
+                            expected: [...expected],
+                            attributed: [...attributed]
+                        });
+                    }
+                }
+                // The retirement gate, before any write and after the drift check: a
+                // ladder-carrying credential whose claim struck nothing while ladder
+                // VMs stand unclaimed is refused rather than retired with its VM left
+                // standing.
+                if (requireLadderVmClaim) {
+                    await assertLadderVmClaimed({
+                        log: published.log,
+                        doc,
+                        credentialVmId: vmId,
+                        claim,
+                        anchorKeyMultibase: unlockKeys.updateKeyMultibase
+                    });
+                }
             }
-        }
-        for (const id of inventory.ladderVmIds) {
-            struckLadderVmIds.add(id);
-        }
-        // The drift check, before any write: this edit's own attribution against
-        // the list the caller resolved a read earlier. A concurrent ceremony, or
-        // a host serving two different log versions to the two reads, would
-        // otherwise let the strike diverge from what the caller's dependent-record
-        // pass already acted on.
-        if (expectedLadderVmIds !== undefined) {
-            const attributed = new Set(inventory.ladderVmIds);
-            const expected = new Set(expectedLadderVmIds);
-            const sameSet = attributed.size === expected.size &&
-                [...expected].every(id => attributed.has(id));
-            if (!sameSet) {
-                throw new LadderInventoryDriftError({
-                    expected: [...expected],
-                    attributed: [...attributed]
-                });
+            const struckLadderVmIds = new Set(claim.struck);
+            const ladderVmPresent = polarity === 'publish'
+                ? ladderVmId !== undefined && standingLadderVmIds.includes(ladderVmId)
+                : struckLadderVmIds.size > 0;
+            const struckIds = new Set([vmId, ...struckLadderVmIds]);
+            const hashCommitted = published.nextKeyHashes.includes(keyHash);
+            // What this entry is responsible for, by `part`: the key half publishes
+            // the `keyAgreement` member alone, the authority half the ladder VM and
+            // the rung's commitment, and the default entry both.
+            const publishesKey = part === 'all' || part === 'key';
+            const publishesAuthority = part === 'all' || part === 'authority';
+            const settled = polarity === 'publish'
+                ? (!publishesKey || vmPresent) &&
+                    (!publishesAuthority ||
+                        (hashCommitted && (ladderVmId === undefined || ladderVmPresent)))
+                : !vmPresent &&
+                    !ladderVmPresent &&
+                    removedHashes.size === 0 &&
+                    removedKeys.size === 0;
+            ladderVmReport = {
+                struck: claim.struck,
+                unclaimed: claim.unclaimed
+            };
+            if (settled) {
+                return undefined;
             }
-        }
-    }
-    const ladderVmPresent = polarity === 'publish'
-        ? ladderVmId !== undefined && standingLadderVmIds.includes(ladderVmId)
-        : struckLadderVmIds.size > 0;
-    const struckIds = new Set([vmId, ...struckLadderVmIds]);
-    const hashCommitted = published.nextKeyHashes.includes(keyHash);
-    const settled = polarity === 'publish'
-        ? vmPresent &&
-            hashCommitted &&
-            (ladderVmId === undefined || ladderVmPresent)
-        : !vmPresent &&
-            !ladderVmPresent &&
-            removedHashes.size === 0 &&
-            removedKeys.size === 0;
-    const ladderVmReport = (resultDoc, struck) => {
-        const claimed = new Set([
-            ...struck,
-            ...inventory.ladderVmIds,
-            ...(ladderVmId !== undefined ? [ladderVmId] : [])
-        ]);
-        return {
-            struck: [...struck],
-            unclaimed: ladderVmIds({ doc: resultDoc }).filter(id => !claimed.has(id))
-        };
-    };
-    if (settled) {
-        return {
-            did,
-            doc,
-            log: published.log,
-            ladderVm: ladderVmReport(doc, struckLadderVmIds)
-        };
-    }
-    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 ' +
-            `${verb ?? 'changing an unlock credential'}.`);
-    }
-    await assertCarryOverCommitments({ published });
-    const existingMethods = (doc.verificationMethod ?? []);
-    const signer = await updateKeySigner({ seed: updateKeys.updateSeed });
-    const nextKeyHashes = polarity === 'publish'
-        ? [...new Set([...published.nextKeyHashes, keyHash])]
-        : published.nextKeyHashes.filter(hash => !removedHashes.has(hash));
-    // A torn self-enrollment leaves a revealed rung in `updateKeys`; the remove
-    // polarity strikes it in the same entry as its hash, keeping the carry-over
-    // invariant self-consistent. On the publish polarity and the ordinary
-    // committed-only removal this is the published set unchanged.
-    const statedUpdateKeys = polarity === 'publish'
-        ? published.updateKeys
-        : published.updateKeys.filter(key => !removedKeys.has(key));
-    const verificationMethods = polarity === 'publish'
-        ? [
-            ...existingMethods.filter(method => method.id !== vmId && method.id !== ladderVmId),
-            unlockKeyVerificationMethod({
-                did,
-                keyAgreement: unlockKeys.keyAgreement
-            }),
-            ...(ladderVmKey !== undefined
+            const existingMethods = (doc.verificationMethod ??
+                []);
+            // The publish polarity commits the credential's update-key hash through
+            // the seam's `commitHashes`, so on a ladder-signed entry it lands after
+            // the acting rung's own carry-over hash (`decisions/0007` order).
+            const commitHashes = polarity === 'publish' && publishesAuthority && !hashCommitted
+                ? [keyHash]
+                : [];
+            const nextKeyHashes = polarity === 'publish'
+                ? undefined
+                : published.nextKeyHashes.filter(hash => !removedHashes.has(hash));
+            // A torn self-enrollment leaves a revealed rung in `updateKeys`; the
+            // remove polarity strikes it in the same entry as its hash, keeping the
+            // carry-over invariant self-consistent. On the publish polarity and the
+            // ordinary committed-only removal this is the published set unchanged.
+            const statedUpdateKeys = polarity === 'publish'
+                ? undefined
+                : published.updateKeys.filter(key => !removedKeys.has(key));
+            const installedLadderVmKey = publishesAuthority ? ladderVmKey : undefined;
+            const verificationMethods = polarity === 'publish'
                 ? [
-                    ladderVerificationMethod({
-                        controller: did,
-                        publicKeyMultibase: ladderVmKey
-                    })
+                    ...existingMethods.filter(method => method.id !== (publishesKey ? vmId : undefined) &&
+                        method.id !== (publishesAuthority ? ladderVmId : undefined)),
+                    ...(publishesKey
+                        ? [
+                            unlockKeyVerificationMethod({
+                                did,
+                                keyAgreement: unlockKeys.keyAgreement
+                            })
+                        ]
+                        : []),
+                    ...(installedLadderVmKey !== undefined
+                        ? [
+                            ladderVerificationMethod({
+                                controller: did,
+                                publicKeyMultibase: installedLadderVmKey
+                            })
+                        ]
+                        : [])
                 ]
-                : [])
-        ]
-        : existingMethods.filter(method => method.id === undefined || !struckIds.has(method.id));
-    // On the remove polarity every relation drops the struck ids: the
-    // credential's entry sits under `keyAgreement` alone and the ladder VM under
-    // `assertionMethod` and `capabilityDelegation` alone, so one filter serves
-    // all five without restating either placement here.
-    const relation = (ids) => polarity === 'publish'
-        ? relationIds(ids)
-        : relationIds(ids).filter(id => !struckIds.has(id));
-    const keyAgreement = polarity === 'publish'
-        ? [...new Set([...relationIds(doc.keyAgreement), vmId])]
-        : relation(doc.keyAgreement);
-    // The ladder VM's two relations, and only those: the asymmetry is what
-    // recognizes it (`ladderVmIds`) and what keeps it out of every client
-    // listing.
-    const withLadderVm = (ids) => ladderVmId === undefined
-        ? relationIds(ids)
-        : [...new Set([...relationIds(ids), ladderVmId])];
-    const assertionMethod = polarity === 'publish'
-        ? withLadderVm(doc.assertionMethod)
-        : relation(doc.assertionMethod);
-    const capabilityDelegation = polarity === 'publish'
-        ? withLadderVm(doc.capabilityDelegation)
-        : relation(doc.capabilityDelegation);
-    const updated = await updateDID({
-        log: published.log,
-        signer,
-        alsoKnownAsWeb: true,
-        // The byoe context that defines a commitment entry's terms is installed
-        // at genesis and carried forward by every update, so no edit re-appends it.
-        updateKeys: statedUpdateKeys,
-        nextKeyHashes,
-        verificationMethods,
-        authentication: relation(doc.authentication),
-        assertionMethod,
-        keyAgreement,
-        capabilityInvocation: relation(doc.capabilityInvocation),
-        capabilityDelegation
+                : existingMethods.filter(method => method.id === undefined || !struckIds.has(method.id));
+            // On the remove polarity every relation drops the struck ids: the
+            // credential's entry sits under `keyAgreement` alone and the ladder VM
+            // under `assertionMethod` and `capabilityDelegation` alone, so one
+            // filter serves all five without restating either placement here.
+            const relation = (ids) => polarity === 'publish'
+                ? relationIds(ids)
+                : relationIds(ids).filter(id => !struckIds.has(id));
+            const keyAgreement = polarity === 'publish'
+                ? publishesKey
+                    ? [...new Set([...relationIds(doc.keyAgreement), vmId])]
+                    : relationIds(doc.keyAgreement)
+                : relation(doc.keyAgreement);
+            // The ladder VM's two relations, and only those: the asymmetry is what
+            // recognizes it (`ladderVmIds`) and what keeps it out of every client
+            // listing.
+            const withLadderVm = (ids) => installedLadderVmKey === undefined || ladderVmId === undefined
+                ? relationIds(ids)
+                : [...new Set([...relationIds(ids), ladderVmId])];
+            const assertionMethod = polarity === 'publish'
+                ? withLadderVm(doc.assertionMethod)
+                : relation(doc.assertionMethod);
+            const capabilityDelegation = polarity === 'publish'
+                ? withLadderVm(doc.capabilityDelegation)
+                : relation(doc.capabilityDelegation);
+            return {
+                // The byoe context that defines a commitment entry's terms is
+                // installed at genesis and carried forward by every update, so no
+                // edit re-appends it.
+                ...(statedUpdateKeys !== undefined
+                    ? { updateKeys: statedUpdateKeys }
+                    : {}),
+                ...(nextKeyHashes !== undefined ? { nextKeyHashes } : {}),
+                ...(commitHashes.length > 0 ? { commitHashes } : {}),
+                verificationMethods,
+                authentication: relation(doc.authentication),
+                assertionMethod,
+                keyAgreement,
+                capabilityInvocation: relation(doc.capabilityInvocation),
+                capabilityDelegation
+            };
+        }
     });
-    await publishUpdatedLog({ idStore, updated, ifMatch: published.etag });
+    const settledHead = outcome.updated ?? outcome.published;
     return {
-        did: updated.did,
-        doc: updated.doc,
-        log: updated.log,
-        ladderVm: ladderVmReport(updated.doc, struckLadderVmIds)
+        did: settledHead.did,
+        doc: settledHead.doc,
+        log: settledHead.log,
+        ladderVm: ladderVmReport
     };
 }
 //# sourceMappingURL=standingWebvh.js.map