@interop/wallet-core 0.48.0 → 0.50.0

package/dist/{webvh/companion.js → clientAnnex/log.js}

@@ -2,25 +2,25 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The companion did:webvh: the disposable sidecar log holding transient
+ * The client annex did:webvh: the disposable sidecar log holding transient
  * per-visit verification methods, one generation per flat `gen-` collection
- * inside the account's stable auxiliary companion Space -- so per-visit facts
+ * inside the account's stable auxiliary annex Space -- so per-visit facts
  * stay out of the account's identity log entirely. This module is the
  * generation's identity, genesis, and enrollment machinery: the
- * `gen-<random>` segment convention, the typed auxiliary Space ensure, the
- * genesis parameters, the pin-slot key for companion continuity, the atomic
+ * `gen-<random>` generation id convention, the typed auxiliary Space ensure,
+ * the genesis parameters, the pin-slot key for annex continuity, the atomic
  * transient-enrollment entry, and the account document's delegated-clients
  * service entry (the pointer at the current generation).
  *
- * The companion's posture differs from the account log's on purpose:
+ * The annex's posture differs from the account log's on purpose:
  *
- * - Update authority is each standing credential's static companion rung 0
+ * - Update authority is each standing credential's static annex rung 0
  *   (chain length one, no rung advancement, no attribution scan). Genesis
  *   states the minting credential's rung-0 key in `updateKeys` and commits
  *   every standing credential's rung-0 hash in `nextKeyHashes` -- the minting
  *   key's own carry-over hash included, or no later entry could re-state it.
  * - Prerotation stays on (the rung-0 hashes are the commitment chain),
- *   witnesses stay off, and portability is off: a companion is
+ *   witnesses stay off, and portability is off: an annex is
  *   generation-scoped and host-bound, and replacement is a GC swap, never a
  *   portability move.
  * - The genesis document is bare -- no verification methods, no service
@@ -32,20 +32,20 @@
  * - No `did:web` projection exists: the generation collection holds only its
  *   `did.jsonl`, capability-gated rather than world-readable.
  *
- * Ordering rule: the companion log publishes FIRST; only then does the
+ * Ordering rule: the annex log publishes FIRST; only then does the
  * caller re-point the account document's `#DelegatedClients` service entry at
- * the new companion DID. A companion nobody points at is authorization-inert
+ * the new annex DID. An annex nobody points at is authorization-inert
  * (no delegation ever names it), so a tear or a double-genesis race leaks
  * storage, never authority -- and the standing orphan discovery is a plain
  * `gen-` prefix match over the auxiliary Space's collection listing, with no
  * registry of generations anywhere.
  *
- * Generation identity is random, never a counter: a reused segment would
+ * Generation identity is random, never a counter: a reused generation id would
  * re-derive the same rung-0 update key for a new generation, and no counter
