@interop/wallet-core 0.108.0 → 0.110.0

package/dist/clientAnnex/log.js

@@ -27,10 +27,13 @@
  *   portability move.
  * - The genesis document is bare -- no verification methods, no service
  *   entries, the DID core context only. Transient verification methods are
- *   published per visit by later entries, and the generation delegation's
- *   service entry is installed by the entry publishing the generation's first
- *   transient method, never by genesis (its bytes would have to name the SCID
- *   the genesis hash derives from).
+ *   published per visit by later entries. The entry that installs the
+ *   generation delegation (the swap's install stage, or the entry publishing
+ *   the generation's first transient method) also carries the generation's
+ *   replica pointers, one entry per replica server the caller restates.
+ *   Genesis carries neither: the delegation's bytes would have to name the
+ *   SCID the genesis hash derives from, and the pointers ride the same entry
+ *   so a generation with no delegation points at no replica.
  * - No `did:web` projection exists: the generation collection holds only its
  *   `did.jsonl`, capability-gated rather than world-readable.
  *
@@ -47,13 +50,16 @@
  * generation collection's name, and the annex DID string embeds it.
  */
 import { createDID, deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
-import { rootCapabilityId, spacePath, toUrl } from '@interop/was-client/paths';
+import { createMultihash, MultihashAlgorithm } from '@interop/data-integrity-core/multihash';
+import { rootCapabilityId, spaceUrlById } from '@interop/was-client/paths';
+import { sha256 } from '@noble/hashes/sha2.js';
 import { base64urlnopad } from '@scure/base';
 import { isJsonObject } from '../jsonObject.js';
+import { ID_COLLECTION } from '../space/collections.js';
 import { plaintextCollection } from '../space/plaintextCollection.js';
 import { clientAnnexRung } from './generationRung.js';
 import { ladderRung } from '../webvh/ladderDerivation.js';
-import { assertCarryOverCommitments, assertPublishedLogDid, currentLogParameters, didWebvhControllerTemplate, MULTIKEY_VM_TYPE, putLogResource, readPublishedLog, readPublishedLogOrThrow, updateKeySigner, withLogConflictRetry, withThreadedHeadOnce } from '../webvh/didWebvh.js';
+import { assertCarryOverCommitments, assertPublishedLogDid, currentLogParameters, didWebvhControllerTemplate, didWebvhLogLocation, didWebvhLogPaths, MULTIKEY_VM_TYPE, putLogResource, readPublishedLog, readPublishedLogOrThrow, updateKeySigner, withLogConflictRetry, withThreadedHeadOnce } from '../webvh/didWebvh.js';
 import { accountEntryHead, signAccountEntry } from '../webvh/accountEntry.js';
 import { relationIds } from '../resourceLog/document.js';
 import { delegationAtExpiry, delegationExpired, delegationSignerGone, STANDING_ZCAP_TTL_MS, standingZcapStale } from '../webvh/standingZcap.js';
@@ -160,7 +166,7 @@ const MULTIKEY_CONTEXT_URL = 'https://w3id.org/security/multikey/v1';
  * publishing a generation no one can ever extend.
  *
  * @param options {object}
- * @param options.wasServerUrl {string}
+ * @param options.baseServerUrl {string}
  * @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
@@ -171,7 +177,7 @@ const MULTIKEY_CONTEXT_URL = 'https://w3id.org/security/multikey/v1';
  * @returns {Promise<object>}   the one-entry log, its DID and document, and
  *   the resolver's meta for it
  */
-export async function createClientAnnexLog({ wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
+export async function createClientAnnexLog({ baseServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
     assertGenerationId(generationId);
     const carryOverHash = await deriveNextKeyHash(updateKeyPublicKeyMultibase);
     if (!nextKeyHashes.includes(carryOverHash)) {
@@ -179,15 +185,14 @@ export async function createClientAnnexLog({ wasServerUrl, spaceId, generationId
             "credential's own rung-0 hash (the carry-over commitment), or no " +
             'later entry could ever re-state the revealed key.');
     }
-    const { host } = new URL(wasServerUrl);
     const controllerTemplate = didWebvhControllerTemplate({
-        wasServerUrl,
+        baseServerUrl,
         spaceId,
         collectionId: generationId
     });
     const result = await createDID({
-        address: host,
-        paths: ['space', spaceId, generationId],
+        address: baseServerUrl,
+        paths: didWebvhLogPaths({ spaceId, collectionId: generationId }),
         signer,
         updateKeys: [updateKeyPublicKeyMultibase],
         nextKeyHashes,
@@ -295,7 +300,7 @@ function typedAnnexSpace({ spaceId, read }) {
  * @param options {object}
  * @param options.was {WasClient}   the storage client, signing as an enrolled
  *   client (or the bootstrap controller on a ladder-anchored signup)
- * @param options.wasServerUrl {string}
+ * @param options.baseServerUrl {string}
  * @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
@@ -315,7 +320,7 @@ function typedAnnexSpace({ spaceId, read }) {
  *   controller afterwards need not re-read it. Always present here, since
  *   this minter always runs the ensure.
  */
-export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore }) {
+export async function mintClientAnnexGeneration({ was, baseServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore }) {
     const spaceDescription = await ensureClientAnnexSpace({
         was,
         spaceId,
@@ -324,7 +329,7 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
     const generationId = mintGenerationId();
     const published = await publishClientAnnexGenesis({
         was,
-        wasServerUrl,
+        baseServerUrl,
         spaceId,
         generationId,
         updateKeyPublicKeyMultibase,
@@ -341,7 +346,7 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
  *
  * @param options {object}
  * @param options.was {WasClient}
- * @param options.wasServerUrl {string}
+ * @param options.baseServerUrl {string}
  * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.generationId {string}   the freshly minted generation id
  * @param options.updateKeyPublicKeyMultibase {string}
@@ -361,7 +366,7 @@ export async function mintClientAnnexGeneration({ was, wasServerUrl, spaceId, co
  *   for itself rather than degrade its compare-and-swap to an unconditional
  *   write.
  */
-async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore, capability }) {
+async function publishClientAnnexGenesis({ was, baseServerUrl, spaceId, generationId, updateKeyPublicKeyMultibase, nextKeyHashes, signer, pinStore, capability }) {
     // The generation collection must exist before its first resource PUT; a
     // fresh random generation id means this is always a create, so the truthful
     // `current: null` skips was-client's pre-merge describe of a Collection
@@ -375,7 +380,7 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
         capability
     }).configure({ current: null, name: generationId, force: true });
     const created = await createClientAnnexLog({
-        wasServerUrl,
+        baseServerUrl,
         spaceId,
         generationId,
         updateKeyPublicKeyMultibase,
@@ -413,7 +418,7 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
  * @param options {object}
  * @param options.was {WasClient}   the storage client, signing as an enrolled
  *   client (or the bootstrap controller on a ladder-anchored signup)
- * @param options.wasServerUrl {string}
+ * @param options.baseServerUrl {string}
  * @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
@@ -447,7 +452,7 @@ async function publishClientAnnexGenesis({ was, wasServerUrl, spaceId, generatio
  *   controller afterwards need not re-read it. Present exactly when the
  *   ensure ran, so absent under a supplied `capability`.
  */
-export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, pinStore, standingRungHashes = [], capability }) {
+export async function mintCredentialClientAnnexGeneration({ was, baseServerUrl, spaceId, controller, ladderSeed, pinStore, standingRungHashes = [], capability }) {
     const spaceDescription = capability === undefined
         ? await ensureClientAnnexSpace({ was, spaceId, controller })
         : undefined;
@@ -456,7 +461,7 @@ export async function mintCredentialClientAnnexGeneration({ was, wasServerUrl, s
     const ownHash = await deriveNextKeyHash(rung.keyMultibase);
     const published = await publishClientAnnexGenesis({
         was,
-        wasServerUrl,
+        baseServerUrl,
         spaceId,
         generationId,
         updateKeyPublicKeyMultibase: rung.keyMultibase,
@@ -601,9 +606,9 @@ export function delegatedClientsPointer({ doc }) {
  *
  * The account deletion ceremony is the reader: it must name each auxiliary
  * Space it is about to destroy, and the log is the only durable record of
- * the superseded ones. Each entry carries the annex DID and its host beside
- * the Space id, because an account that has migrated hosts leaves entries
- * this deployment cannot address: deleting `spaceId` on the CURRENT host
+ * the superseded ones. Each entry carries the annex DID and its base server URL beside
+ * the Space id, because an account that has migrated servers leaves entries
+ * this deployment cannot address: deleting `spaceId` on the CURRENT server
  * would address a Space that is not the one the entry names, and a 404 there
  * would otherwise read as a clean deletion. Such an entry is the caller's to
  * report as a residue.
@@ -614,12 +619,15 @@ export function delegatedClientsPointer({ doc }) {
  *
  * An entry carrying no document state, and an endpoint that does not parse
  * as a client-annex DID, are skipped rather than refused: the walk is an
- * enumeration aid, and a caller cannot act on an id it could not read.
+ * enumeration aid, and a caller cannot act on an id it could not read. An
+ * annex DID whose location cannot be read back off it is refused instead,
+ * with the location reader's own error, since a deletion that skipped it
+ * would leave that Space standing unreported.
  *
  * @param options {object}
  * @param options.log {DIDLog}   the VERIFIED account log
- * @returns {Array<{ did: string, host: string, spaceId: string }>}   the
- *   Spaces, in log order
+ * @returns {Array<{ did: string, baseServerUrl: string, spaceId: string }>}
+ *   the Spaces, in log order, each with the base server URL its DID locates
  */
 export function delegatedClientsSpaceHistory({ log }) {
     const spaces = [];
@@ -634,7 +642,8 @@ export function delegatedClientsSpaceHistory({ log }) {
         if (spaces.some(space => space.spaceId === parts.spaceId)) {
             continue;
         }
-        spaces.push({ did: pointed, host: parts.host, spaceId: parts.spaceId });
+        const { baseServerUrl } = didWebvhLogLocation({ did: pointed });
+        spaces.push({ did: pointed, baseServerUrl, spaceId: parts.spaceId });
     }
     return spaces;
 }
@@ -740,18 +749,17 @@ export const DELEGATED_CLIENTS_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
  * @param options {object}
  * @param options.zcapClient {ZcapClient}   the delegating signer (an
  *   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.baseServerUrl {string}   the server's base server URL
  * @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, clientAnnexSpaceId, controller, now = Date.now() }) {
-    const spaceUrl = toUrl({
-        baseUrl: wasServerUrl,
-        path: spacePath(clientAnnexSpaceId)
+export async function mintDelegatedClientsDelegation({ zcapClient, baseServerUrl, clientAnnexSpaceId, controller, now = Date.now() }) {
+    const spaceUrl = spaceUrlById({
+        baseServerUrl,
+        spaceId: clientAnnexSpaceId
     });
     return (await zcapClient.delegate({
         capability: rootCapabilityId(spaceUrl),
@@ -774,11 +782,10 @@ export async function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl,
  * @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)
+ * @param options.baseServerUrl {string}   the server's base server URL
  * @returns {Function}   `({ controller }) => Promise<IZcap | undefined>`
  */
-export function delegatedClientsDelegationMinter({ doc, zcapClient, wasServerUrl }) {
+export function delegatedClientsDelegationMinter({ doc, zcapClient, baseServerUrl }) {
     return async ({ controller }) => {
         const clientAnnexDid = delegatedClientsPointer({
             doc: doc
@@ -795,7 +802,7 @@ export function delegatedClientsDelegationMinter({ doc, zcapClient, wasServerUrl
         }
         return mintDelegatedClientsDelegation({
             zcapClient,
-            wasServerUrl,
+            baseServerUrl,
             clientAnnexSpaceId,
             controller
         });
@@ -937,15 +944,15 @@ export const GENERATION_DELEGATION_TTL_MS = STANDING_ZCAP_TTL_MS;
  * @param options {object}
  * @param options.zcapClient {ZcapClient}   the delegating signer (ladder VM
  *   or an enrolled client's promoted signer)
- * @param options.wasServerUrl {string}   the ACCOUNT Space's storage server
+ * @param options.baseServerUrl {string}   the ACCOUNT Space's storage server
  * @param options.spaceId {string}   the ACCOUNT Space's id
  * @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, clientAnnexDid, now = Date.now() }) {
+export async function mintGenerationDelegation({ zcapClient, baseServerUrl, spaceId, clientAnnexDid, now = Date.now() }) {
     clientAnnexDidParts({ did: clientAnnexDid });
-    const spaceUrl = toUrl({ baseUrl: wasServerUrl, path: spacePath(spaceId) });
+    const spaceUrl = spaceUrlById({ baseServerUrl, spaceId });
     return (await zcapClient.delegate({
         capability: rootCapabilityId(spaceUrl),
         // Subtree marker: pending the profile change; flip this target to `${spaceUrl}*` when it ships.
@@ -1017,6 +1024,187 @@ export function embeddedGenerationDelegation({ doc }) {
         endpoint: 'map'
     });
 }
+/**
+ * The type IRI of the annex document's replica pointer entries: one entry per
+ * replica server the account registers, each naming that server's DID. The
+ * term is the PWS companion spec's, since replication is its domain.
+ * Wire-level and permanent (app-connect-spec decision 0001): the source
+ * server gates a ladder-signed pull on it, and readers dispatch on this IRI
+ * rather than on the entry's fragment id.
+ */
+export const REPLICA_SERVER_SERVICE_TYPE = 'https://w3id.org/pws#ReplicaServer';
+/**
+ * The Space id a replica server publishes its own did:webvh log under.
+ */
+const REPLICA_SERVER_SPACE_ID = 'server';
+/**
+ * Refuses, with a `TypeError`, a replica server DID that is not a did:webvh
+ * whose path is `space:server:id` (app-connect-spec decision 0003, predicate
+ * 6: the source server checks the grantee's shape beside the pointer). A
+ * malformed value would land permanently in a hash-chained annex entry the
+ * server refuses anyway, so the wallet refuses it before minting the entry.
+ *
+ * @param options {object}
+ * @param options.serverDid {string}
+ */
+export function assertReplicaServerDid({ serverDid }) {
+    let location;
+    try {
+        location = didWebvhLogLocation({ did: serverDid });
+    }
+    catch {
+        location = undefined;
+    }
+    if (location === undefined ||
+        location.spaceId !== REPLICA_SERVER_SPACE_ID ||
+        location.collectionId !== ID_COLLECTION.id) {
+        throw new TypeError('A replica server DID is a did:webvh whose path is ' +
+            `space:${REPLICA_SERVER_SPACE_ID}:${ID_COLLECTION.id}; got ` +
+            `"${serverDid}".`);
+    }
+}
+/**
+ * The fragment id of a replica pointer entry: `replica-` followed by the
+ * SHA-256 multihash of the replica server's DID string (its UTF-8 bytes),
+ * base64url with no padding. Derived rather than random, so one server's
+ * entry has the same id on every restate. Wire-level and permanent; readers
+ * still dispatch on {@link REPLICA_SERVER_SERVICE_TYPE}.
+ *
+ * @param options {object}
+ * @param options.serverDid {string}   the replica server's DID
+ * @returns {string}   the fragment, without the `#`
+ */
+export function replicaServerServiceFragment({ serverDid }) {
+    const digest = sha256(new TextEncoder().encode(serverDid));
+    const multihash = createMultihash(digest, MultihashAlgorithm.SHA2_256);
+    return `replica-${base64urlnopad.encode(multihash)}`;
+}
+/**
+ * Builds a replica pointer entry for an annex document. The
+ * `serviceEndpoint` is the replica server's bare DID STRING, and the entry
+ * carries nothing beside it. Refuses a malformed `serverDid`
+ * ({@link assertReplicaServerDid}).
+ *
+ * @param options {object}
+ * @param options.clientAnnexDid {string}   the generation's annex DID
+ * @param options.serverDid {string}   the replica server's DID
+ * @returns {ServiceEndpoint}
+ */
+export function replicaServerServiceEntry({ clientAnnexDid, serverDid }) {
+    assertReplicaServerDid({ serverDid });
+    return {
+        id: `${clientAnnexDid}#${replicaServerServiceFragment({ serverDid })}`,
+        type: REPLICA_SERVER_SERVICE_TYPE,
+        serviceEndpoint: serverDid
+    };
+}
+/**
+ * The replica servers an annex document points at: the `serviceEndpoint` of
+ * every entry whose `type` names (or includes)
+ * {@link REPLICA_SERVER_SERVICE_TYPE}, in document order, each DID once.
+ * Only a bare DID-string endpoint counts, the same predicate the server's
+ * replica-pointer clause evaluates, so wallet and server read the same
+ * pointer set off one document.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the resolved (and verified) annex document
+ * @returns {string[]}
+ */
+export function replicaServerPointers({ doc }) {
+    return [
+        ...new Set(serviceEntriesWith({
+            doc,
+            type: REPLICA_SERVER_SERVICE_TYPE,
+            endpoint: 'string'
+        }).map(entry => entry.serviceEndpoint))
+    ];
+}
+/**
+ * Whether an annex document carries a replica pointer at `serverDid`: a
+ * replica pointer entry whose endpoint is the server's DID. The match is by
+ * endpoint alone, the one the server's replica-pointer clause makes; an
+ * entry's fragment id is a selector and names no server.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the resolved (and verified) annex document
+ * @param options.serverDid {string}   the replica server's DID
+ * @returns {boolean}
+ */
+export function replicaServerPointerStands({ doc, serverDid }) {
+    return replicaServerPointers({ doc }).includes(serverDid);
+}
+/**
+ * The replica servers of `serverDids`, each once, that an annex document
+ * carries no pointer at ({@link replicaServerPointerStands}). The set the
+ * installing entry adds, and what a caller whose install pass published
+ * nothing reads off the head that pass stood on.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}
+ * @param options.serverDids {string[]}
+ * @returns {string[]}
+ */
+export function replicaServersMissing({ doc, serverDids }) {
+    const standing = new Set(replicaServerPointers({ doc }));
+    return [...new Set(serverDids)].filter(serverDid => !standing.has(serverDid));
+}
+/**
+ * An {@link InstalledServices} hook that points the generation at
+ * `serverDids`: a replica pointer entry for each one the document does not
+ * already carry ({@link replicaServerPointerStands}). Every standing entry,
+ * replica pointers among them, is carried through untouched: the hook only
+ * adds, since dropping a pointer is the replica pass's decision, made against
+ * the connections directory.
+ *
+ * The hook refuses, before any entry is minted, a malformed server DID
+ * ({@link assertReplicaServerDid}) with a `TypeError`, standing ones
+ * included, and with an `Error` a document that already carries a service
+ * entry under the id an added pointer would take (one of another type,
+ * another endpoint, or an endpoint that is not a DID string): a second entry
+ * under one id is a document no resolver admits, and the entry standing
+ * there was not written by this hook.
+ *
+ * @param options {object}
+ * @param options.serverDids {string[]}   the replica servers to point at
+ * @returns {InstalledServices}
+ */
+export function replicaPointerInstaller({ serverDids }) {
+    return ({ doc, clientAnnexDid }) => {
+        for (const serverDid of serverDids) {
+            assertReplicaServerDid({ serverDid });
+        }
+        const added = replicaServersMissing({ doc, serverDids }).map(serverDid => replicaServerServiceEntry({ clientAnnexDid, serverDid }));
+        const taken = new Set((doc.service ?? []).map(entry => entry.id));
+        for (const entry of added) {
+            if (taken.has(entry.id)) {
+                throw new Error(`client annex: the document already carries a service entry at ` +
+                    `"${entry.id}" that is not the replica pointer at ` +
+                    `"${entry.serviceEndpoint}"; nothing was written.`);
+            }
+        }
+        return added;
+    };
+}
+/**
+ * The service list the entry installing a generation delegation publishes:
+ * the delegation entry ({@link withGenerationDelegationEntry}) followed by
+ * whatever the caller's {@link InstalledServices} hook adds. The one
+ * composition both installing writers run, so an install-time entry can
+ * never land in an entry other than the delegation's.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the annex document as published
+ * @param options.clientAnnexDid {string}
+ * @param options.delegation {IZcap}
+ * @param [options.installedServices] {InstalledServices}
+ * @returns {ServiceEndpoint[]}
+ */
+function withInstalledEntries({ doc, clientAnnexDid, delegation, installedServices }) {
+    return [
+        ...withGenerationDelegationEntry({ doc, clientAnnexDid, delegation }),
+        ...(installedServices?.({ doc, clientAnnexDid }) ?? [])
+    ];
+}
 /**
  * Every generation delegation a generation's log has ever embedded, in log
  * order and deduplicated by zcap id -- the annex-log HISTORY WALK the
@@ -1392,9 +1580,13 @@ export async function readClientAnnexLogOrAbsent({ store, expectedDid }) {
  *   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
+ *   the first transient VM or by the GC ceremony's own install stage, and
+ *   not by genesis (a genesis-embedded signed zcap can never verify -- its
  *   `controller` embeds the SCID the genesis hash derives from)
+ * @param [options.installedServices] {InstalledServices}   the service
+ *   entries the installing entry writes beside the delegation (the replica
+ *   pointers, {@link replicaPointerInstaller}). Invoked only by the entry
+ *   that installs the delegation; ignored on every other entry
  * @param [options.expectedDid] {string}   the annex DID the log must
  *   resolve to, from the account document's pointer. The read and the publish
  *   run under the store's own chain-head pin
@@ -1422,7 +1614,7 @@ export async function enrollClientAnnexTransientClient({ published: threadedHead
  * @param options {object}   see {@link enrollClientAnnexTransientClient}
  * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
  */
-async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, expectedDid, published: alreadyRead }) {
+async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, transientKeyMultibase, services, mintGenerationDelegation: mintDelegation, installedServices, expectedDid, published: alreadyRead }) {
     const published = alreadyRead !== undefined
         ? assertPublishedLogDid({
             published: alreadyRead,
@@ -1456,16 +1648,18 @@ async function enrollClientAnnexTransientClientOnce({ store, ladderSeed, transie
     // The generation delegation installs with the first transient VM (never at
     // genesis): a delegation-less document about to receive its first method
     // gets the entry minted and appended here, so a generation with no visits
-    // never carries a delegation and stays authorization-inert.
+    // never carries a delegation and stays authorization-inert. The replica
+    // pointers ride the same entry.
     if (services === undefined &&
         mintDelegation !== undefined &&
         existingMethods.length === 0 &&
         embeddedGenerationDelegation({ doc }) === undefined) {
         const delegation = await mintDelegation({ clientAnnexDid: did });
-        services = withGenerationDelegationEntry({
+        services = withInstalledEntries({
             doc,
             clientAnnexDid: did,
-            delegation
+            delegation,
+            ...(installedServices !== undefined ? { installedServices } : {})
         });
     }
     const transientMethod = {
@@ -1711,6 +1905,9 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
  *   {@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.installedServices] {InstalledServices}   forwarded to
+ *   the enrollment entry: what the installing entry writes beside the
+ *   delegation
  * @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)
@@ -1722,7 +1919,7 @@ export async function setDelegatedClientsPointerOnce({ idStore, signer, clientAn
  *   every later round does
  * @returns {Promise<{ clientAnnexDid: string, doc: DIDDoc, log: DIDLog }>}
  */
-export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, maxRounds = 3, published: threadedHead }) {
+export async function enrollTransientClient({ readAccountDocument, storeForGenerationId, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, installedServices, maxRounds = 3, published: threadedHead }) {
     let accountDoc = await readAccountDocument();
     for (let round = 0; round < maxRounds; round++) {
         const clientAnnexDid = delegatedClientsPointer({ doc: accountDoc });
@@ -1745,7 +1942,8 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
             ...(head !== undefined ? { published: head } : {}),
             ...(mintDelegation !== undefined
                 ? { mintGenerationDelegation: mintDelegation }
-                : {})
+                : {}),
+            ...(installedServices !== undefined ? { installedServices } : {})
         });
         // The GC-race re-read: an unchanged pointer means the enrollment stands
         // in the pointed generation; a moved one means a concurrent GC abandoned
@@ -1781,7 +1979,7 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * @param options {object}
  * @param options.was {WasClient}   the storage client the mint and the
  *   install write through
- * @param options.wasServerUrl {string}
+ * @param options.baseServerUrl {string}
  * @param options.spaceId {string}   the auxiliary annex Space's id
  * @param options.controller {string}   the Space's creation controller (see
  *   {@link mintCredentialClientAnnexGeneration})
@@ -1799,6 +1997,10 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  *   generation's standing set, restated in the fresh genesis (see
  *   {@link mintCredentialClientAnnexGeneration}); absent on a first
  *   generation and wherever no superseded log was readable
+ * @param [options.installedServices] {InstalledServices}   what the
+ *   install entry writes beside the delegation, the restated replica pointers
+ *   ({@link replicaPointerInstaller}); absent on a first generation and
+ *   wherever the caller holds no list
  * @param [options.beforePointerEntry] {Function}
  *   `({ minted }) => Promise<void>` -- runs after the install and before the
  *   pointer entry, with the mint's published head (its `spaceDescription`
@@ -1807,10 +2009,10 @@ export async function enrollTransientClient({ readAccountDocument, storeForGener
  * @returns {Promise<{ clientAnnexDid: string, generationDelegation: IZcap,
  *   pointed: T }>}
  */
-export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spaceId, controller, ladderSeed, mintGenerationDelegation, point, pinStore, capability, standingRungHashes, beforePointerEntry, now }) {
+export async function mintPointedClientAnnexGeneration({ was, baseServerUrl, spaceId, controller, ladderSeed, mintGenerationDelegation, point, pinStore, capability, standingRungHashes, installedServices, beforePointerEntry, now }) {
     const minted = await mintCredentialClientAnnexGeneration({
         was,
-        wasServerUrl,
+        baseServerUrl,
         spaceId,
         controller,
         ladderSeed,
@@ -1828,6 +2030,7 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
         }),
         ladderSeed,
         mintGenerationDelegation,
+        ...(installedServices !== undefined ? { installedServices } : {}),
         expectedDid: minted.did,
         ...(minted.etag !== undefined ? { published: minted } : {}),
         ...(now !== undefined ? { now } : {})
@@ -1899,6 +2102,14 @@ export async function mintPointedClientAnnexGeneration({ was, wasServerUrl, spac
  *   its own ladder VM (whose delegations it revokes server-side in the next
  *   breath, a state no client-side predicate can read) and the client its
  *   removal entry has yet to strike
+ * @param [options.installedServices] {InstalledServices}   the service
+ *   entries the installing entry writes beside the delegation, the replica
+ *   pointers ({@link replicaPointerInstaller}): a fresh generation's install
+ *   stage writes them beside the delegation, and a renewal on a live
+ *   generation adds what the document lacks and keeps every standing entry
+ *   through the prior-state clone. A pass that publishes nothing never
+ *   invokes the hook; the caller reads what the head still lacks off the
+ *   `published` it hands back ({@link replicaServersMissing})
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @param [options.published] {PublishedWebvhLog}   a head the caller already
  *   read and verified under this same pin slot, so the stage builds on it
@@ -1933,7 +2144,7 @@ export async function ensureGenerationDelegationCurrent({ published: threadedHea
  * @returns {Promise<{ delegation: IZcap, renewed: boolean,
  *   published?: PublishedWebvhLog }>}
  */
-async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, mintGenerationDelegation: mintDelegation, expectedDid, accountDoc, retiringKeyMultibases = [], now, published: alreadyRead }) {
+async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, mintGenerationDelegation: mintDelegation, expectedDid, accountDoc, retiringKeyMultibases = [], installedServices, now, published: alreadyRead }) {
     const published = alreadyRead !== undefined
         ? assertPublishedLogDid({
             published: alreadyRead,
@@ -1974,13 +2185,15 @@ async function ensureGenerationDelegationCurrentOnce({ store, ladderSeed, mintGe
         // 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.
+        // other service entry (the standing replica pointers among them) ride
+        // the library's prior-state clone untouched.
         updateKeys: [...new Set([...published.updateKeys, rung.keyMultibase])],
         nextKeyHashes: [...published.nextKeyHashes],
-        services: withGenerationDelegationEntry({
+        services: withInstalledEntries({
             doc,
             clientAnnexDid: did,
-            delegation: fresh
+            delegation: fresh,
+            ...(installedServices !== undefined ? { installedServices } : {})
         })
     });
     // The publish advances the store's chain-head pin to what it just wrote, so