@interop/wallet-core 0.49.0 → 0.50.0

package/dist/{webvh/companion.d.ts → clientAnnex/log.d.ts}

@@ -1,22 +1,23 @@
 import type { DIDDoc, DIDLog, ServiceEndpoint, Signer } from '@interop/did-method-webvh';
 import type { IZcap } from '@interop/data-integrity-core';
 import type { ZcapClient } from '@interop/ezcap';
-import type { WasClient } from '@interop/was-client';
+import type { IDelegatedZcap, WasClient } from '@interop/was-client';
 import type { ResourceLogPinStore } from '../resourceLog/pin.js';
-import type { ClientWebvhUpdateKeys, WebvhIdStore } from './didWebvh.js';
-import type { WebvhLogResourceStore } from './wasIdStore.js';
+import type { ClientWebvhUpdateKeys, WebvhIdStore } from '../webvh/didWebvh.js';
+import type { PublishedKeyDocument } from '../webvh/listClients.js';
+import type { WebvhLogResourceStore } 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 declare const COMPANION_SPACE_TYPE: string[];
+export declare const CLIENT_ANNEX_SPACE_TYPE: string[];
 /**
  * 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 generation id embeds in every companion
+ * Space's collection listing, and the generation id embeds in every annex
  * DID string ever published.
  */
 export declare const GENERATION_ID_PREFIX = "gen-";
@@ -31,31 +32,31 @@ export declare const GENERATION_ID_PREFIX = "gen-";
 export declare function mintGenerationId(): string;
 /**
  * Refuses anything that is not a well-formed generation id. Run by every
- * companion builder that takes a generation id, so a malformed one is refused
+ * 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 generationId {string}
  */
 export declare function assertGenerationId(generationId: string): void;
 /**
- * The pin-slot key for one companion generation's log -- host-free like every
+ * 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.spaceId {string}   the auxiliary annex Space's id
  * @param options.generationId {string}   the generation collection's name
  * @returns {string}
  */