- * carrier survives GC deleting the old collection. The segment is also the
- * generation-identifying half of the companion rung HKDF labels
- * (`<segment>/rung/<k>` under the unlock ladder's one salt), so there is
- * exactly one spelling of a generation's identity -- the one the companion
+ * carrier survives GC deleting the old collection. The generation id is also
+ * the generation-identifying half of the annex rung HKDF labels
+ * (`<generationId>/rung/<k>` under the unlock ladder's one salt), so there is
+ * exactly one spelling of a generation's identity -- the one the annex
  * DID string already embeds.
  */
 import { createDID, deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
@@ -53,92 +53,94 @@ import { rootCapabilityId, spaceItems, spacePath, toUrl } from '@interop/was-cli
 import { base64urlnopad } from '@scure/base';
 import { DID_LOG_RESOURCE } from '../space/collections.js';
 import { resourceLogPinId } from '../resourceLog/pin.js';
-import { companionRung } from '../unlock/ladder.js';
-import { assertCarryOverCommitments, concludeWithPublishedLog, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, publishUpdatedLog, putLogResource, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } from './didWebvh.js';
-import { STANDING_ZCAP_TTL_MS, zcapExpiring } from './standingZcap.js';
-import { wasWebvhLogStore } from './wasIdStore.js';
+import { clientAnnexRung } from './ladder.js';
+import { assertCarryOverCommitments, concludeWithPublishedLog, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, publishUpdatedLog, putLogResource, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } from '../webvh/didWebvh.js';
+import { delegationKeyInDocument } from '../webvh/listClients.js';
+import { delegationProofKeyId, STANDING_ZCAP_TTL_MS, zcapExpiring } from '../webvh/standingZcap.js';
+import { wasWebvhLogStore } from '../webvh/wasIdStore.js';
 /**
- * The Space Description `type` array of the auxiliary companion Space, set at
+ * The Space Description `type` array of the auxiliary annex Space, set at
  * creation (the server treats a Space's `type` as immutable afterwards).
  * Wire-level and permanent: the server's inspector clause recognizes the
  * `DelegatedClientsSpace` member, and user-data surfaces exclude auxiliary
  * Spaces by it.
  */
-export const COMPANION_SPACE_TYPE = [
+export const CLIENT_ANNEX_SPACE_TYPE = [
     'Space',
     'AuxiliarySpace',
     'DelegatedClientsSpace'
 ];
 /**
  * The `type` member that marks a Space as the delegated-clients auxiliary
- * Space (the last entry of {@link COMPANION_SPACE_TYPE}).
+ * Space (the last entry of {@link CLIENT_ANNEX_SPACE_TYPE}).
  */
 const DELEGATED_CLIENTS_SPACE_TYPE = 'DelegatedClientsSpace';
 /**
  * The literal prefix of every generation collection's name. Wire-level and
  * permanent: orphan discovery is a plain prefix match over the auxiliary
- * Space's collection listing, and the segment embeds in every companion DID
- * string ever published.
+ * Space's collection listing, and the generation id embeds in every annex
+ * DID string ever published.
  */
-export const GENERATION_SEGMENT_PREFIX = 'gen-';
+export const GENERATION_ID_PREFIX = 'gen-';
 /**
  * The random suffix: 12 bytes, base64url-no-pad (16 characters), for 20
  * characters total. Every character is inside the server's `[A-Za-z0-9._~-]+`
- * id allowlist, so `encodeURIComponent` is the identity on the segment and
- * the DID path encoding round-trips it.
+ * id allowlist, so `encodeURIComponent` is the identity on the generation id
+ * and the DID path encoding round-trips it.
  */
-const GENERATION_SEGMENT_SUFFIX_BYTES = 12;
+const GENERATION_ID_SUFFIX_BYTES = 12;
 /**
- * The full segment shape: the literal prefix plus 16 base64url characters.
+ * The full generation id shape: the literal prefix plus 16 base64url
+ * characters.
  */
-const GENERATION_SEGMENT_PATTERN = /^gen-[A-Za-z0-9_-]{16}$/;
+const GENERATION_ID_PATTERN = /^gen-[A-Za-z0-9_-]{16}$/;
 /**
- * Mints a fresh generation segment -- the generation collection's name, e.g.
+ * Mints a fresh generation id -- the generation collection's name, e.g.
  * `gen-Ux3v0kQf9aPmB2hZ`. Random rather than a counter on purpose: never-reuse
  * is structural (nothing durable survives GC to carry a counter), at the same
  * probabilistic order as every other random-id convention in the system.
  *
  * @returns {string}
  */
-export function mintGenerationSegment() {
-    return (GENERATION_SEGMENT_PREFIX +
-        base64urlnopad.encode(crypto.getRandomValues(new Uint8Array(GENERATION_SEGMENT_SUFFIX_BYTES))));
+export function mintGenerationId() {
+    return (GENERATION_ID_PREFIX +
+        base64urlnopad.encode(crypto.getRandomValues(new Uint8Array(GENERATION_ID_SUFFIX_BYTES))));
 }
 /**
- * Refuses anything that is not a well-formed generation segment. Run by every
- * companion builder that takes a segment, so a malformed one is refused
+ * Refuses anything that is not a well-formed generation id. Run by every
+ * annex builder that takes a generation id, so a malformed one is refused
  * before it can reach a DID string, an HKDF label, or a collection id.
  *
- * @param segment {string}
+ * @param generationId {string}
  */
-export function assertGenerationSegment(segment) {
-    if (!GENERATION_SEGMENT_PATTERN.test(segment)) {
-        throw new Error(`Not a generation segment: "${segment}" (expected "gen-" plus 16 ` +
+export function assertGenerationId(generationId) {
+    if (!GENERATION_ID_PATTERN.test(generationId)) {
+        throw new Error(`Not a generation id: "${generationId}" (expected "gen-" plus 16 ` +
             'base64url characters).');
     }
 }
 /**
- * The pin-slot key for one companion generation's log -- host-free like every
- * pin-slot key, keyed by the auxiliary Space id and the generation segment.
+ * The pin-slot key for one annex generation's log -- host-free like every
+ * pin-slot key, keyed by the auxiliary Space id and the generation id.
  * A transient session keeps this slot in an in-memory pin store (a durable
  * pin is the wrong lifetime for a disposable log, and a transient session
  * must not durably create the pin store on a read); a durable client's store
- * clears companion slots when the generation is collected.
+ * clears annex slots when the generation is collected.
  *
  * @param options {object}
- * @param options.spaceId {string}   the auxiliary companion Space's id
- * @param options.segment {string}   the generation collection's name
+ * @param options.spaceId {string}   the auxiliary annex Space's id
+ * @param options.generationId {string}   the generation collection's name
  * @returns {string}
  */
-export function companionLogPinId({ spaceId, segment }) {
+export function clientAnnexLogPinId({ spaceId, generationId }) {
     return resourceLogPinId({
         spaceId,
-        collectionId: segment,
+        collectionId: generationId,
         resourceId: DID_LOG_RESOURCE
     });
 }
 /**
- * The WAS-backed store a companion generation's ceremonies read and publish
+ * The WAS-backed store an annex generation's ceremonies read and publish
  * through with controller-tier signing (an enrolled client). A transient
  * session writes through the delegated store instead
  * (`delegatedWebvhLogStore`, invoking the credential's sibling delegation);
@@ -146,16 +148,24 @@ export function companionLogPinId({ spaceId, segment }) {
  *
  * @param options {object}
  * @param options.was {WasClient}
- * @param options.spaceId {string}   the auxiliary companion Space's id
- * @param options.segment {string}   the generation collection's name
+ * @param options.spaceId {string}   the auxiliary annex Space's id
+ * @param options.generationId {string}   the generation collection's name
+ * @param [options.capability] {IZcap}   an invocation capability every request
+ *   rides (the sibling delegation, where the caller is not an enrolled
+ *   invoker); absent, requests invoke the root capability
  * @returns {WebvhLogResourceStore}
  */
-export function companionLogStore({ was, spaceId, segment }) {
-    assertGenerationSegment(segment);
-    return wasWebvhLogStore({ was, spaceId, collectionId: segment });
+export function clientAnnexLogStore({ was, spaceId, generationId, capability }) {
+    assertGenerationId(generationId);
+    return wasWebvhLogStore({
+        was,
+        spaceId,
+        collectionId: generationId,
+        ...(capability !== undefined ? { capability } : {})
+    });
 }
 /**
- * The DID core context -- the companion genesis document's whole `@context`.
+ * The DID core context -- the annex genesis document's whole `@context`.
  * The document carries no verification methods and no service entries at
  * genesis, so no other vocabulary is in scope; the entry that first publishes
  * a typed member extends the context then (a did:webvh entry replaces the
@@ -163,23 +173,23 @@ export function companionLogStore({ was, spaceId, segment }) {
  */
 const DID_CORE_CONTEXT = 'https://www.w3.org/ns/did/v1';
 /**
- * The Multikey context, appended to the companion document's `@context` by
+ * The Multikey context, appended to the annex document's `@context` by
  * the entry that first publishes a transient verification method (genesis
  * carries the DID core context only, having no typed members to define).
  */
 const MULTIKEY_CONTEXT_URL = 'https://w3id.org/security/multikey/v1';
 /**
- * Creates the one-entry companion generation log. The genesis parameters are
- * the companion posture (see the module doc): prerotation on via the rung-0
+ * Creates the one-entry annex generation log. The genesis parameters are
+ * the annex posture (see the module doc): prerotation on via the rung-0
  * hash commitments, no witnesses, portability off (the library's default,
  * stated explicitly in the emitted entry), and a bare document -- id and the
  * DID core context, nothing else.
  *
  * The caller supplies the update authority: the minting credential's
- * companion rung-0 key as the sole `updateKeys` member, `nextKeyHashes` as
+ * annex rung-0 key as the sole `updateKeys` member, `nextKeyHashes` as
  * every standing credential's rung-0 hash (restated explicitly on every later
  * entry, never inherited), and rung 0's signer. The minting key's own
- * carry-over hash MUST be among the commitments -- every companion entry
+ * carry-over hash MUST be among the commitments -- every annex entry
  * re-states `updateKeys` containing the revealed rung-0 keys, and the
  * resolver checks the re-statement against the previous entry's commitments
  * -- so a `nextKeyHashes` that omits it is refused here rather than
@@ -187,20 +197,20 @@ const MULTIKEY_CONTEXT_URL = 'https://w3id.org/security/multikey/v1';
  *
  * @param options {object}
  * @param options.wasServerUrl {string}
- * @param options.spaceId {string}   the auxiliary companion Space's id
- * @param options.segment {string}   the generation collection's name
+ * @param options.spaceId {string}   the auxiliary annex Space's id
+ * @param options.generationId {string}   the generation collection's name
  * @param options.updateKeyPublicKeyMultibase {string}   the minting
- *   credential's companion rung-0 key
+ *   credential's annex rung-0 key
  * @param options.nextKeyHashes {string[]}   every standing credential's
  *   rung-0 hash, the minting credential's included
  * @param options.signer {Signer}   the minting credential's rung-0 signer
  * @returns {Promise<{ log: DIDLog; did: string; doc: DIDDoc }>}
  */
-export async function createCompanionLog({ wasServerUrl, spaceId, segment, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
-    assertGenerationSegment(segment);
+export async function createClientAnnexLog({ wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
+    assertGenerationId(generationId);
     const carryOverHash = await deriveNextKeyHash(updateKeyPublicKeyMultibase);
     if (!nextKeyHashes.includes(carryOverHash)) {
-        throw new Error('companion genesis: `nextKeyHashes` must include the minting ' +
+        throw new Error('client annex genesis: `nextKeyHashes` must include the minting ' +
             "credential's own rung-0 hash (the carry-over commitment), or no " +
             'later entry could ever re-state the revealed key.');
     }
@@ -208,24 +218,24 @@ export async function createCompanionLog({ wasServerUrl, spaceId, segment, updat
     const controllerTemplate = didWebvhControllerTemplate({
         wasServerUrl,
         spaceId,
-        collectionId: segment
+        collectionId: generationId
     });
     const result = await createDID({
         address: host,
-        paths: ['space', spaceId, segment],
+        paths: ['space', spaceId, generationId],
         signer,
         updateKeys: [updateKeyPublicKeyMultibase],
         nextKeyHashes,
         didDocument: { '@context': [DID_CORE_CONTEXT], id: controllerTemplate }
     });
     if (!result.did || !result.doc) {
-        throw new Error('companion genesis: createDID returned no DID document.');
+        throw new Error('client annex genesis: createDID returned no DID document.');
     }
     return { log: result.log, did: result.did, doc: result.doc };
 }
 /**
- * Ensures the auxiliary companion Space exists: created with the typed
- * Description ({@link COMPANION_SPACE_TYPE}) under the given controller when
+ * Ensures the auxiliary annex Space exists: created with the typed
+ * Description ({@link CLIENT_ANNEX_SPACE_TYPE}) under the given controller when
  * absent, verified when present. The `type` array must ride the create -- the
  * server accepts it at creation only and treats it as immutable afterwards --
  * which is also why an existing Space at this id that is NOT typed as the
@@ -241,19 +251,19 @@ export async function createCompanionLog({ wasServerUrl, spaceId, segment, updat
  *
  * @param options {object}
  * @param options.was {WasClient}
- * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.controller {string}   the Space controller (the account
- *   did:webvh where it exists; a bootstrap did:key on a client-less signup,
+ *   did:webvh where it exists; a bootstrap did:key on a ladder-anchored signup,
  *   promoted the same way the account Space's controller is)
  * @returns {Promise<void>}
  */
-export async function ensureCompanionSpace({ was, spaceId, controller }) {
+export async function ensureClientAnnexSpace({ was, spaceId, controller }) {
     const space = was.space(spaceId);
     const current = await space.describe();
     if (current === null) {
         await space.configure({
             controller,
-            type: COMPANION_SPACE_TYPE,
+            type: CLIENT_ANNEX_SPACE_TYPE,
             force: true
         });
         return;
@@ -261,18 +271,19 @@ export async function ensureCompanionSpace({ was, spaceId, controller }) {
     if (!current.type?.includes(DELEGATED_CLIENTS_SPACE_TYPE)) {
         throw new Error(`The Space "${spaceId}" exists but is not typed as the ` +
             'delegated-clients auxiliary Space; its type is immutable, so it ' +
-            'cannot hold companion generations.');
+            'cannot hold client-annex generations.');
     }
 }
 /**
- * Mints a fresh companion generation with controller-tier signing: ensures
- * the typed auxiliary Space, mints a fresh random segment, creates the
+ * Mints a fresh annex generation with controller-tier signing: ensures
+ * the typed auxiliary Space, mints a fresh random generation id, creates the
  * generation collection, and publishes the genesis `did.jsonl` as a
  * create-if-absent -- the same conditional-publish discipline as every log
- * write, though a fresh random segment makes a create collision negligible.
+ * write, though a fresh random generation id makes a create collision
+ * negligible.
  *
  * The account document's `#DelegatedClients` service entry is deliberately
- * NOT written here: the companion log publishes first, and the caller
+ * NOT written here: the annex log publishes first, and the caller
  * re-points the account document at the returned DID afterwards. A run torn
  * between the two leaves an unpointed generation -- authorization-inert (no
  * delegation names it), collected by the standing `gen-` prefix orphan
@@ -285,27 +296,27 @@ export async function ensureCompanionSpace({ was, spaceId, controller }) {
  *
  * @param options {object}
  * @param options.was {WasClient}   the storage client, signing as an enrolled
- *   client (or the bootstrap controller on a client-less signup)
+ *   client (or the bootstrap controller on a ladder-anchored signup)
  * @param options.wasServerUrl {string}
- * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.controller {string}   the auxiliary Space's controller, used
  *   only when the Space does not exist yet
  * @param options.updateKeyPublicKeyMultibase {string}   the minting
- *   credential's companion rung-0 key
+ *   credential's annex rung-0 key
  * @param options.nextKeyHashes {string[]}   every standing credential's
  *   rung-0 hash, the minting credential's included
  * @param options.signer {Signer}   the minting credential's rung-0 signer
- * @returns {Promise<{ did: string; segment: string; log: DIDLog;
+ * @returns {Promise<{ did: string; generationId: string; log: DIDLog;
  *   doc: DIDDoc }>}
  */
-export async function mintCompanionGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
-    await ensureCompanionSpace({ was, spaceId, controller });
-    const segment = mintGenerationSegment();
-    return publishCompanionGenesis({
+export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
+    await ensureClientAnnexSpace({ was, spaceId, controller });
+    const generationId = mintGenerationId();
+    return publishClientAnnexGenesis({
         was,
         wasServerUrl,
         spaceId,
-        segment,
+        generationId,
         updateKeyPublicKeyMultibase,
         nextKeyHashes,
         signer
@@ -319,87 +330,106 @@ export async function mintCompanionGeneration({ was, wasServerUrl, spaceId, cont
  * @param options {object}
  * @param options.was {WasClient}
  * @param options.wasServerUrl {string}
- * @param options.spaceId {string}   the auxiliary companion Space's id
- * @param options.segment {string}   the freshly minted generation segment
+ * @param options.spaceId {string}   the auxiliary annex Space's id
+ * @param options.generationId {string}   the freshly minted generation id
  * @param options.updateKeyPublicKeyMultibase {string}
  * @param options.nextKeyHashes {string[]}
  * @param options.signer {Signer}
- * @returns {Promise<{ did: string; segment: string; log: DIDLog;
+ * @param [options.capability] {IZcap}   an invocation capability the
+ *   collection create and the genesis publish ride (a delegated minter)
+ * @returns {Promise<{ did: string; generationId: string; log: DIDLog;
  *   doc: DIDDoc }>}
  */
-async function publishCompanionGenesis({ was, wasServerUrl, spaceId, segment, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
+async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, capability }) {
     // The generation collection must exist before its first resource PUT; a
-    // fresh random segment means this is always a create. Plaintext on purpose:
-    // the server resolves the companion DID out of its own storage, and the
+    // fresh random generation id means this is always a create. Plaintext on
+    // purpose:
+    // the server resolves the annex DID out of its own storage, and the
     // collection is capability-gated rather than encrypted.
     await was
-        .space(spaceId)
-        .collection(segment, { encryption: 'plaintext' })
-        .configure({ name: segment, force: true });
-    const created = await createCompanionLog({
+        .space(spaceId, capability !== undefined ? { capability } : {})
+        .collection(generationId, { encryption: 'plaintext' })
+        .configure({ name: generationId, force: true });
+    const created = await createClientAnnexLog({
         wasServerUrl,
         spaceId,
-        segment,
+        generationId,
         updateKeyPublicKeyMultibase,
         nextKeyHashes,
         signer
     });
     await putLogResource({
-        store: companionLogStore({ was, spaceId, segment }),
+        store: clientAnnexLogStore({
+            was,
+            spaceId,
+            generationId,
+            ...(capability !== undefined ? { capability } : {})
+        }),
         log: created.log,
         ifNoneMatch: true
     });
-    return { ...created, segment };
+    return { ...created, generationId };
 }
 /**
- * Mints a fresh companion generation signed by a standing CREDENTIAL's
- * companion rung 0 -- the mint a ladder-seed holder runs (a credential-in-hand
- * login, or a test harness standing in for one). The segment must exist
+ * Mints a fresh annex generation signed by a standing CREDENTIAL's
+ * annex rung 0 -- the mint a ladder-seed holder runs (a credential-in-hand
+ * login, or a test harness standing in for one). The generation id must exist
  * before the update authority can: the rung-0 key derives from the ladder
- * seed AND the segment (`companionRung`), so this helper mints the segment
+ * seed AND the generation id (`clientAnnexRung`), so this helper mints the
+ * generation id
  * first, derives the rung, and states its own carry-over hash in
- * `nextKeyHashes` -- {@link mintCompanionGeneration}'s caller-supplied-key
+ * `nextKeyHashes` -- {@link mintClientAnnexGeneration}'s caller-supplied-key
  * shape cannot express that ordering. Everything else matches it: the typed
  * Space ensure, the collection create, the create-if-absent genesis publish,
  * and the pointer deliberately left to the caller.
  *
  * @param options {object}
  * @param options.was {WasClient}   the storage client, signing as an enrolled
- *   client (or the bootstrap controller on a client-less signup)
+ *   client (or the bootstrap controller on a ladder-anchored signup)
  * @param options.wasServerUrl {string}
- * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.controller {string}   the auxiliary Space's controller, used
  *   only when the Space does not exist yet
  * @param options.ladderSeed {Uint8Array}   the minting credential's ladder
  *   seed, from its unlock record
  * @param [options.extraNextKeyHashes] {string[]}   the OTHER standing
- *   credentials' rung-0 hashes for this segment, when the account has more
+ *   credentials' rung-0 hashes for this generation id, when the account has
+ *   more
  *   than one; the minting credential's own carry-over hash is always included
- * @returns {Promise<{ did: string; segment: string; log: DIDLog;
+ * @param [options.capability] {IZcap}   an invocation capability the mint
+ *   rides -- the transient-recovery continuation minting its fresh generation
+ *   through the credential's sibling delegation (the auxiliary Space's items
+ *   subtree). The typed-Space ensure is then skipped: the delegation's target
+ *   covers the collections beneath the Space, never the Space Description,
+ *   and a standing sibling delegation presupposes the auxiliary Space
+ * @returns {Promise<{ did: string; generationId: string; log: DIDLog;
  *   doc: DIDDoc }>}
  */
-export async function mintCredentialCompanionGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, extraNextKeyHashes = [] }) {
-    await ensureCompanionSpace({ was, spaceId, controller });
-    const segment = mintGenerationSegment();
-    const rung = await companionRung({ ladderSeed, segment });
-    return publishCompanionGenesis({
+export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, extraNextKeyHashes = [], capability }) {
+    if (capability === undefined) {
+        await ensureClientAnnexSpace({ was, spaceId, controller });
+    }
+    const generationId = mintGenerationId();
+    const rung = await clientAnnexRung({ ladderSeed, generationId });
+    return publishClientAnnexGenesis({
         was,
         wasServerUrl,
         spaceId,
-        segment,
+        generationId,
         updateKeyPublicKeyMultibase: rung.keyMultibase,
         nextKeyHashes: [
             await deriveNextKeyHash(rung.keyMultibase),
             ...extraNextKeyHashes
         ],
-        signer: await updateKeySigner({ seed: rung.seed })
+        signer: await updateKeySigner({ seed: rung.seed }),
+        ...(capability !== undefined ? { capability } : {})
     });
 }
 /**
  * The type IRI of the account document's delegated-clients service entry --
- * the pointer at the current companion generation's DID. Wire-level and
+ * the pointer at the current annex generation's DID. Wire-level and
  * permanent: readers (this module's {@link delegatedClientsPointer}, the
- * server's companion-chain inspector clause) dispatch on this IRI, never on
+ * server's annex-chain inspector clause) dispatch on this IRI, never on
  * the entry's fragment id, which is non-semantic by convention.
  */
 export const DELEGATED_CLIENTS_SERVICE_TYPE = 'https://w3id.org/byoe#DelegatedClients';
@@ -412,25 +442,25 @@ export const DELEGATED_CLIENTS_SERVICE_TYPE = 'https://w3id.org/byoe#DelegatedCl
 const DELEGATED_CLIENTS_SERVICE_FRAGMENT = 'delegated-clients';
 /**
  * Builds a fresh delegated-clients service entry for the account document.
- * The `serviceEndpoint` is the companion DID STRING, deliberately not a URL:
+ * The `serviceEndpoint` is the annex DID STRING, deliberately not a URL:
  * the DID is self-certifying and host-independent, and the account pointer
  * already carries the host.
  *
  * @param options {object}
  * @param options.accountDid {string}   the account did:webvh
- * @param options.companionDid {string}   the current generation's companion
+ * @param options.clientAnnexDid {string}   the current generation's annex
  *   DID
  * @returns {ServiceEndpoint}
  */
-export function delegatedClientsServiceEntry({ accountDid, companionDid }) {
+export function delegatedClientsServiceEntry({ accountDid, clientAnnexDid }) {
     return {
         id: `${accountDid}#${DELEGATED_CLIENTS_SERVICE_FRAGMENT}`,
         type: DELEGATED_CLIENTS_SERVICE_TYPE,
-        serviceEndpoint: companionDid
+        serviceEndpoint: clientAnnexDid
     };
 }
 /**
- * The companion DID the account document currently points at: the
+ * The annex DID the account document currently points at: the
  * `serviceEndpoint` of the service entry whose `type` names (or includes)
  * {@link DELEGATED_CLIENTS_SERVICE_TYPE}. Only a bare DID-string endpoint
  * counts -- the same predicate the server's inspector clause evaluates, so
@@ -450,9 +480,42 @@ export function delegatedClientsPointer({ doc }) {
     }
     return undefined;
 }
+/**
+ * The account document's `service` array with the delegated-clients pointer
+ * set to `clientAnnexDid`. An existing pointer entry is re-pointed in place,
+ * its fragment id preserved verbatim (the id is non-semantic and stable);
+ * absent one, a fresh entry is appended. Every other service entry is carried
+ * through untouched.
+ *
+ * Shared by the two writers of the pointer: the standalone
+ * {@link setDelegatedClientsPointer} entry, and the transient-recovery
+ * continuation, which folds the pointer into its own add-and-retire entry so
+ * the pointer can never lag the entry that retires the standing ladder VMs.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the current account document
+ * @param options.accountDid {string}   the account did:webvh
+ * @param options.clientAnnexDid {string}   the generation to point at
+ * @returns {ServiceEndpoint[]}
+ */
+export function servicesPointedAtClientAnnex({ doc, accountDid, clientAnnexDid }) {
+    const existing = (doc.service ?? []);
+    const isPointerEntry = (entry) => {
+        const types = Array.isArray(entry.type) ? entry.type : [entry.type];
+        return types.includes(DELEGATED_CLIENTS_SERVICE_TYPE);
+    };
+    return existing.some(isPointerEntry)
+        ? existing.map(entry => isPointerEntry(entry)
+            ? { ...entry, serviceEndpoint: clientAnnexDid }
+            : entry)
+        : [
+            ...existing,
+            delegatedClientsServiceEntry({ accountDid, clientAnnexDid })
+        ];
+}
 /**
  * The unlock-record sibling delegation's `allowedAction` set: GET beside PUT,
- * so an enrolling transient client can read the companion head it appends to.
+ * so an enrolling transient client can read the annex head it appends to.
  * Wire-level and permanent (wallet-core decision 0005): the server's
  * inspector clause admits a delegated-clients delegation with `allowedAction`
  * a subset of exactly this pair.
@@ -466,16 +529,17 @@ export const DELEGATED_CLIENTS_DELEGATION_ACTIONS = ['GET', 'PUT'];
  */
 export const DELEGATED_CLIENTS_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
 /**
- * Mints one delegated-clients (companion-Space) delegation: the pre-minted
+ * Mints one delegated-clients (annex Space) delegation: the pre-minted
  * zcap sealed into a standing credential's unlock record beside the account
- * bridge, which is what lets a transient login reach the companion log with
+ * bridge, which is what lets a transient login reach the annex log with
  * nothing but the credential. The shape is a permanent wire artifact
  * (wallet-core decision 0005):
  *
- * - `invocationTarget` is the AUXILIARY companion Space's items subtree --
+ * - `invocationTarget` is the AUXILIARY annex Space's items subtree --
  *   the Space URL with a trailing slash, built with was-client's paths
  *   helpers so the bytes match the server's target check on a sub-path
- *   deployment. Generation coverage comes from segment-bounded attenuation
+ *   deployment. Generation coverage comes from generation-id-bounded
+ *   attenuation
  *   over the flat `gen-` collection names, so no GC cycle rewrites the
  *   record or the registry.
  * - `controller` is the credential-derived signing DID (the same grantee
@@ -489,22 +553,22 @@ export const DELEGATED_CLIENTS_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
  *   enrolled client's promoted signer, or the account ladder VM)
  * @param options.wasServerUrl {string}   the auxiliary Space's storage
  *   server (the account pointer's host)
- * @param options.companionSpaceId {string}   the auxiliary companion
+ * @param options.clientAnnexSpaceId {string}   the auxiliary annex
  *   Space's id
  * @param options.controller {string}   the credential-derived signing DID
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @returns {Promise<IZcap>}
  */
-export async function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl, companionSpaceId, controller, now = Date.now() }) {
+export async function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl, clientAnnexSpaceId, controller, now = Date.now() }) {
     const spaceUrl = toUrl({
         serverUrl: wasServerUrl,
-        path: spacePath(companionSpaceId)
+        path: spacePath(clientAnnexSpaceId)
     });
     return (await zcapClient.delegate({
         capability: rootCapabilityId(spaceUrl),
         invocationTarget: toUrl({
             serverUrl: wasServerUrl,
-            path: spaceItems(companionSpaceId)
+            path: spaceItems(clientAnnexSpaceId)
         }),
         controller,
         allowedActions: [...DELEGATED_CLIENTS_DELEGATION_ACTIONS],
@@ -512,9 +576,51 @@ export async function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl,
     }));
 }
 /**
- * The auxiliary companion Space id a delegated-clients delegation targets,
+ * Builds the annex-side sibling-delegation minter the durable record re-mint
+ * orchestrator (`recovery/remintRecoveryDelegations`) takes as an injected
+ * closure -- the boundary keeping that base orchestrator free of annex
+ * imports. The returned closure reads the auxiliary annex Space id off the
+ * verified document's delegated-clients service entry (the annex DID string
+ * embeds it) and mints a fresh {@link mintDelegatedClientsDelegation} to the
+ * named controller; it resolves `undefined` while the document points at no
+ * generation, which the orchestrator reads as "carry the old sealed member
+ * verbatim".
+ *
+ * @param options {object}
+ * @param options.doc {object}   the locally verified account document
+ * @param options.zcapClient {ZcapClient}   the acting client's promoted
+ *   signer, which mints the fresh delegations
+ * @param options.wasServerUrl {string}   the auxiliary Space's storage
+ *   server (the account pointer's host)
+ * @returns {Function}   `({ controller }) => Promise<IZcap | undefined>`
+ */
+export function delegatedClientsDelegationMinter({ doc, zcapClient, wasServerUrl }) {
+    return async ({ controller }) => {
+        const clientAnnexDid = delegatedClientsPointer({
+            doc: doc
+        });
+        if (!clientAnnexDid) {
+            return undefined;
+        }
+        let clientAnnexSpaceId;
+        try {
+            clientAnnexSpaceId = clientAnnexDidParts({ did: clientAnnexDid }).spaceId;
+        }
+        catch {
+            return undefined;
+        }
+        return mintDelegatedClientsDelegation({
+            zcapClient,
+            wasServerUrl,
+            clientAnnexSpaceId,
+            controller
+        });
+    };
+}
+/**
+ * The auxiliary annex Space id a delegated-clients delegation targets,
  * read out of its `invocationTarget` (the items-subtree URL,
- * `.../space/<companionSpaceId>/`). The id has no other home -- a transient
+ * `.../space/<clientAnnexSpaceId>/`). The id has no other home -- a transient
  * login learns the Space from the delegation it unwraps, and a refresh pass
  * that holds the old delegation rebuilds the target from it -- so this parse
  * is the one reader. Returns `undefined` on anything that is not an
@@ -548,7 +654,7 @@ export function delegatedClientsDelegationSpaceId({ delegation }) {
     return spaceId ? decodeURIComponent(spaceId) : undefined;
 }
 /**
- * The type IRI of the companion document's generation-delegation service
+ * The type IRI of the annex document's generation-delegation service
  * entry -- the generation's standing Space-scoped zcap, embedded where an
  * enrolling transient client can reach it before it holds any other
  * authority. Wire-level and permanent: readers (this module's
@@ -601,8 +707,8 @@ export const GENERATION_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
  *   bytes match the server's target check on a sub-path deployment. The
  *   bare Space URL sits outside the capability bytes (see
  *   {@link GENERATION_DELEGATION_ACTIONS} for what that excludes).
- * - `controller` is the bare companion DID string. Transient keys invoke as
- *   `<companionDid>#<vm>`, and the server's inspector clause compares this
+ * - `controller` is the bare annex DID string. Transient keys invoke as
+ *   `<clientAnnexDid>#<vm>`, and the server's inspector clause compares this
  *   string against the account document's delegated-clients pointer.
  * - The chain is rooted directly in the account Space's root zcap, so an
  *   App Connect grant delegated under it forms the depth-3 chain
@@ -618,12 +724,12 @@ export const GENERATION_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
  *   or a durable client's promoted signer)
  * @param options.wasServerUrl {string}   the ACCOUNT Space's storage server
  * @param options.spaceId {string}   the ACCOUNT Space's id
- * @param options.companionDid {string}   the generation's companion DID
+ * @param options.clientAnnexDid {string}   the generation's annex DID
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @returns {Promise<IZcap>}
  */
-export async function mintGenerationDelegation({ zcapClient, wasServerUrl, spaceId, companionDid, now = Date.now() }) {
-    companionDidParts({ did: companionDid });
+export async function mintGenerationDelegation({ zcapClient, wasServerUrl, spaceId, clientAnnexDid, now = Date.now() }) {
+    clientAnnexDidParts({ did: clientAnnexDid });
     const spaceUrl = toUrl({ serverUrl: wasServerUrl, path: spacePath(spaceId) });
     return (await zcapClient.delegate({
         capability: rootCapabilityId(spaceUrl),
@@ -631,7 +737,7 @@ export async function mintGenerationDelegation({ zcapClient, wasServerUrl, space
             serverUrl: wasServerUrl,
             path: spaceItems(spaceId)
         }),
-        controller: companionDid,
+        controller: clientAnnexDid,
         allowedActions: [...GENERATION_DELEGATION_ACTIONS],
         expires: new Date(now + GENERATION_DELEGATION_TTL_MS)
     }));
@@ -661,33 +767,33 @@ export function clampGrantExpires({ ttlMs, delegation, now = Date.now() }) {
     return new Date(Math.min(now + ttlMs, parentExpires));
 }
 /**
- * Builds a fresh generation-delegation service entry for a companion
+ * Builds a fresh generation-delegation service entry for an annex
  * document. The `serviceEndpoint` is the full delegated-zcap JSON as a
  * single map, byte-identical to what `zcapClient.delegate` produced -- the
- * companion entry proof (JCS canonicalization) then covers it byte for byte,
+ * annex entry proof (JCS canonicalization) then covers it byte for byte,
  * so host tampering with the stored delegation is client-visible.
  *
  * @param options {object}
- * @param options.companionDid {string}   the generation's companion DID
+ * @param options.clientAnnexDid {string}   the generation's annex DID
  * @param options.delegation {IZcap}   the minted generation delegation
  * @returns {ServiceEndpoint}
  */
-export function generationDelegationServiceEntry({ companionDid, delegation }) {
+export function generationDelegationServiceEntry({ clientAnnexDid, delegation }) {
     return {
-        id: `${companionDid}#${GENERATION_DELEGATION_SERVICE_FRAGMENT}`,
+        id: `${clientAnnexDid}#${GENERATION_DELEGATION_SERVICE_FRAGMENT}`,
         type: GENERATION_DELEGATION_SERVICE_TYPE,
         serviceEndpoint: delegation
     };
 }
 /**
- * The generation delegation a companion document carries: the
+ * The generation delegation an annex document carries: the
  * `serviceEndpoint` map of the service entry whose `type` names (or
  * includes) {@link GENERATION_DELEGATION_SERVICE_TYPE}. Only a map-form
  * endpoint counts (the delegation is embedded as the zcap JSON itself,
  * never as a URL or an encoded string).
  *
  * @param options {object}
- * @param options.doc {DIDDoc}   the resolved (and verified) companion
+ * @param options.doc {DIDDoc}   the resolved (and verified) annex
  *   document
  * @returns {IZcap | undefined}
  */
@@ -706,18 +812,77 @@ export function embeddedGenerationDelegation({ doc }) {
     return undefined;
 }
 /**
- * The companion document's service list with the generation delegation
+ * Every generation delegation a generation's log has ever embedded, in log
+ * order and deduplicated by zcap id -- the annex-log HISTORY WALK the
+ * last-durable-client forget revokes from (decision 0004's 2026-08-19
+ * amendment): a renewal replaces the head service entry's endpoint in place,
+ * so a superseded delegation's bytes survive only in earlier entries'
+ * re-stated full state, and a renewal inside the 30-day window can leave TWO
+ * still-unexpired ladder-signed delegations. The caller filters (signer,
+ * expiry) and revokes; this walk only recovers the bytes.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the generation's VERIFIED log
+ * @returns {IZcap[]}
+ */
+export function generationDelegationHistory({ log }) {
+    const seen = new Set();
+    const delegations = [];
+    for (const entry of log) {
+        const embedded = embeddedGenerationDelegation({
+            doc: entry.state
+        });
+        if (embedded === undefined) {
+            continue;
+        }
+        const id = embedded.id;
+        if (typeof id !== 'string' || seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        delegations.push(embedded);
+    }
+    return delegations;
+}
+/**
+ * Submits the revocation of a generation delegation, reading the server's
+ * 400 answer as success: an already-revoked chain (a resumed ceremony's
+ * blind re-POST) and an expired delegation (which no longer needs revoking)
+ * both land there, and the revocation protocol exposes no read endpoint to
+ * distinguish them beforehand. Matched on `err.name` -- error classes do not
+ * survive crossing package copies. The `revoke` seam is was-client's
+ * `WasClient#revoke`, bound by the caller.
+ *
+ * @param options {object}
+ * @param options.revoke {Function}   `(delegation) => Promise<void>` --
+ *   POSTs the revocation (`was.revoke`)
+ * @param options.delegation {IZcap}
+ * @returns {Promise<void>}
+ */
+export async function revokeTreatingAlreadyRevokedAsSuccess({ revoke, delegation }) {
+    try {
+        await revoke(delegation);
+    }
+    catch (err) {
+        if (err.name === 'ValidationError') {
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * The annex document's service list with the generation delegation
  * installed: an existing entry's endpoint is replaced in place, its fragment
  * id preserved verbatim (the id is non-semantic and stable); absent one, a
  * fresh entry is appended. Every other service entry is preserved untouched.
  *
  * @param options {object}
- * @param options.doc {DIDDoc}   the companion document as published
- * @param options.companionDid {string}
+ * @param options.doc {DIDDoc}   the annex document as published
+ * @param options.clientAnnexDid {string}
  * @param options.delegation {IZcap}
  * @returns {ServiceEndpoint[]}
  */
-function withGenerationDelegationEntry({ doc, companionDid, delegation }) {
+function withGenerationDelegationEntry({ doc, clientAnnexDid, delegation }) {
     const existing = (doc.service ?? []);
     const isDelegationEntry = (entry) => {
         const types = Array.isArray(entry.type) ? entry.type : [entry.type];
@@ -732,65 +897,66 @@ function withGenerationDelegationEntry({ doc, companionDid, delegation }) {
             : entry)
         : [
             ...existing,
-            generationDelegationServiceEntry({ companionDid, delegation })
+            generationDelegationServiceEntry({ clientAnnexDid, delegation })
         ];
 }
 /**
- * Parses the auxiliary Space id and generation segment out of a companion DID
- * string. Both are permanent substrings of every companion DID by
- * construction (`did:webvh:<scid>:<host>:...:space:<spaceId>:<segment>`), and
- * the segment is the generation-identifying half of the companion rung HKDF
+ * Parses the auxiliary Space id and generation id out of an annex DID
+ * string. Both are permanent substrings of every annex DID by
+ * construction: the generation id is the final path segment of the annex
+ * DID (`did:webvh:<scid>:<host>:...:space:<spaceId>:<generationId>`), and it
+ * is the generation-identifying half of the annex rung HKDF
  * labels, so this parse is what lets an enrollee derive its writing key from
  * the pointer alone -- no log read, no registry.
  *
  * @param options {object}
- * @param options.did {string}   a companion did:webvh string
- * @returns {{ spaceId: string, segment: string }}
+ * @param options.did {string}   an annex did:webvh string
+ * @returns {{ spaceId: string, generationId: string }}
  */
-export function companionDidParts({ did }) {
+export function clientAnnexDidParts({ did }) {
     const parts = did.split(':');
-    const segment = parts[parts.length - 1];
+    const generationId = parts[parts.length - 1];
     const spaceId = parts[parts.length - 2];
     if (parts.length < 7 ||
         parts[0] !== 'did' ||
         parts[1] !== 'webvh' ||
         parts[parts.length - 3] !== 'space' ||
-        segment === undefined ||
+        generationId === undefined ||
         spaceId === undefined ||
         spaceId.length === 0) {
-        throw new Error(`Not a companion did:webvh: "${did}".`);
+        throw new Error(`Not a client annex did:webvh: "${did}".`);
     }
-    assertGenerationSegment(segment);
-    return { spaceId, segment };
+    assertGenerationId(generationId);
+    return { spaceId, generationId };
 }
 /**
- * Thrown when the published companion log commits neither the writing
+ * Thrown when the published annex log commits neither the writing
  * credential's rung-0 key nor its hash -- the mid-generation lockout: a
- * credential bound after the generation's genesis cannot write the companion
+ * credential bound after the generation's genesis cannot write the annex
  * until an existing writer commits its rung-0 hash or the next GC swap's
  * genesis does. Typed so callers can map it to the fresh-generation path
  * where one is licensed (the transient-recovery continuation) or to honest
  * copy where none is.
  */
-export class CompanionRungUncommittedError extends Error {
+export class ClientAnnexRungUncommittedError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'CompanionRungUncommittedError';
+        this.name = 'ClientAnnexRungUncommittedError';
     }
 }
 /**
- * Reads and resolves the published companion log through the narrow seam, or
+ * Reads and resolves the published annex log through the narrow seam, or
  * throws when the generation's `did.jsonl` is missing (an unpointed or
  * deleted generation -- nothing to enroll into).
  *
  * @param options {object}
- * @param options.store {CompanionWriteStore}
+ * @param options.store {ClientAnnexWriteStore}
  * @param [options.expectedDid] {string}
  * @param [options.pinStore] {ResourceLogPinStore}
  * @param [options.logId] {string}
  * @returns {Promise<PublishedWebvhLog>}
  */
-async function readCompanionLogOrThrow({ store, expectedDid, pinStore, logId }) {
+async function readClientAnnexLogOrThrow({ store, expectedDid, pinStore, logId }) {
     // readPublishedLog only calls getIdResourceRaw, so the narrow seam is safe.
     const published = await readPublishedLog({
         idStore: store,
@@ -799,18 +965,19 @@ async function readCompanionLogOrThrow({ store, expectedDid, pinStore, logId })
         ...(logId !== undefined ? { logId } : {})
     });
     if (!published) {
-        throw new Error('companion: did.jsonl is missing; the generation was never minted or ' +
+        throw new Error('client annex: did.jsonl is missing; the generation was never minted or ' +
             'has been collected.');
     }
     return published;
 }
 /**
  * TRANSIENT ENROLLMENT: publishes one per-visit verification method into a
- * companion generation's log -- one atomic entry, signed by the writing
- * credential's static rung 0 (derived from the ladder seed and the segment;
- * see `companionRung`). The entry:
+ * annex generation's log -- one atomic entry, signed by the writing
+ * credential's static rung 0 (derived from the ladder seed and the generation
+ * id;
+ * see `clientAnnexRung`). The entry:
  *
- * - reveals the writer's rung-0 key into `updateKeys` at its first companion
+ * - reveals the writer's rung-0 key into `updateKeys` at its first annex
  *   write (later writes re-state it unchanged);
  * - re-states `nextKeyHashes` verbatim -- every standing credential's rung-0
  *   hash, the writer's own carry-over hash included -- explicitly on the
@@ -819,7 +986,7 @@ async function readCompanionLogOrThrow({ store, expectedDid, pinStore, logId })
  *   relationship arrays stated explicitly (no `authentication`, no
  *   `assertionMethod`, no `keyAgreement` twin -- the DIDAuth path signs as
  *   the bare did:key, and the controller-marker convention does not arise in
- *   the companion at all).
+ *   the annex at all).
  *
  * The transient key set carries no update key, and nothing here touches the
  * ACCOUNT log's `updateKeys` or `nextKeyHashes`. There is no two-entry
@@ -828,54 +995,54 @@ async function readCompanionLogOrThrow({ store, expectedDid, pinStore, logId })
  * published document's own state -- a VM already present is a no-op.
  *
  * A writer whose rung-0 key is neither revealed nor committed is refused
- * ({@link CompanionRungUncommittedError}): companion entries verify against
+ * ({@link ClientAnnexRungUncommittedError}): annex entries verify against
  * the log's own hash-commitment chain, so no admission rule can make an
  * uncommitted key verify mid-log.
  *
  * @param options {object}
- * @param options.store {CompanionWriteStore}   the generation's log store
+ * @param options.store {ClientAnnexWriteStore}   the generation's log store
  *   (delegated through the credential's sibling delegation, or
  *   controller-tier)
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed, from
  *   its unlock record
- * @param options.segment {string}   the generation collection's name
+ * @param options.generationId {string}   the generation collection's name
  * @param options.transientKeyMultibase {string}   the visit's in-memory
  *   Ed25519 signing key, public multibase
- * @param [options.services] {ServiceEndpoint[]}   the companion document's
+ * @param [options.services] {ServiceEndpoint[]}   the annex document's
  *   full service-entry list, replacing the published one wholesale; omitted,
  *   the prior entries are preserved verbatim (or extended by
  *   `mintGenerationDelegation` below). Supplying both is refused in favor of
  *   the explicit list
  * @param [options.mintGenerationDelegation] {Function}
- *   `({ companionDid }) => Promise<IZcap>` -- mints the generation
+ *   `({ clientAnnexDid }) => Promise<IZcap>` -- mints the generation
  *   delegation this entry installs when it publishes the generation's FIRST
  *   transient verification method (and the document carries no delegation
  *   entry yet). Never invoked otherwise: the delegation is installed with
  *   the first transient VM or by the GC ceremony's own install stage, never
  *   by genesis (a genesis-embedded signed zcap can never verify -- its
  *   `controller` embeds the SCID the genesis hash derives from)
- * @param [options.expectedDid] {string}   the companion DID the log must
+ * @param [options.expectedDid] {string}   the annex DID the log must
  *   resolve to, from the account document's pointer
  * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
  *   transient session passes an in-memory store)
  * @param [options.logId] {string}   the generation's pin-slot key, from
- *   {@link companionLogPinId}; required whenever a `pinStore` is supplied
+ *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-export async function enrollCompanionTransientClient(options) {
-    return withLogConflictRetry(() => enrollCompanionTransientClientOnce(options));
+export async function enrollClientAnnexTransientClient(options) {
+    return withLogConflictRetry(() => enrollClientAnnexTransientClientOnce(options));
 }
 /**
- * One attempt of {@link enrollCompanionTransientClient}, re-invoked by the
+ * One attempt of {@link enrollClientAnnexTransientClient}, re-invoked by the
  * conflict retry (with the same signing key -- static rung 0 has no
  * advanced-rung retry shape).
  *
- * @param options {object}   see {@link enrollCompanionTransientClient}
+ * @param options {object}   see {@link enrollClientAnnexTransientClient}
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId }) {
-    assertGenerationSegment(segment);
-    const published = await readCompanionLogOrThrow({
+async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, generationId, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId }) {
+    assertGenerationId(generationId);
+    const published = await readClientAnnexLogOrThrow({
         store,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
         ...(pinStore !== undefined ? { pinStore } : {}),
@@ -890,13 +1057,13 @@ async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment,
     if (existingMethods.some(method => method.id === vmId)) {
         return { did, doc, log: published.log };
     }
-    const rung = await companionRung({ ladderSeed, segment });
+    const rung = await clientAnnexRung({ ladderSeed, generationId });
     const rungHash = await deriveNextKeyHash(rung.keyMultibase);
     const revealed = published.updateKeys.includes(rung.keyMultibase);
     if (!revealed && !published.nextKeyHashes.includes(rungHash)) {
-        throw new CompanionRungUncommittedError("companion: the log commits neither this credential's rung-0 key nor " +
+        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither this credential's rung-0 key nor " +
             'its hash; a credential bound mid-generation cannot write the ' +
-            'companion until a writer commits its hash or the next GC swap does.');
+            'annex until a writer commits its hash or the next GC swap does.');
     }
     // A non-rotating entry re-states `updateKeys`, which the resolver checks
     // against the previous entry's commitments -- genesis enforces the
@@ -910,10 +1077,10 @@ async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment,
         mintDelegation !== undefined &&
         existingMethods.length === 0 &&
         embeddedGenerationDelegation({ doc }) === undefined) {
-        const delegation = await mintDelegation({ companionDid: did });
+        const delegation = await mintDelegation({ clientAnnexDid: did });
         services = withGenerationDelegationEntry({
             doc,
-            companionDid: did,
+            clientAnnexDid: did,
             delegation
         });
     }
@@ -947,17 +1114,17 @@ async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment,
         capabilityDelegation: relationIds(doc.capabilityDelegation),
         ...(services !== undefined ? { services } : {})
     });
-    // The log only -- a companion has no did:web projection -- conditional on
+    // The log only -- an annex has no did:web projection -- conditional on
     // the read this entry was built on.
     await putLogResource({ store, log: updated.log, ifMatch: published.etag });
     return { did: updated.did, doc: updated.doc, log: updated.log };
 }
 /**
  * Points the account document's delegated-clients service entry at a
- * companion DID -- the first install after a generation's genesis, and the GC
+ * annex DID -- the first install after a generation's genesis, and the GC
  * swap's re-point alike. One ordinary document-update entry, signed by an
- * enrolled durable client's active update key; the companion log always
- * publishes FIRST (see {@link mintCompanionGeneration}), so a tear leaves an
+ * enrolled durable client's active update key; the annex log always
+ * publishes FIRST (see {@link mintClientAnnexGeneration}), so a tear leaves an
  * unpointed, authorization-inert generation, never a dangling pointer.
  *
  * An existing delegated-clients entry is re-pointed in place, its fragment id
@@ -968,10 +1135,14 @@ async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment,
  * a no-op on the log (it still heals a lagging `did.json`).
  *
  * @param options {object}
- * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store
+ * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store; with
+ *   `logOnly`, only its log read and `did.jsonl` PUT are used, so the narrow
+ *   delegated seam satisfies it
  * @param options.updateKeys {ClientWebvhUpdateKeys}   this durable client's
- *   update-key seeds
- * @param options.companionDid {string}   the generation to point at
+ *   update-key seeds -- or the ladder-rung idiom on a ladder-anchored
+ *   account (`{ updateSeed: rung0.seed, stagedSeed: rung1.seed }`), as the
+ *   credential-anchored genesis and the transient-recovery continuation pass
+ * @param options.clientAnnexDid {string}   the generation to point at
  * @param [options.expectedDid] {string}   the account DID the log must
  *   resolve to, from the account pointer
  * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
@@ -979,6 +1150,11 @@ async function enrollCompanionTransientClientOnce({ store, ladderSeed, segment,
  * @param [options.logId] {string}   the account log's pin-slot key, from
  *   `accountLogPinId({ spaceId })`; required whenever a `pinStore` is
  *   supplied
+ * @param [options.logOnly] {boolean}   publish `did.jsonl` only, never the
+ *   `did.json` projection -- the transient-recovery continuation writing
+ *   through the record's bridge delegation, whose narrow scope covers nothing
+ *   but the log. The projection heals at the next authorized write (the log
+ *   is the source of truth)
  * @returns {Promise<{ did: string, doc: DIDDoc }>}
  */
 export async function setDelegatedClientsPointer(options) {
@@ -991,9 +1167,9 @@ export async function setDelegatedClientsPointer(options) {
  * @param options {object}   see {@link setDelegatedClientsPointer}
  * @returns {Promise<{ did: string, doc: DIDDoc }>}
  */
-async function setDelegatedClientsPointerOnce({ idStore, updateKeys, companionDid, expectedDid, pinStore, logId }) {
+async function setDelegatedClientsPointerOnce({ idStore, updateKeys, clientAnnexDid, expectedDid, pinStore, logId, logOnly = false }) {
     // Refuses a malformed target before anything is read or written.
-    companionDidParts({ did: companionDid });
+    clientAnnexDidParts({ did: clientAnnexDid });
     const published = await readPublishedLog({
         idStore,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
@@ -1001,11 +1177,13 @@ async function setDelegatedClientsPointerOnce({ idStore, updateKeys, companionDi
         ...(logId !== undefined ? { logId } : {})
     });
     if (!published) {
-        throw new Error('did:webvh: did.jsonl is missing; nothing to point at a companion.');
+        throw new Error('did:webvh: did.jsonl is missing; nothing to point at a client annex.');
     }
     const { did, doc } = published;
-    if (delegatedClientsPointer({ doc }) === companionDid) {
-        await concludeWithPublishedLog({ idStore, published });
+    if (delegatedClientsPointer({ doc }) === clientAnnexDid) {
+        if (!logOnly) {
+            await concludeWithPublishedLog({ idStore, published });
+        }
         return { did, doc };
     }
     // The entry is signed by this client's active update key; a log that does
@@ -1017,19 +1195,11 @@ async function setDelegatedClientsPointerOnce({ idStore, updateKeys, companionDi
             'delegated-clients entry.');
     }
     await assertCarryOverCommitments({ published });
-    const existing = (doc.service ?? []);
-    const isPointerEntry = (entry) => {
-        const types = Array.isArray(entry.type) ? entry.type : [entry.type];
-        return types.includes(DELEGATED_CLIENTS_SERVICE_TYPE);
-    };
-    const services = existing.some(isPointerEntry)
-        ? existing.map(entry => isPointerEntry(entry)
-            ? { ...entry, serviceEndpoint: companionDid }
-            : entry)
-        : [
-            ...existing,
-            delegatedClientsServiceEntry({ accountDid: did, companionDid })
-        ];
+    const services = servicesPointedAtClientAnnex({
+        doc,
+        accountDid: did,
+        clientAnnexDid
+    });
     const signer = await updateKeySigner({ seed: updateKeys.updateSeed });
     const updated = await updateDID({
         log: published.log,
@@ -1042,7 +1212,16 @@ async function setDelegatedClientsPointerOnce({ idStore, updateKeys, companionDi
         nextKeyHashes: published.nextKeyHashes,
         services
     });
-    await publishUpdatedLog({ idStore, updated, ifMatch: published.etag });
+    if (logOnly) {
+        await putLogResource({
+            store: idStore,
+            log: updated.log,
+            ifMatch: published.etag
+        });
+    }
+    else {
+        await publishUpdatedLog({ idStore, updated, ifMatch: published.etag });
+    }
     return { did: updated.did, doc: updated.doc };
 }
 /**
@@ -1060,76 +1239,88 @@ async function setDelegatedClientsPointerOnce({ idStore, updateKeys, companionDi
  * @param options.readAccountDocument {Function}   reads the VERIFIED account
  *   document (the caller's `verifyAccountLog` read, pins and `expectedDid`
  *   applied there); called once per round
- * @param options.storeForSegment {Function}   builds the generation's log
- *   store for a segment (the delegated store over the credential's sibling
+ * @param options.storeForGenerationId {Function}   builds the generation's log
+ *   store for a generation id (the delegated store over the credential's
+ *   sibling
  *   delegation, or a controller-tier store)
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
  * @param options.transientKeyMultibase {string}   the visit's in-memory
  *   signing key, public multibase
  * @param [options.mintGenerationDelegation] {Function}
- *   `({ companionDid }) => Promise<IZcap>` -- forwarded to the enrollment
+ *   `({ clientAnnexDid }) => Promise<IZcap>` -- forwarded to the enrollment
  *   entry, which installs the minted delegation when it publishes the
  *   generation's first transient VM (see
- *   {@link enrollCompanionTransientClient}). The closure receives whichever
- *   companion DID the round enrolls into, so a GC-race re-enroll mints for
+ *   {@link enrollClientAnnexTransientClient}). The closure receives whichever
+ *   annex DID the round enrolls into, so a GC-race re-enroll mints for
  *   the fresh generation
  * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins for the
  *   generation logs (a transient session passes an in-memory store); slot
- *   keys are derived per generation with {@link companionLogPinId}
+ *   keys are derived per generation with {@link clientAnnexLogPinId}
  * @param [options.maxRounds] {number}   how many pointer moves to chase
  *   before giving up (a GC pass is quarterly, so more than one mid-ceremony
  *   move means something else is wrong)
- * @returns {Promise<{ companionDid: string, doc: DIDDoc, log: DIDLog }>}
+ * @returns {Promise<{ clientAnnexDid: string, doc: DIDDoc, log: DIDLog }>}
  */
-export async function enrollTransientClient({ readAccountDocument, storeForSegment, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds = 3 }) {
+export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds = 3 }) {
     let accountDoc = await readAccountDocument();
     for (let round = 0; round < maxRounds; round++) {
-        const companionDid = delegatedClientsPointer({ doc: accountDoc });
-        if (companionDid === undefined) {
-            throw new Error('companion: the account document carries no delegated-clients ' +
+        const clientAnnexDid = delegatedClientsPointer({ doc: accountDoc });
+        if (clientAnnexDid === undefined) {
+            throw new Error('client annex: the account document carries no delegated-clients ' +
                 'service entry; no generation exists to enroll into.');
         }
-        const { spaceId, segment } = companionDidParts({ did: companionDid });
-        const enrolled = await enrollCompanionTransientClient({
-            store: storeForSegment(segment),
+        const { spaceId, generationId } = clientAnnexDidParts({
+            did: clientAnnexDid
+        });
+        const enrolled = await enrollClientAnnexTransientClient({
+            store: storeForGenerationId(generationId),
             ladderSeed,
-            segment,
+            generationId,
             transientKeyMultibase,
-            expectedDid: companionDid,
+            expectedDid: clientAnnexDid,
             ...(mintDelegation !== undefined
                 ? { mintGenerationDelegation: mintDelegation }
                 : {}),
             ...(pinStore !== undefined
-                ? { pinStore, logId: companionLogPinId({ spaceId, segment }) }
+                ? { pinStore, logId: clientAnnexLogPinId({ spaceId, generationId }) }
                 : {})
         });
         // The GC-race re-read: an unchanged pointer means the enrollment stands
         // in the pointed generation; a moved one means a concurrent GC abandoned
         // it, and the next round enrolls into the fresh generation.
         accountDoc = await readAccountDocument();
-        if (delegatedClientsPointer({ doc: accountDoc }) === companionDid) {
-            return { companionDid, doc: enrolled.doc, log: enrolled.log };
+        if (delegatedClientsPointer({ doc: accountDoc }) === clientAnnexDid) {
+            return { clientAnnexDid, doc: enrolled.doc, log: enrolled.log };
         }
     }
-    throw new Error('companion: the delegated-clients pointer kept moving across ' +
+    throw new Error('client annex: the delegated-clients pointer kept moving across ' +
         `${String(maxRounds)} enrollment rounds; giving up.`);
 }
 /**
  * RENEW PRECEDES MINT: the blocking pre-mint stage a transient App Connect
- * approval runs before delegating any grant. Reads the companion document
+ * approval runs before delegating any grant. Reads the annex document
  * and hands back its embedded generation delegation -- renewing it first
  * when it is expired or inside the 30-day renewal window ({@link
  * zcapExpiring}): a fresh delegation is minted through the caller's closure
  * (ladder-signed -- the renewal must not depend on the very delegation it
  * replaces; published through the store, which in a transient session is
  * the credential's sibling delegation, so even a hard-expired delegation is
- * recoverable), and one companion entry replaces the service entry's
+ * recoverable), and one annex entry replaces the service entry's
  * endpoint in place, signed by the writing credential's static rung 0.
  *
- * A companion document carrying no delegation entry at all installs one the
+ * An annex document carrying no delegation entry at all installs one the
  * same way (the GC ceremony's own install stage and the first-VM install
  * make this rare; a heal, not a policy).
  *
+ * Beside the expiry axis, an `accountDoc` adds the SIGNER-DEATH axis: a
+ * standing delegation whose proof key is no longer in the supplied verified
+ * account document has rotted under the current-key-set rule (the durable
+ * client that minted it was revoked, or the ladder VM that signed it left
+ * with the first durable self-enrollment) and is replaced the same way. No
+ * revocation POST accompanies the replacement: a rotted chain no longer
+ * verifies at the revocation endpoint, and the expiry-renewal path never
+ * revoked either.
+ *
  * Failure is the caller's failure: a renewal that cannot complete throws,
  * and the App Connect approval fails with the standard retryable-ceremony
  * posture -- deliberately no clamp-on-failure fallback, which would deliver
@@ -1139,21 +1330,28 @@ export async function enrollTransientClient({ readAccountDocument, storeForSegme
  * 30 or more days remaining ({@link clampGrantExpires}).
  *
  * @param options {object}
- * @param options.store {CompanionWriteStore}   the generation's log store
+ * @param options.store {ClientAnnexWriteStore}   the generation's log store
  *   (delegated through the credential's sibling delegation, or
  *   controller-tier)
  * @param options.ladderSeed {Uint8Array}   the credential's ladder seed, from
  *   its unlock record
- * @param options.segment {string}   the generation collection's name
+ * @param options.generationId {string}   the generation collection's name
  * @param options.mintGenerationDelegation {Function}
- *   `({ companionDid }) => Promise<IZcap>` -- mints the replacement
+ *   `({ clientAnnexDid }) => Promise<IZcap>` -- mints the replacement
  *   delegation (ladder-signed in a transient session)
- * @param [options.expectedDid] {string}   the companion DID the log must
+ * @param [options.expectedDid] {string}   the annex DID the log must
  *   resolve to, from the account document's pointer
  * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
  *   transient session passes an in-memory store)
  * @param [options.logId] {string}   the generation's pin-slot key, from
- *   {@link companionLogPinId}; required whenever a `pinStore` is supplied
+ *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ * @param [options.accountDoc] {PublishedKeyDocument}   the locally VERIFIED
+ *   account document; supplied, a standing delegation whose proof key it no
+ *   longer lists is replaced (the signer-death axis above)
+ * @param [options.force] {boolean}   replace the embedded delegation
+ *   unconditionally, however healthy it looks -- the last-durable-client
+ *   forget's replacement stage, where the standing delegation has just been
+ *   revoked server-side (a state no client-side predicate can read)
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @returns {Promise<{ delegation: IZcap, renewed: boolean }>}
  */
@@ -1168,9 +1366,9 @@ export async function ensureGenerationDelegationCurrent(options) {
  * @param options {object}   see {@link ensureGenerationDelegationCurrent}
  * @returns {Promise<{ delegation: IZcap, renewed: boolean }>}
  */
-async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, segment, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, now }) {
-    assertGenerationSegment(segment);
-    const published = await readCompanionLogOrThrow({
+async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, generationId, mintGenerationDelegation: mintDelegation, expectedDid, pinStore, logId, accountDoc, force = false, now }) {
+    assertGenerationId(generationId);
+    const published = await readClientAnnexLogOrThrow({
         store,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
         ...(pinStore !== undefined ? { pinStore } : {}),
@@ -1178,7 +1376,17 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, segmen
     });
     const { did, doc } = published;
     const standing = embeddedGenerationDelegation({ doc });
-    if (standing !== undefined &&
+    const signerRotted = standing !== undefined &&
+        accountDoc !== undefined &&
+        !delegationKeyInDocument({
+            doc: accountDoc,
+            ...(delegationProofKeyId(standing) !== undefined
+                ? { delegationKeyId: delegationProofKeyId(standing) }
+                : {})
+        });
+    if (!force &&
+        standing !== undefined &&
+        !signerRotted &&
         !zcapExpiring({
             ...(standing.expires !== undefined
                 ? { expires: standing.expires }
@@ -1189,22 +1397,22 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, segmen
     }
     // The rung refusal precedes the mint: nothing is delegated for a writer
     // who cannot publish the entry that would carry it.
-    const rung = await companionRung({ ladderSeed, segment });
+    const rung = await clientAnnexRung({ ladderSeed, generationId });
     const rungHash = await deriveNextKeyHash(rung.keyMultibase);
     const revealed = published.updateKeys.includes(rung.keyMultibase);
     if (!revealed && !published.nextKeyHashes.includes(rungHash)) {
-        throw new CompanionRungUncommittedError("companion: the log commits neither this credential's rung-0 key nor " +
+        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither this credential's rung-0 key nor " +
             'its hash; a credential bound mid-generation cannot renew the ' +
             'generation delegation until a writer commits its hash or the next ' +
             'GC swap does.');
     }
     await assertCarryOverCommitments({ published });
-    const fresh = await mintDelegation({ companionDid: did });
+    const fresh = await mintDelegation({ clientAnnexDid: did });
     const signer = await updateKeySigner({ seed: rung.seed });
     const updated = await updateDID({
         log: published.log,
         signer,
-        // The writer's rung-0 key reveals at its first companion write, exactly
+        // The writer's rung-0 key reveals at its first annex write, exactly
         // as the enrollment entry does; `nextKeyHashes` is re-stated verbatim,
         // never inherited. Verification methods, relationship arrays, and every
         // other service entry ride the library's prior-state clone untouched.
@@ -1212,11 +1420,196 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, segmen
         nextKeyHashes: [...published.nextKeyHashes],
         services: withGenerationDelegationEntry({
             doc,
-            companionDid: did,
+            clientAnnexDid: did,
             delegation: fresh
         })
     });
     await putLogResource({ store, log: updated.log, ifMatch: published.etag });
     return { delegation: fresh, renewed: true };
 }
-//# sourceMappingURL=companion.js.map
+/**
+ * THE CLIENT-ANNEX RUNG STRIKE: drops a retired credential's annex posture
+ * from a generation's log -- its revealed rung-0 key out of `updateKeys` and
+ * its standing rung-0 hash out of `nextKeyHashes` -- in one atomic entry
+ * signed by ANOTHER credential's committed rung 0 (an annex entry cannot
+ * remove its own signing key: the entry verifies against its own re-stated
+ * `updateKeys`). The credential-rotation ceremony's annex reach.
+ *
+ * A log committing neither the retired rung's key nor its hash is already
+ * clean and the strike no-ops (`struck: false`) -- the resumable shape, and
+ * the common one: a credential that never minted or wrote this generation
+ * has no posture in it. An acting rung the log does not commit (after the
+ * retired members are excluded -- so the retired credential can never sign
+ * its own strike) is refused with {@link ClientAnnexRungUncommittedError},
+ * which the caller maps to the generation-swap fallback: a fresh generation
+ * minted from a surviving credential's seed retires the rung with the whole
+ * generation.
+ *
+ * @param options {object}
+ * @param options.store {ClientAnnexWriteStore}   the pointed generation's log
+ *   store (controller-tier, or delegated through a sibling delegation)
+ * @param options.retiredLadderSeed {Uint8Array}   the RETIRED credential's
+ *   ladder seed (its rung is derived per generation, so the seed is the only
+ *   way to name what to strike)
+ * @param options.actingLadderSeed {Uint8Array}   a surviving credential's
+ *   ladder seed, whose committed rung 0 signs the strike entry
+ * @param options.generationId {string}   the generation collection's name
+ * @param [options.expectedDid] {string}   the annex DID the log must
+ *   resolve to, from the account document's pointer
+ * @param [options.pinStore] {ResourceLogPinStore}
+ * @param [options.logId] {string}   the generation's pin-slot key, from
+ *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ * @returns {Promise<{ struck: boolean }>}
+ */
+export async function retireClientAnnexRung(options) {
+    return withLogConflictRetry(() => retireClientAnnexRungOnce(options));
+}
+/**
+ * One attempt of {@link retireClientAnnexRung}, re-invoked by the conflict
+ * retry (with the same signing key -- static rung 0 has no advanced-rung
+ * retry shape).
+ *
+ * @param options {object}   see {@link retireClientAnnexRung}
+ * @returns {Promise<{ struck: boolean }>}
+ */
+async function retireClientAnnexRungOnce({ store, retiredLadderSeed, actingLadderSeed, generationId, expectedDid, pinStore, logId }) {
+    assertGenerationId(generationId);
+    const published = await readClientAnnexLogOrThrow({
+        store,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore !== undefined ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {})
+    });
+    const retired = await clientAnnexRung({
+        ladderSeed: retiredLadderSeed,
+        generationId
+    });
+    const retiredHash = await deriveNextKeyHash(retired.keyMultibase);
+    const remainingKeys = published.updateKeys.filter(key => key !== retired.keyMultibase);
+    const remainingHashes = published.nextKeyHashes.filter(hash => hash !== retiredHash);
+    if (remainingKeys.length === published.updateKeys.length &&
+        remainingHashes.length === published.nextKeyHashes.length) {
+        // Already clean: the retired credential holds no posture in this
+        // generation (never committed, or a completed earlier strike).
+        return { struck: false };
+    }
+    // The acting rung must be committed AFTER the retired members are
+    // excluded, so the retired credential can never sign its own strike.
+    const acting = await clientAnnexRung({
+        ladderSeed: actingLadderSeed,
+        generationId
+    });
+    const actingHash = await deriveNextKeyHash(acting.keyMultibase);
+    const revealed = remainingKeys.includes(acting.keyMultibase);
+    if (!revealed && !remainingHashes.includes(actingHash)) {
+        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither the acting credential's rung-0 " +
+            'key nor its hash (or it is the retired rung itself); the strike ' +
+            'needs a distinct committed writer -- swap the generation instead.');
+    }
+    await assertCarryOverCommitments({ published });
+    const signer = await updateKeySigner({ seed: acting.seed });
+    const updated = await updateDID({
+        log: published.log,
+        signer,
+        // The acting rung reveals at its first annex write, exactly as the
+        // enrollment entry does; the retired rung's key and hash are dropped by
+        // explicit re-statement (never parameter inheritance). Verification
+        // methods, relationship arrays, and the service entries ride the
+        // library's prior-state clone untouched.
+        updateKeys: [...new Set([...remainingKeys, acting.keyMultibase])],
+        nextKeyHashes: [...remainingHashes]
+    });
+    await putLogResource({ store, log: updated.log, ifMatch: published.etag });
+    return { struck: true };
+}
+/**
+ * THE CLIENT-ANNEX RUNG COMMIT: adds a freshly bound credential's rung-0
+ * hash to a generation's `nextKeyHashes` -- one atomic hash-restating entry
+ * signed by an already-committed credential's rung 0. The bind ceremonies'
+ * annex reach (passkey add, passphrase change): a bind runs from a logged-in
+ * session whose own login credential's rung 0 is committed, so committing the
+ * new credential's hash here is what keeps it out of the mid-generation
+ * lockout ({@link ClientAnnexRungUncommittedError} at its first transient
+ * login, otherwise standing until the next GC swap's genesis).
+ *
+ * A log already committing the bound rung's hash (or carrying its revealed
+ * key) is a no-op (`committed: false`) -- the resumable shape. An acting rung
+ * the log does not commit is refused with
+ * {@link ClientAnnexRungUncommittedError}: the bind ceremony maps that to an
+ * honest skip (nothing licenses it to mint a generation), and the lockout
+ * consequence stands as documented.
+ *
+ * @param options {object}
+ * @param options.store {ClientAnnexWriteStore}   the pointed generation's log
+ *   store (controller-tier, or delegated through a sibling delegation)
+ * @param options.boundLadderSeed {Uint8Array}   the freshly bound
+ *   credential's ladder seed (its rung is derived per generation, so the seed
+ *   is the only way to name what to commit)
+ * @param options.actingLadderSeed {Uint8Array}   the logged-in session's
+ *   login credential's ladder seed, whose committed rung 0 signs the entry
+ * @param options.generationId {string}   the generation collection's name
+ * @param [options.expectedDid] {string}   the annex DID the log must
+ *   resolve to, from the account document's pointer
+ * @param [options.pinStore] {ResourceLogPinStore}
+ * @param [options.logId] {string}   the generation's pin-slot key, from
+ *   {@link clientAnnexLogPinId}; required whenever a `pinStore` is supplied
+ * @returns {Promise<{ committed: boolean }>}
+ */
+export async function commitClientAnnexRung(options) {
+    return withLogConflictRetry(() => commitClientAnnexRungOnce(options));
+}
+/**
+ * One attempt of {@link commitClientAnnexRung}, re-invoked by the conflict
+ * retry (with the same signing key -- static rung 0 has no advanced-rung
+ * retry shape).
+ *
+ * @param options {object}   see {@link commitClientAnnexRung}
+ * @returns {Promise<{ committed: boolean }>}
+ */
+async function commitClientAnnexRungOnce({ store, boundLadderSeed, actingLadderSeed, generationId, expectedDid, pinStore, logId }) {
+    assertGenerationId(generationId);
+    const published = await readClientAnnexLogOrThrow({
+        store,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore !== undefined ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {})
+    });
+    const bound = await clientAnnexRung({
+        ladderSeed: boundLadderSeed,
+        generationId
+    });
+    const boundHash = await deriveNextKeyHash(bound.keyMultibase);
+    if (published.updateKeys.includes(bound.keyMultibase) ||
+        published.nextKeyHashes.includes(boundHash)) {
+        // Already committed (or even revealed): a completed earlier run, or a
+        // generation the bound credential itself minted.
+        return { committed: false };
+    }
+    const acting = await clientAnnexRung({
+        ladderSeed: actingLadderSeed,
+        generationId
+    });
+    const actingHash = await deriveNextKeyHash(acting.keyMultibase);
+    const revealed = published.updateKeys.includes(acting.keyMultibase);
+    if (!revealed && !published.nextKeyHashes.includes(actingHash)) {
+        throw new ClientAnnexRungUncommittedError("client annex: the log commits neither the acting credential's rung-0 " +
+            'key nor its hash; a commit entry needs a committed writer -- the ' +
+            'bound credential stays locked out until the next GC swap.');
+    }
+    await assertCarryOverCommitments({ published });
+    const signer = await updateKeySigner({ seed: acting.seed });
+    const updated = await updateDID({
+        log: published.log,
+        signer,
+        // The acting rung reveals at its first annex write, exactly as the
+        // enrollment entry does; the bound rung's hash is added by explicit
+        // re-statement (never parameter inheritance). Verification methods,
+        // relationship arrays, and the service entries ride the library's
+        // prior-state clone untouched.
+        updateKeys: [...new Set([...published.updateKeys, acting.keyMultibase])],
+        nextKeyHashes: [...published.nextKeyHashes, boundHash]
+    });
+    await putLogResource({ store, log: updated.log, ifMatch: published.etag });
+    return { committed: true };
+}
+//# sourceMappingURL=log.js.map