@interop/wallet-core 0.62.0 → 0.66.0

package/dist/clientAnnex/ladderAnchored.js

@@ -38,7 +38,7 @@
  *   whole document inventory out; the last enrolled client refuses
  *   ({@link LastEnrolledClientForgetError}).
  * - {@link strikeLadderVmWebvh} / {@link installLadderVmWebvh} /
- *   {@link forgetLastWebvhClient} -- the entries of the LAST enrolled
+ *   `forgetLastWebvhClient` -- the entries of the LAST enrolled
  *   client's forget (decision 0004's 2026-08-19 amendment): the credential's
  *   own ladder VM struck and then reinstalled while the client stands (the
  *   pair supplying the transition's inventory-changing document version),
@@ -53,12 +53,14 @@
  * from durable state alone, on the recovery continuation's pattern.
  */
 import { deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
-import { assertCanonicalClientKeys, assertCarryOverCommitments, concludeWithPublishedLog, createLadderAnchoredWebvhLog, didWebvhControllerTemplate, genesisNextKeyHashes, ladderVerificationMethod, markedVerificationMethodPair, pinOfLog, publishWebvhLog, putLogResource, readPublishedLog, relationIds, servedHead, updateKeySigner, withLogConflictRetry, writeKeysJson } from '../webvh/didWebvh.js';
+import { assertCanonicalClientKeys, backfillKeyMapWebvhBlock, concludeWithPublishedLog, createLadderAnchoredWebvhLog, didWebvhControllerTemplate, genesisNextKeyHashes, ladderVerificationMethod, markedVerificationMethodPair, pinOfLog, publishEntryPinned, publishWebvhLog, readPublishedLog, readPublishedLogOrThrow, servedHead, updateKeySigner, withLogConflictRetry, writeKeysJson } from '../webvh/didWebvh.js';
+import { putDidWebProjection } from '../webvh/didWebProjection.js';
 import { accountLogPinId } from '../webvh/verifyLog.js';
-import { ladderVmIds } from '../webvh/listClients.js';
+import { ladderVmIds, relationIds } from '../resourceLog/document.js';
 import { clientRemovalFields, clientRemovalTarget } from '../webvh/revokeClient.js';
-import { readLogOrThrow, unlockKeyVerificationMethod } from '../unlock/standingWebvh.js';
+import { unlockKeyVerificationMethod } from '../unlock/standingWebvh.js';
 import { attributeLadderRung, ladderRung, ladderVmKeyMultibase } from './ladder.js';
+import { signAccountEntry } from '../webvh/accountEntry.js';
 /**
  * LADDER-ANCHORED GENESIS: assembles the one-entry did:webvh log of an account
  * with zero enrolled clients, anchored on the minting credential's
@@ -94,7 +96,7 @@ import { attributeLadderRung, ladderRung, ladderVmKeyMultibase } from './ladder.
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
  * @param options.keyAgreement {UnlockKeyAgreementPublication}   the
  *   credential's key-agreement publication (commitment or verbatim)
- * @returns {Promise<{ log: DIDLog, webDoc: object, did: string }>}
+ * @returns {Promise<CreatedWebvhLog>}
  */
 export async function createLadderAnchoredAccountLog({ wasServerUrl, spaceId, didWebKeys, ladderSeed, keyAgreement }) {
     const rung0 = await ladderRung({ ladderSeed, index: 0 });
@@ -145,6 +147,9 @@ export async function createLadderAnchoredAccountLog({ wasServerUrl, spaceId, di
  *   the wallet keeps a KMS; folded into the CREATE path only (see the
  *   adoption note in the body), which also records the minted DID into
  *   keys.json's webvh block as the enrolled-client ensure does
+ * @param [options.keysJsonEtag] {string}   the ETag the KMS-authentication
+ *   stage's own `keys.json` write returned, carried as the `ifMatch` of that
+ *   rewrite
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
  * @param options.keyAgreement {UnlockKeyAgreementPublication}   the
  *   credential's key-agreement publication (commitment or verbatim)
@@ -154,7 +159,18 @@ export async function createLadderAnchoredAccountLog({ wasServerUrl, spaceId, di
  * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
  *   pins; the account log's slot is keyed by `accountLogPinId` over the
  *   `spaceId` above
- * @returns {Promise<{ did: string }>}
+ * @returns {Promise<{ did: string, published: PublishedWebvhLog,
+ *   logMinted: boolean }>}   `published` is the head this stage stands on --
+ *   the served one on the adopt branch, the minted one paired with its
+ *   create PUT's ETag on the create branch -- so the stage after it can build
+ *   on this head instead of re-reading the log this one just read or wrote.
+ *   Its `etag` is absent against a backend that serves none, which is one
+ *   case a later stage must still read for itself. `logMinted` says WHICH
+ *   branch produced it, which a later stage needs before reusing it: a
+ *   minted head is one no other writer could have held a moment ago, while
+ *   an adopted head is a snapshot of an account other clients are free to
+ *   write to, and the parts of it no ETag protects (the document's
+ *   completion tests) can be stale by the time a later stage reads them
  */
 export async function ensureLadderAnchoredDidWebvh(options) {
     return withLogConflictRetry(() => ensureLadderAnchoredDidWebvhOnce(options));
@@ -164,9 +180,10 @@ export async function ensureLadderAnchoredDidWebvh(options) {
  * conflict retry.
  *
  * @param options {object}   see {@link ensureLadderAnchoredDidWebvh}
- * @returns {Promise<{ did: string }>}
+ * @returns {Promise<{ did: string, published: PublishedWebvhLog,
+ *   logMinted: boolean }>}
  */
-async function ensureLadderAnchoredDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys, ladderSeed, keyAgreement, expectedDid, pinStore }) {
+async function ensureLadderAnchoredDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys, keysJsonEtag, ladderSeed, keyAgreement, expectedDid, pinStore }) {
     const logId = accountLogPinId({ spaceId });
     const published = await readPublishedLog({
         idStore,
@@ -184,9 +201,21 @@ async function ensureLadderAnchoredDidWebvhOnce({ idStore, wasServerUrl, spaceId
         // edits it, and a log published without the KMS convenience key is
         // healed by a later login, not here.
         await attributeLadderRung({ ladderSeed, published });
-        // Heals a did.json left lagging by a torn earlier publish.
+        // Heals a keys.json left without its `webvh` block by a run torn between
+        // the genesis entry and the rewrite: the served map's own binding gains
+        // the DID this log resolves to. Gated on this run keeping a KMS, so a
+        // KMS-less wallet spends no read on a resource it never writes.
+        if (didWebKeys) {
+            await backfillKeyMapWebvhBlock({ idStore, did: published.did });
+        }
+        // Heals a did.json left lagging by a torn earlier publish of this
+        // controller-invoking genesis; a lag left by a later ladder-signed entry
+        // is `ensureDidWebProjection`'s to mend.
         const { did } = await concludeWithPublishedLog({ idStore, published });
-        return { did };
+        // The served head verbatim: the projection PUT above touches no log, so
+        // the read's own ETag is still the log's validator. `logMinted: false`
+        // marks it as a snapshot of an account other clients may be writing to.
+        return { did, published, logMinted: false };
     }
     const created = await createLadderAnchoredAccountLog({
         wasServerUrl,
@@ -195,7 +224,7 @@ async function ensureLadderAnchoredDidWebvhOnce({ idStore, wasServerUrl, spaceId
         ladderSeed,
         keyAgreement
     });
-    await publishWebvhLog({
+    const written = await publishWebvhLog({
         idStore,
         log: created.log,
         webDoc: created.webDoc,
@@ -216,26 +245,86 @@ async function ensureLadderAnchoredDidWebvhOnce({ idStore, wasServerUrl, spaceId
         await writeKeysJson({
             idStore,
             didWebKeys,
-            webvh: { did: created.did }
+            webvh: { did: created.did },
+            ...(keysJsonEtag !== undefined && { ifMatch: keysJsonEtag })
         });
     }
-    return { did: created.did };
+    // The head this run just wrote, assembled from what `createDID` already
+    // resolved plus the create PUT's own validator -- no second read, and no
+    // second resolve.
+    return {
+        did: created.did,
+        logMinted: true,
+        published: {
+            log: created.log,
+            did: created.did,
+            doc: created.doc,
+            updateKeys: created.updateKeys,
+            nextKeyHashes: created.nextKeyHashes,
+            ...(written.etag !== undefined ? { etag: written.etag } : {})
+        }
+    };
 }
 /**
- * Publishes `did.jsonl` through the narrow seam -- the log only, never
- * `did.json` (the bridge delegation covers nothing else; the enrolled session
- * republishes the projection once it is the controller). Conditional on the
- * read the entry was built on; a lost race surfaces as a
- * `WebvhLogConflictError` (the mapping lives in `putLogResource`).
+ * ONE LADDER-SIGNED ACCOUNT-LOG ENTRY: the account-entry seam
+ * ({@link signAccountEntry}) on its ladder arm, narrowed to the outcome the
+ * annex's ceremonies read. The seam owns the nine steps -- the pinned read,
+ * the rung attribution, the rung's carry-over hash, the carry-over
+ * precondition, the update-key signer, the self-reveal union into
+ * `updateKeys`, the carry-over union into `nextKeyHashes`, the conditional
+ * publish (`did.jsonl` alone, the bridge's whole reach), and the pin advance.
+ *
+ * No conflict retry of its own: a lost compare-and-swap surfaces as a
+ * `WebvhLogConflictError` for the caller's {@link withLogConflictRetry} to
+ * re-run, which is what re-attributes the rung and climbs to the winner's
+ * committed one (the retry-up-the-ladder resolution).
  *
  * @param options {object}
- * @param options.store {UnlockLogStore}
- * @param options.log {DIDLog}
- * @param [options.ifMatch] {string}   publish only if `did.jsonl` is unchanged
- * @returns {Promise<void>}
+ * @param options.store {UnlockLogStore}   public log read + delegated PUT
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @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
+ *   pins: the read is checked against the pinned head, and the pin advances
+ *   to the head this entry publishes
+ * @param [options.logId] {string}   the account log's pin slot
+ *   (`accountLogPinId({ spaceId })`); required whenever a `pinStore` is
+ *   supplied
+ * @param [options.skip] {function}   `(published) => boolean` -- run on the
+ *   read, before any attribution; `true` returns `skipped` with nothing
+ *   published
+ * @param options.build {function}
+ *   `({ published, rung, state }) => LadderSignedEntry | undefined` -- the
+ *   entry's own members, or `undefined` to decline
+ * @param [options.beforePublish] {function}   `({ updated }) => Promise<void>`
+ *   -- the pre-publish seam, for the ceremonies that PUT their post-entry
+ *   `did:web` projection while the authority they are about to end can still
+ *   write it. See {@link signAccountEntry}
+ * @returns {Promise<LadderSignedEntryOutcome>}
  */
-async function publishLogOnly({ store, log, ifMatch }) {
-    await putLogResource({ store, log, ifMatch });
+export async function ladderSignedAccountEntry({ store, ladderSeed, expectedDid, pinStore, logId, skip, build, beforePublish }) {
+    const outcome = await signAccountEntry({
+        idStore: store,
+        signer: { kind: 'ladder', ladderSeed },
+        build: ({ published, rung, state }) => build({ published, rung: rung, state: state }),
+        ...(skip ? { skip } : {}),
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {}),
+        missingMessage: 'did:webvh: did.jsonl is missing; nothing to enroll into.',
+        ...(beforePublish ? { beforePublish } : {})
+    });
+    if (outcome.skipped) {
+        return { skipped: true, published: outcome.published };
+    }
+    return {
+        skipped: false,
+        published: outcome.published,
+        rung: outcome.rung,
+        rungHash: outcome.rungHash,
+        state: outcome.state,
+        ...(outcome.updated ? { updated: outcome.updated } : {})
+    };
 }
 /**
  * SELF-ENROLLMENT (run by the credential-derived client through the delegated
@@ -406,83 +495,63 @@ export class BuiltOnHeadNotReachedError extends Error {
  * @returns {Promise<{ did: string, webDoc?: object, committed: boolean }>}
  */
 async function selfEnrollWebvhClientOnce({ store, ladderSeed, newClientKeys, newClientUpdateSeeds, onCommitted, builtOnHead, expectedDid, pinStore, logId }) {
-    // Each attempt's own read is what the CAS publish is built on, so the
-    // continuity check runs here -- and again on the retry-up-the-ladder
-    // re-run -- not only on the verify that follows both entries.
-    const pinned = {
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    };
-    let published = await readLogOrThrow({
+    // The reveal-and-commit entry, through the shared preamble and postamble.
+    // It is skipped when a torn earlier run already published it (the rung
+    // revealed AND every needed hash committed).
+    const reveal = await ladderSignedAccountEntry({
         store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...pinned
-    });
-    // The resume marker, checked before anything else -- the completion check
-    // included, so a truncated served log is refused rather than read as "not
-    // complete yet" and rebuilt over.
-    if (builtOnHead) {
-        const genesisScid = published.log[0]?.parameters.scid ?? '';
-        const reached = published.log.some(entry => entry.versionId === builtOnHead.versionId);
-        if (genesisScid !== builtOnHead.scid || !reached) {
-            throw new BuiltOnHeadNotReachedError({ builtOnHead });
-        }
-    }
-    // Already complete (a torn earlier run finished the add entry): the new
-    // client's update key is authorized, which only the add entry writes. The
-    // seam is deliberately NOT entered here -- nothing is about to be
-    // published, so there is no pivot to persist ahead of.
-    if (published.updateKeys.includes(newClientKeys.updateKeyMultibase)) {
-        return { did: published.did, committed: false };
-    }
-    // Which rung is current, recovered from the log itself. Fails closed with
-    // `LadderAttributionError` for a revoked (or never-bound) credential and
-    // for any ambiguous history.
-    const { rung, state } = await attributeLadderRung({ ladderSeed, published });
-    const nextRung = await ladderRung({ ladderSeed, index: rung.index + 1 });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    const newUpdateHash = await deriveNextKeyHash(newClientKeys.updateKeyMultibase);
-    const newStagedHash = await deriveNextKeyHash(newClientKeys.stagedUpdateKeyMultibase);
-    const nextRungHash = await deriveNextKeyHash(nextRung.keyMultibase);
-    // The reveal-and-commit entry, skipped when a torn earlier run already
-    // published it (the rung revealed AND every needed hash committed).
-    const revealed = state === 'revealed';
-    const committed = [newUpdateHash, newStagedHash, nextRungHash].every(hash => published.nextKeyHashes.includes(hash));
-    if (!revealed || !committed) {
-        await assertCarryOverCommitments({ published });
-        const signer = await updateKeySigner({ seed: rung.seed });
-        const updated = await updateDID({
-            log: published.log,
-            signer,
-            alsoKnownAsWeb: true,
-            updateKeys: [...new Set([...published.updateKeys, rung.keyMultibase])],
-            // The spent rung's own hash is kept through this entry (so a resumed
-            // commit can re-state the revealed key); the add entry drops it, while
-            // the next rung's hash stays as the credential's standing commitment.
-            nextKeyHashes: [
-                ...new Set([
-                    ...published.nextKeyHashes,
-                    rungHash,
-                    newUpdateHash,
-                    newStagedHash,
-                    nextRungHash
-                ])
-            ]
-        });
-        await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-        // Advance the pin to what the reveal entry just published, so the re-read
-        // below (and any read after a tear here) refuses a host that rolls the
-        // log back behind it.
-        if (pinStore && logId !== undefined) {
-            await pinStore.write({ logId, pin: pinOfLog(updated.log) });
+        ladderSeed,
+        expectedDid,
+        pinStore,
+        logId,
+        skip: read => {
+            // The resume marker, checked before anything else -- the completion
+            // check included, so a truncated served log is refused rather than read
+            // as "not complete yet" and rebuilt over.
+            if (builtOnHead) {
+                const genesisScid = read.log[0]?.parameters.scid ?? '';
+                const reached = read.log.some(entry => entry.versionId === builtOnHead.versionId);
+                if (genesisScid !== builtOnHead.scid || !reached) {
+                    throw new BuiltOnHeadNotReachedError({ builtOnHead });
+                }
+            }
+            // Already complete (a torn earlier run finished the add entry): the new
+            // client's update key is authorized, which only the add entry writes.
+            // The seam is deliberately NOT entered on this path -- nothing is about
+            // to be published, so there is no pivot to persist ahead of.
+            return read.updateKeys.includes(newClientKeys.updateKeyMultibase);
+        },
+        build: async ({ published: read, rung, state }) => {
+            const nextRung = await ladderRung({ ladderSeed, index: rung.index + 1 });
+            const newUpdateHash = await deriveNextKeyHash(newClientKeys.updateKeyMultibase);
+            const newStagedHash = await deriveNextKeyHash(newClientKeys.stagedUpdateKeyMultibase);
+            const nextRungHash = await deriveNextKeyHash(nextRung.keyMultibase);
+            const committed = [newUpdateHash, newStagedHash, nextRungHash].every(hash => read.nextKeyHashes.includes(hash));
+            if (state === 'revealed' && committed) {
+                return undefined;
+            }
+            // The spent rung's own hash is kept through this entry by the shared
+            // carry-over union (so a resumed commit can re-state the revealed key);
+            // the add entry drops it, while the next rung's hash stays as the
+            // credential's standing commitment. The three land after it, in the
+            // append order `decisions/0007` ratifies.
+            return { commitHashes: [newUpdateHash, newStagedHash, nextRungHash] };
         }
-        // The same account the reveal entry just extended, under the same pin.
-        published = await readLogOrThrow({
-            store,
-            expectedDid: published.did,
-            ...pinned
-        });
+    });
+    if (reveal.skipped) {
+        return { did: reveal.published.did, committed: false };
     }
+    const { rung, rungHash } = reveal;
+    // The same account the reveal entry just extended, under the same pin.
+    const published = reveal.updated
+        ? await readPublishedLogOrThrow({
+            idStore: store,
+            expectedDid: reveal.published.did,
+            pinStore,
+            logId,
+            missingMessage: 'did:webvh: did.jsonl is missing; nothing to enroll into.'
+        })
+        : reveal.published;
     // The persist-before-publish seam: the pending client-key record is
     // persisted client-local HERE, on the head the add entry is about to be
     // built on, before that entry -- the ceremony's pivot -- publishes a client
@@ -536,12 +605,13 @@ async function selfEnrollWebvhClientOnce({ store, ladderSeed, newClientKeys, new
     });
     // Conditional on the read this entry was built on: the re-read above when
     // the commit entry ran here, the first read when it was skipped.
-    await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-    // Advance the pin to what this entry just published, so a host rolling the
-    // log back straight afterwards is refused on the next read.
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
-    }
+    await publishEntryPinned({
+        store,
+        log: updated.log,
+        ifMatch: published.etag,
+        pinStore,
+        logId
+    });
     return { did: updated.did, webDoc: updated.webDoc, committed: true };
 }
 /**
@@ -605,6 +675,13 @@ export class LastEnrolledClientForgetError extends Error {
  * @param options {object}
  * @param options.store {UnlockLogStore}   the credential's delegated
  *   `did.jsonl` bridge store
+ * @param [options.projectionStore] {object}   an `id`-collection store the
+ *   FORGETTING client can still write through (its own root-invoking store):
+ *   the post-removal `did:web` projection is PUT through it immediately
+ *   before the removal entry publishes, and only when this run publishes that
+ *   entry. See {@link clientForgetEntryOnce} for the ordering rationale.
+ *   Omitted, `did.json` keeps naming the forgotten client until some later
+ *   writer runs `ensureDidWebProjection`
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
  * @param options.forgottenClient {RevokedClientKeys}   this client's public
  *   halves; an `updateKeyMultibase` the log does not authorize (stale, or the
@@ -626,120 +703,130 @@ export class LastEnrolledClientForgetError extends Error {
  *   on the idempotent no-op path)
  */
 export async function forgetWebvhClient(options) {
-    return withLogConflictRetry(() => clientForgetEntryOnce({ ...options, transition: false }));
+    return withLogConflictRetry(() => clientForgetEntryOnce({ ...options, assertRemovable: assertNotLastClient }));
 }
 /**
- * THE LAST-CLIENT REMOVAL ENTRY (the two-entry transition ceremony's second
- * entry): {@link forgetWebvhClient}'s removal shape with the last-client
- * refusal inverted -- the forgotten client IS the last enrolled client, and
- * the account stays invocable because the ladder VM the install entry
- * published ({@link installLadderVmWebvh}) remains in the document. A
- * document NOT carrying this credential's ladder VM refuses: publishing the
- * entry would strand the account with neither an enrolled client nor the
- * ladder anchor. Run only from the composed ceremony
- * (`forgetLastEnrolledClient`), which sequences the install entry and the
- * delegation revocations before it.
+ * The plain forget's removability invariant: `capabilityInvocation` lists
+ * exactly the enrolled clients' signing keys (a recovery code's key is
+ * `keyAgreement`-only and the KMS convenience key `authentication`-only), so
+ * the forgotten client standing alone there means removing it strands the
+ * account. The transition ceremony supplies its own invariant instead
+ * (`forgetLast.ts`), which is why this one is injected rather than selected
+ * by a flag inside the shared entry builder.
  *
- * @param options {object}   see {@link forgetWebvhClient}
- * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
+ * @param options {object}
+ * @param options.published {PublishedWebvhLog}
+ * @param options.target {ClientRemovalTarget}
+ * @returns {void}
  */
-export async function forgetLastWebvhClient(options) {
-    return withLogConflictRetry(() => clientForgetEntryOnce({ ...options, transition: true }));
+function assertNotLastClient({ published, target }) {
+    const invocationIds = relationIds(published.doc.capabilityInvocation);
+    if (invocationIds.includes(target.signingVmId) &&
+        invocationIds.every(id => id === target.signingVmId)) {
+        throw new LastEnrolledClientForgetError();
+    }
 }
 /**
- * One attempt of {@link forgetWebvhClient} or {@link forgetLastWebvhClient},
- * re-invoked by the conflict retry. The two share everything but the guard:
- * the plain forget refuses the last enrolled client, the transition removal
- * requires the ladder VM already installed instead.
+ * One attempt of {@link forgetWebvhClient} or `forgetLastWebvhClient`
+ * (`forgetLast.ts`), re-invoked by their conflict retries. The two share the
+ * whole removal entry and differ only in what makes the removal admissible,
+ * which each supplies as `assertRemovable` -- the plain forget refuses the
+ * last enrolled client, the transition removal requires the ladder VM already
+ * installed. The invariant travels with the ceremony that owns it rather than
+ * living here as a flag.
+ *
+ * THE PROJECTION IS PUBLISHED BEFORE THE ENTRY, and the order is forced: the
+ * removal entry is ladder-signed and publishes `did.jsonl` alone (the bridge
+ * delegation covers nothing else), while the forgotten client's authority
+ * dies at that entry under the current-key-set rule. So the post-removal
+ * `did:web` projection has to be written while that client can still write
+ * it. A run torn between the projection PUT and the entry leaves `did.json`
+ * omitting a client the log still lists, which is fail-closed for a `did:web`
+ * verifier and is re-PUT by the re-run; the reverse order would leave the
+ * revoked client standing in `did.json` with nothing left able to remove it.
+ * The idempotent already-forgotten path writes no projection at all: the
+ * removal entry landed on an earlier run, so this client's authority is
+ * already gone and its store can only be refused. A projection that path
+ * leaves stale is mended by the next transient visit's
+ * `ensureDidWebProjection`, which invokes under its generation delegation.
  *
  * @param options {object}   see {@link forgetWebvhClient}, plus:
- * @param options.transition {boolean}   `true` for the last-client removal
- *   entry (require the installed ladder VM), `false` for the plain forget
- *   (refuse the last client)
+ * @param options.assertRemovable {function}
+ *   `({ published, target }) => void` -- run on the read, after the
+ *   idempotent already-forgotten check and before anything is attributed or
+ *   built; it throws to refuse the removal
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-async function clientForgetEntryOnce({ store, ladderSeed, forgottenClient, knownLatentHashes = [], expectedDid, pinStore, logId, transition }) {
-    // Each attempt's own read is what the CAS publish is built on, so the
-    // continuity check runs here, not only on the orchestrator's pre-read.
-    const published = await readLogOrThrow({
+export async function clientForgetEntryOnce({ store, projectionStore, ladderSeed, forgottenClient, knownLatentHashes = [], expectedDid, pinStore, logId, assertRemovable }) {
+    // Resolved by the skip hook on the read the entry is built on, and used by
+    // the build below -- the same snapshot, never a second read.
+    let target;
+    const entry = await ladderSignedAccountEntry({
         store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
-    const { did, doc } = published;
-    const target = await clientRemovalTarget({
-        published,
-        client: forgottenClient
-    });
-    if (!target.present) {
-        // Already forgotten (a torn earlier run finished the entry). No did.json
-        // heal here: the bridge covers did.jsonl only.
-        return { did, doc, log: published.log };
-    }
-    if (transition) {
-        // The no-neither invariant, checked rather than assumed: the removal may
-        // only publish while the ladder VM stands in the document (the install
-        // entry ran), or the account would land with nothing that can anchor it.
-        const ladderVmId = `${did}#${await ladderVmKeyMultibase({ ladderSeed })}`;
-        if (!ladderVmIds({ doc }).includes(ladderVmId)) {
-            throw new Error('did:webvh: the ladder VM is not installed in the document; the ' +
-                'last-client removal entry would strand the account (the install ' +
-                'entry runs first).');
-        }
-    }
-    else {
-        // The last-client refusal: capabilityInvocation lists exactly the
-        // enrolled clients' signing keys (a recovery code's key is
-        // keyAgreement-only and the KMS convenience authentication-only), so the
-        // forgotten client standing alone there means removing it strands the
-        // account.
-        const invocationIds = relationIds(doc.capabilityInvocation);
-        if (invocationIds.includes(target.signingVmId) &&
-            invocationIds.every(id => id === target.signingVmId)) {
-            throw new LastEnrolledClientForgetError();
-        }
-    }
-    // Which rung is current, recovered from the log itself. Fails closed with
-    // `LadderAttributionError` for a revoked (or never-bound) credential and
-    // for any ambiguous history.
-    const { rung } = await attributeLadderRung({ ladderSeed, published });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    await assertCarryOverCommitments({ published });
-    // The ladder vouches for its own commitments: a self-enrolled client's
-    // staged hash was committed in the same reveal entry as the next rung's
-    // hash, so without these the staged-hash attribution cannot tell the two
-    // apart. Every hash a reveal entry can have committed is for a rung at or
-    // one past the current index.
-    const ladderHashes = [];
-    for (let index = 0; index <= rung.index + 1; index++) {
-        const laddered = await ladderRung({ ladderSeed, index });
-        ladderHashes.push(await deriveNextKeyHash(laddered.keyMultibase));
-    }
-    const fields = await clientRemovalFields({
-        published,
-        target,
-        knownLatentHashes: [...knownLatentHashes, ...ladderHashes]
-    });
-    const signer = await updateKeySigner({ seed: rung.seed });
-    const updated = await updateDID({
-        log: published.log,
-        signer,
-        alsoKnownAsWeb: true,
-        ...fields,
-        // The acting rung reveals itself in the entry it signs (its hash stands
-        // committed, or the rung is already revealed), and its own hash is kept
-        // committed so the carry-over convention holds for the next entry.
-        updateKeys: [...new Set([...fields.updateKeys, rung.keyMultibase])],
-        nextKeyHashes: [...new Set([...fields.nextKeyHashes, rungHash])]
+        ladderSeed,
+        expectedDid,
+        pinStore,
+        logId,
+        skip: async (published) => {
+            target = await clientRemovalTarget({
+                published,
+                client: forgottenClient
+            });
+            if (!target.present) {
+                // Already forgotten (a torn earlier run finished the entry). No
+                // projection is written on this path: this client's verification
+                // methods left the document with that entry, so its store is
+                // authorized for nothing. The next transient visit's
+                // `ensureDidWebProjection` is the mender.
+                return true;
+            }
+            await assertRemovable({ published, target });
+            return false;
+        },
+        build: async ({ published, rung }) => {
+            // The ladder vouches for its own commitments: a self-enrolled client's
+            // staged hash was committed in the same reveal entry as the next rung's
+            // hash, so without these the staged-hash attribution cannot tell the
+            // two apart. Every hash a reveal entry can have committed is for a rung
+            // at or one past the current index.
+            const ladderHashes = [];
+            for (let index = 0; index <= rung.index + 1; index++) {
+                const laddered = await ladderRung({ ladderSeed, index });
+                ladderHashes.push(await deriveNextKeyHash(laddered.keyMultibase));
+            }
+            // The removal's own filtered sets; the acting rung's key and hash are
+            // unioned back in by the shared carry-over conventions.
+            return clientRemovalFields({
+                published,
+                target: target,
+                knownLatentHashes: [...knownLatentHashes, ...ladderHashes]
+            });
+        },
+        // The post-removal projection, published while the client being removed
+        // can still write it (see the header). `webDoc` is the `alsoKnownAsWeb`
+        // projection `ladderSignedAccountEntry` always asks `updateDID` for.
+        ...(projectionStore
+            ? {
+                beforePublish: async ({ updated }) => {
+                    if (!updated.webDoc) {
+                        // `publishUpdatedLog` states the same invariant: every entry is
+                        // built with `alsoKnownAsWeb`, so a missing projection is a
+                        // defect. Refusing here is what keeps the removal entry from
+                        // publishing with `did.json` left naming the removed client,
+                        // which on a client-less account nothing could mend.
+                        throw new Error('did:webvh: updateDID returned no webDoc despite the ' +
+                            'did:web alsoKnownAs.');
+                    }
+                    await putDidWebProjection({
+                        store: projectionStore,
+                        webDoc: updated.webDoc
+                    });
+                }
+            }
+            : {})
     });
-    await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-    // Advance the pin to what this entry just published, so a host rolling the
-    // log back straight afterwards is refused on the next read.
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
-    }
-    return { did: updated.did, doc: updated.doc, log: updated.log };
+    const settled = entry.updated ?? entry.published;
+    return { did: settled.did, doc: settled.doc, log: settled.log };
 }
 /**
  * THE LADDER-VM INSTALL ENTRY (the two-entry transition ceremony's first
@@ -794,72 +881,83 @@ export async function installLadderVmWebvh(options) {
  * @param options {object}   see {@link installLadderVmWebvh}
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog, installed: boolean }>}
  */
-async function installLadderVmWebvhOnce({ store, ladderSeed, expectedDid, pinStore, logId }) {
-    // Each attempt's own read is what the CAS publish is built on, so the
-    // continuity check runs here, not only on the orchestrator's pre-read.
-    const published = await readLogOrThrow({
-        store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
+async function installLadderVmWebvhOnce(options) {
+    const { changed, ...settled } = await setLadderVmPresenceOnce({
+        ...options,
+        present: true
     });
-    const { did, doc } = published;
+    return { ...settled, installed: changed };
+}
+/**
+ * ONE LADDER-VM PRESENCE ENTRY, in either direction: `present: true`
+ * publishes this credential's ladder VM, `present: false` strikes it, and the
+ * entries are otherwise the same edit read backwards -- the VM in or out of
+ * `verificationMethod`, `assertionMethod`, and `capabilityDelegation`, with
+ * `authentication`, `keyAgreement`, and `capabilityInvocation` re-stated
+ * untouched. That relation asymmetry (`assertionMethod` and
+ * `capabilityDelegation` only, never `authentication` or
+ * `capabilityInvocation`) is what the recognition reads and what keeps a
+ * ladder VM out of every client listing, so the two directions must agree on
+ * it exactly; stating it once is the point of the merge.
+ *
+ * The id derives from the ladder seed, so the entry reaches ONE credential's
+ * VM: another standing credential's ladder VM, and every enrolled client's
+ * inventory, stand untouched. Idempotent in both directions -- a document
+ * already in the asked-for state is a no-op returning `changed: false`,
+ * detected BEFORE the rung attribution so a re-run over a retired credential
+ * returns unchanged rather than failing closed.
+ *
+ * @param options {object}   see {@link installLadderVmWebvh}, plus:
+ * @param options.present {boolean}   the state the entry leaves the ladder VM
+ *   in
+ * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog, changed: boolean }>}
+ */
+async function setLadderVmPresenceOnce({ store, ladderSeed, expectedDid, pinStore, logId, present }) {
     const ladderVmKey = await ladderVmKeyMultibase({ ladderSeed });
-    const ladderVmId = `${did}#${ladderVmKey}`;
-    if (ladderVmIds({ doc }).includes(ladderVmId)) {
-        // Already installed (a torn earlier run published the entry, or the
-        // account is mid-transition).
-        return { did, doc, log: published.log, installed: false };
-    }
-    // Which rung is current, recovered from the log itself. Fails closed with
-    // `LadderAttributionError` for a revoked (or never-bound) credential and
-    // for any ambiguous history.
-    const { rung } = await attributeLadderRung({ ladderSeed, published });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    await assertCarryOverCommitments({ published });
-    const existingMethods = (doc.verificationMethod ?? []);
-    const verificationMethods = [
-        ...existingMethods.filter(method => method.id !== ladderVmId),
-        ladderVerificationMethod({
-            controller: did,
-            publicKeyMultibase: ladderVmKey
-        })
-    ];
-    // The ladder VM's relation asymmetry: `assertionMethod` and
-    // `capabilityDelegation` only -- no `authentication`, no
-    // `capabilityInvocation` -- which is also what keeps it out of every client
-    // listing.
-    const withVm = (relation) => [
-        ...new Set([...relationIds(relation), ladderVmId])
-    ];
-    const signer = await updateKeySigner({ seed: rung.seed });
-    const updated = await updateDID({
-        log: published.log,
-        signer,
-        alsoKnownAsWeb: true,
-        // The acting rung reveals itself in the entry it signs (its hash stands
-        // committed, or the rung is already revealed), and its own hash is kept
-        // committed so the carry-over convention holds for the next entry.
-        updateKeys: [...new Set([...published.updateKeys, rung.keyMultibase])],
-        nextKeyHashes: [...new Set([...published.nextKeyHashes, rungHash])],
-        verificationMethods,
-        authentication: relationIds(doc.authentication),
-        assertionMethod: withVm(doc.assertionMethod),
-        keyAgreement: relationIds(doc.keyAgreement),
-        capabilityInvocation: relationIds(doc.capabilityInvocation),
-        capabilityDelegation: withVm(doc.capabilityDelegation)
+    const entry = await ladderSignedAccountEntry({
+        store,
+        ladderSeed,
+        expectedDid,
+        pinStore,
+        logId,
+        // Already in the asked-for state: a torn earlier run published the entry,
+        // the account is mid-transition, or the credential never bound a VM here.
+        skip: published => ladderVmIds({ doc: published.doc }).includes(`${published.did}#${ladderVmKey}`) === present,
+        build: ({ published }) => {
+            const { did, doc } = published;
+            const ladderVmId = `${did}#${ladderVmKey}`;
+            const withoutVm = (relation) => relationIds(relation).filter(id => id !== ladderVmId);
+            const withVm = (relation) => [...new Set([...relationIds(relation), ladderVmId])];
+            const inRelation = present ? withVm : withoutVm;
+            const otherMethods = (doc.verificationMethod ?? []).filter(method => method.id !== ladderVmId);
+            return {
+                verificationMethods: present
+                    ? [
+                        ...otherMethods,
+                        ladderVerificationMethod({
+                            controller: did,
+                            publicKeyMultibase: ladderVmKey
+                        })
+                    ]
+                    : otherMethods,
+                // The ladder VM's relation asymmetry: `assertionMethod` and
+                // `capabilityDelegation` only -- no `authentication`, no
+                // `capabilityInvocation` -- which is also what keeps it out of every
+                // client listing.
+                authentication: relationIds(doc.authentication),
+                assertionMethod: inRelation(doc.assertionMethod),
+                keyAgreement: relationIds(doc.keyAgreement),
+                capabilityInvocation: relationIds(doc.capabilityInvocation),
+                capabilityDelegation: inRelation(doc.capabilityDelegation)
+            };
+        }
     });
-    await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-    // Advance the pin to what this entry just published, so a host rolling the
-    // log back straight afterwards is refused on the next read.
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
-    }
+    const settled = entry.updated ?? entry.published;
     return {
-        did: updated.did,
-        doc: updated.doc,
-        log: updated.log,
-        installed: true
+        did: settled.did,
+        doc: settled.doc,
+        log: settled.log,
+        changed: entry.updated !== undefined
     };
 }
 /**
@@ -916,54 +1014,12 @@ export async function strikeLadderVmWebvh(options) {
  * @param options {object}   see {@link strikeLadderVmWebvh}
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog, struck: boolean }>}
  */
-async function strikeLadderVmWebvhOnce({ store, ladderSeed, expectedDid, pinStore, logId }) {
-    // Each attempt's own read is what the CAS publish is built on, so the
-    // continuity check runs here, not only on the orchestrator's pre-read.
-    const published = await readLogOrThrow({
-        store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
-    const { did, doc } = published;
-    const ladderVmId = `${did}#${await ladderVmKeyMultibase({ ladderSeed })}`;
-    if (!ladderVmIds({ doc }).includes(ladderVmId)) {
-        // Nothing of this credential's to strike (a torn earlier run published
-        // the entry, or the credential never bound a VM here).
-        return { did, doc, log: published.log, struck: false };
-    }
-    // Which rung is current, recovered from the log itself. Fails closed with
-    // `LadderAttributionError` for a revoked (or never-bound) credential and
-    // for any ambiguous history.
-    const { rung } = await attributeLadderRung({ ladderSeed, published });
-    const rungHash = await deriveNextKeyHash(rung.keyMultibase);
-    await assertCarryOverCommitments({ published });
-    const existingMethods = (doc.verificationMethod ?? []);
-    const withoutVm = (relation) => relationIds(relation).filter(id => id !== ladderVmId);
-    const signer = await updateKeySigner({ seed: rung.seed });
-    const updated = await updateDID({
-        log: published.log,
-        signer,
-        alsoKnownAsWeb: true,
-        // The acting rung reveals itself in the entry it signs (its hash stands
-        // committed, or the rung is already revealed), and its own hash is kept
-        // committed so the carry-over convention holds for the next entry.
-        updateKeys: [...new Set([...published.updateKeys, rung.keyMultibase])],
-        nextKeyHashes: [...new Set([...published.nextKeyHashes, rungHash])],
-        verificationMethods: existingMethods.filter(method => method.id !== ladderVmId),
-        authentication: relationIds(doc.authentication),
-        assertionMethod: withoutVm(doc.assertionMethod),
-        keyAgreement: relationIds(doc.keyAgreement),
-        capabilityInvocation: relationIds(doc.capabilityInvocation),
-        capabilityDelegation: withoutVm(doc.capabilityDelegation)
+async function strikeLadderVmWebvhOnce(options) {
+    const { changed, ...settled } = await setLadderVmPresenceOnce({
+        ...options,
+        present: false
     });
-    await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-    // Advance the pin to what this entry just published, so a host rolling the
-    // log back straight afterwards is refused on the next read.
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
-    }
-    return { did: updated.did, doc: updated.doc, log: updated.log, struck: true };
+    return { ...settled, struck: changed };
 }
 /**
  * THE STANDALONE REVEAL-AND-COMMIT ENTRY: reveals this credential's currently
@@ -1005,38 +1061,27 @@ async function strikeLadderVmWebvhOnce({ store, ladderSeed, expectedDid, pinStor
  *   entry
  */
 export async function revealLadderRungWebvh({ store, ladderSeed, expectedDid, pinStore, logId }) {
-    const published = await readLogOrThrow({
+    const entry = await ladderSignedAccountEntry({
         store,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore ? { pinStore } : {}),
-        ...(logId !== undefined ? { logId } : {})
-    });
-    const { rung, state } = await attributeLadderRung({ ladderSeed, published });
-    if (state === 'revealed') {
-        return { revealed: false };
-    }
-    await assertCarryOverCommitments({ published });
-    const nextRung = await ladderRung({ ladderSeed, index: rung.index + 1 });
-    const signer = await updateKeySigner({ seed: rung.seed });
-    const updated = await updateDID({
-        log: published.log,
-        signer,
-        alsoKnownAsWeb: true,
-        updateKeys: [...new Set([...published.updateKeys, rung.keyMultibase])],
-        nextKeyHashes: [
-            ...new Set([
-                ...published.nextKeyHashes,
-                await deriveNextKeyHash(rung.keyMultibase),
-                await deriveNextKeyHash(nextRung.keyMultibase)
-            ])
-        ]
+        ladderSeed,
+        expectedDid,
+        pinStore,
+        logId,
+        build: async ({ rung, state }) => {
+            // A rung already revealed (a torn earlier run, or a racing ceremony
+            // that got there first) leaves nothing to publish. The decline sits
+            // after the attribution because the attribution is what answers it.
+            if (state === 'revealed') {
+                return undefined;
+            }
+            // The entry commits the next rung only; the acting rung's own key and
+            // carry-over hash come from the shared reveal and carry-over unions.
+            const nextRung = await ladderRung({ ladderSeed, index: rung.index + 1 });
+            return {
+                commitHashes: [await deriveNextKeyHash(nextRung.keyMultibase)]
+            };
+        }
     });
-    await publishLogOnly({ store, log: updated.log, ifMatch: published.etag });
-    // Advance the pin to what this entry just published, so a host rolling the
-    // log back straight afterwards is refused on the next read.
-    if (pinStore && logId !== undefined) {
-        await pinStore.write({ logId, pin: pinOfLog(updated.log) });
-    }
-    return { revealed: true };
+    return { revealed: entry.updated !== undefined };
 }
 //# sourceMappingURL=ladderAnchored.js.map