-export declare function companionLogPinId({ spaceId, generationId }: {
+export declare function clientAnnexLogPinId({ spaceId, generationId }: {
     spaceId: string;
     generationId: string;
 }): string;
 /**
- * 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);
@@ -63,27 +64,31 @@ export declare function companionLogPinId({ spaceId, generationId }: {
  *
  * @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.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 declare function companionLogStore({ was, spaceId, generationId }: {
+export declare function clientAnnexLogStore({ was, spaceId, generationId, capability }: {
     was: WasClient;
     spaceId: string;
     generationId: string;
+    capability?: IZcap;
 }): WebvhLogResourceStore;
 /**
- * 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
@@ -91,16 +96,16 @@ export declare function companionLogStore({ was, spaceId, generationId }: {
  *
  * @param options {object}
  * @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.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 declare function createCompanionLog({ wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
+export declare function createClientAnnexLog({ wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
     wasServerUrl: string;
     spaceId: string;
     generationId: string;
@@ -113,8 +118,8 @@ export declare function createCompanionLog({ wasServerUrl, spaceId, generationId
     doc: DIDDoc;
 }>;
 /**
- * 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
@@ -130,19 +135,19 @@ export declare function createCompanionLog({ wasServerUrl, spaceId, generationId
  *
  * @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 declare function ensureCompanionSpace({ was, spaceId, controller }: {
+export declare function ensureClientAnnexSpace({ was, spaceId, controller }: {
     was: WasClient;
     spaceId: string;
     controller: string;
 }): Promise<void>;
 /**
- * Mints a fresh companion generation with controller-tier signing: ensures
+ * 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
@@ -150,7 +155,7 @@ export declare function ensureCompanionSpace({ was, spaceId, controller }: {
  * 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
@@ -163,20 +168,20 @@ export declare 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; generationId: string; log: DIDLog;
  *   doc: DIDDoc }>}
  */
-export declare function mintCompanionGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
+export declare function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
     was: WasClient;
     wasServerUrl: string;
     spaceId: string;
@@ -191,23 +196,23 @@ export declare function mintCompanionGeneration({ was, wasServerUrl, spaceId, co
     doc: DIDDoc;
 }>;
 /**
- * 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
+ * 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 generation id (`companionRung`), so this helper mints the
+ * 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
@@ -216,16 +221,23 @@ export declare function mintCompanionGeneration({ was, wasServerUrl, spaceId, co
  *   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
+ * @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 declare function mintCredentialCompanionGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, extraNextKeyHashes }: {
+export declare function mintCredentialClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, extraNextKeyHashes, capability }: {
     was: WasClient;
     wasServerUrl: string;
     spaceId: string;
     controller: string;
     ladderSeed: Uint8Array;
     extraNextKeyHashes?: string[];
+    capability?: IZcap;
 }): Promise<{
     did: string;
     generationId: string;
@@ -234,30 +246,30 @@ export declare function mintCredentialCompanionGeneration({ was, wasServerUrl, s
 }>;
 /**
  * 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 declare const DELEGATED_CLIENTS_SERVICE_TYPE = "https://w3id.org/byoe#DelegatedClients";
 /**
  * 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 declare function delegatedClientsServiceEntry({ accountDid, companionDid }: {
+export declare function delegatedClientsServiceEntry({ accountDid, clientAnnexDid }: {
     accountDid: string;
-    companionDid: string;
+    clientAnnexDid: string;
 }): ServiceEndpoint;
 /**
- * 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
@@ -270,9 +282,32 @@ export declare function delegatedClientsServiceEntry({ accountDid, companionDid
 export declare function delegatedClientsPointer({ doc }: {
     doc: DIDDoc;
 }): string | 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 declare function servicesPointedAtClientAnnex({ doc, accountDid, clientAnnexDid }: {
+    doc: DIDDoc;
+    accountDid: string;
+    clientAnnexDid: string;
+}): ServiceEndpoint[];
 /**
  * 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.
@@ -286,13 +321,13 @@ export declare const DELEGATED_CLIENTS_DELEGATION_ACTIONS: string[];
  */
 export declare const DELEGATED_CLIENTS_DELEGATION_TTL_MS: number;
 /**
- * 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 generation-id-bounded
@@ -310,23 +345,49 @@ export declare const DELEGATED_CLIENTS_DELEGATION_TTL_MS: number;
  *   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 declare function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl, companionSpaceId, controller, now }: {
+export declare function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl, clientAnnexSpaceId, controller, now }: {
     zcapClient: ZcapClient;
     wasServerUrl: string;
-    companionSpaceId: string;
+    clientAnnexSpaceId: string;
     controller: string;
     now?: number;
 }): Promise<IZcap>;
 /**
- * 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 declare function delegatedClientsDelegationMinter({ doc, zcapClient, wasServerUrl }: {
+    doc: object;
+    zcapClient: ZcapClient;
+    wasServerUrl: string;
+}): (options: {
+    controller: string;
+}) => Promise<IZcap | undefined>;
+/**
+ * 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
@@ -340,7 +401,7 @@ export declare function delegatedClientsDelegationSpaceId({ delegation }: {
     delegation: IZcap;
 }): string | 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
@@ -379,8 +440,8 @@ export declare const GENERATION_DELEGATION_TTL_MS: number;
  *   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
@@ -396,15 +457,15 @@ export declare const GENERATION_DELEGATION_TTL_MS: number;
  *   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 declare function mintGenerationDelegation({ zcapClient, wasServerUrl, spaceId, companionDid, now }: {
+export declare function mintGenerationDelegation({ zcapClient, wasServerUrl, spaceId, clientAnnexDid, now }: {
     zcapClient: ZcapClient;
     wasServerUrl: string;
     spaceId: string;
-    companionDid: string;
+    clientAnnexDid: string;
     now?: number;
 }): Promise<IZcap>;
 /**
@@ -429,30 +490,30 @@ export declare function clampGrantExpires({ ttlMs, delegation, now }: {
     now?: number;
 }): Date;
 /**
- * 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 declare function generationDelegationServiceEntry({ companionDid, delegation }: {
-    companionDid: string;
+export declare function generationDelegationServiceEntry({ clientAnnexDid, delegation }: {
+    clientAnnexDid: string;
     delegation: IZcap;
 }): ServiceEndpoint;
 /**
- * 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}
  */
@@ -460,53 +521,89 @@ export declare function embeddedGenerationDelegation({ doc }: {
     doc: DIDDoc;
 }): IZcap | undefined;
 /**
- * Parses the auxiliary Space id and generation id out of a companion DID
- * string. Both are permanent substrings of every companion DID by
- * construction: the generation id is the final path segment of the companion
+ * 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 declare function generationDelegationHistory({ log }: {
+    log: DIDLog;
+}): IZcap[];
+/**
+ * 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 declare function revokeTreatingAlreadyRevokedAsSuccess({ revoke, delegation }: {
+    revoke: (delegation: IDelegatedZcap) => Promise<void>;
+    delegation: IZcap;
+}): Promise<void>;
+/**
+ * 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 companion rung HKDF
+ * 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
+ * @param options.did {string}   an annex did:webvh string
  * @returns {{ spaceId: string, generationId: string }}
  */
-export declare function companionDidParts({ did }: {
+export declare function clientAnnexDidParts({ did }: {
     did: string;
 }): {
     spaceId: string;
     generationId: string;
 };
 /**
- * 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 declare class CompanionRungUncommittedError extends Error {
+export declare class ClientAnnexRungUncommittedError extends Error {
     constructor(message: string);
 }
 /**
- * The narrow store seam a companion entry is read and published through: the
- * log read and the conditional `did.jsonl` PUT, nothing else (a companion has
+ * The narrow store seam an annex entry is read and published through: the
+ * log read and the conditional `did.jsonl` PUT, nothing else (an annex has
  * no `did.json` projection and no key map). Satisfied by
- * {@link companionLogStore} (controller-tier signing) and by the delegated
+ * {@link clientAnnexLogStore} (controller-tier signing) and by the delegated
  * store a transient session writes through (`delegatedWebvhLogStore`,
  * invoking the credential's sibling delegation).
  */
-export type CompanionWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putIdResource'>;
+export type ClientAnnexWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putIdResource'>;
 /**
  * TRANSIENT ENROLLMENT: publishes one per-visit verification method into a
- * companion generation's log -- one atomic entry, signed by the writing
+ * 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 `companionRung`). The entry:
+ * 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
@@ -515,7 +612,7 @@ export type CompanionWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putId
  *   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
@@ -524,12 +621,12 @@ export type CompanionWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putId
  * 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
@@ -537,35 +634,35 @@ export type CompanionWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putId
  * @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 declare function enrollCompanionTransientClient(options: {
-    store: CompanionWriteStore;
+export declare function enrollClientAnnexTransientClient(options: {
+    store: ClientAnnexWriteStore;
     ladderSeed: Uint8Array;
     generationId: string;
     transientKeyMultibase: string;
     services?: ServiceEndpoint[];
     mintGenerationDelegation?: (options: {
-        companionDid: string;
+        clientAnnexDid: string;
     }) => Promise<IZcap>;
     expectedDid?: string;
     pinStore?: ResourceLogPinStore;
@@ -577,10 +674,10 @@ export declare function enrollCompanionTransientClient(options: {
 }>;
 /**
  * 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
@@ -591,10 +688,14 @@ export declare function enrollCompanionTransientClient(options: {
  * 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
@@ -602,15 +703,21 @@ export declare function enrollCompanionTransientClient(options: {
  * @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 declare function setDelegatedClientsPointer(options: {
     idStore: WebvhIdStore;
     updateKeys: ClientWebvhUpdateKeys;
-    companionDid: string;
+    clientAnnexDid: string;
     expectedDid?: string;
     pinStore?: ResourceLogPinStore;
     logId?: string;
+    logOnly?: boolean;
 }): Promise<{
     did: string;
     doc: DIDDoc;
@@ -638,51 +745,60 @@ export declare function setDelegatedClientsPointer(options: {
  * @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 declare function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds }: {
     readAccountDocument: () => Promise<DIDDoc>;
-    storeForGenerationId: (generationId: string) => CompanionWriteStore;
+    storeForGenerationId: (generationId: string) => ClientAnnexWriteStore;
     ladderSeed: Uint8Array;
     transientKeyMultibase: string;
     mintGenerationDelegation?: (options: {
-        companionDid: string;
+        clientAnnexDid: string;
     }) => Promise<IZcap>;
     pinStore?: ResourceLogPinStore;
     maxRounds?: number;
 }): Promise<{
-    companionDid: string;
+    clientAnnexDid: string;
     doc: DIDDoc;
     log: DIDLog;
 }>;
 /**
  * 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
@@ -692,37 +808,135 @@ export declare function enrollTransientClient({ readAccountDocument, storeForGen
  * 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.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 }>}
  */
 export declare function ensureGenerationDelegationCurrent(options: {
-    store: CompanionWriteStore;
+    store: ClientAnnexWriteStore;
     ladderSeed: Uint8Array;
     generationId: string;
     mintGenerationDelegation: (options: {
-        companionDid: string;
+        clientAnnexDid: string;
     }) => Promise<IZcap>;
     expectedDid?: string;
     pinStore?: ResourceLogPinStore;
     logId?: string;
+    accountDoc?: PublishedKeyDocument;
+    force?: boolean;
     now?: number;
 }): Promise<{
     delegation: IZcap;
     renewed: boolean;
 }>;
-//# sourceMappingURL=companion.d.ts.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 declare function retireClientAnnexRung(options: {
+    store: ClientAnnexWriteStore;
+    retiredLadderSeed: Uint8Array;
+    actingLadderSeed: Uint8Array;
+    generationId: string;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+    logId?: string;
+}): Promise<{
+    struck: boolean;
+}>;
+/**
+ * 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 declare function commitClientAnnexRung(options: {
+    store: ClientAnnexWriteStore;
+    boundLadderSeed: Uint8Array;
+    actingLadderSeed: Uint8Array;
+    generationId: string;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+    logId?: string;
+}): Promise<{
+    committed: boolean;
+}>;
+//# sourceMappingURL=log.d.ts.map