@interop/was-client 0.60.0 → 0.62.0

package/README.md

@@ -13,6 +13,7 @@
 - [Usage](#usage)
   - [Creating a client (signer + zcapClient)](#creating-a-client-signer--zcapclient)
     - [Deriving a client from a secret or seed (`./identity`)](#deriving-a-client-from-a-secret-or-seed-identity)
+  - [Service discovery](#service-discovery)
   - [The handle model](#the-handle-model)
   - [Spaces](#spaces)
   - [Collections](#collections)
@@ -187,6 +188,50 @@ accepted. A server that verifies both it and the older `Ed25519Signature2020`
 accepts chains whose links mix the two, which is what a fleet upgrading at its
 own pace produces.
 
+### Service discovery
+
+Before its first signed request, the client reads the server's service
+description. It sends an unsigned `HEAD` to `serverUrl` and follows the
+`Link: <...>; rel="service"` header on the response, whatever its status. Then
+it reads the linked document with an unsigned `GET`. The spec fixes no path for
+the document, so the client assumes none.
+
+From the document the client selects the WAS specification version it speaks.
+This client speaks only v0.5. It ignores `specs` keys other than
+`https://w3id.org/pws` and entries without a `version`. If no entry names v0.5,
+or the document is malformed, every signed request rejects with
+`IncompatibleServerError` before anything is signed. A server whose responses
+carry no `service` link predates v0.5 and is refused the same way. The client
+does not fall back to the v0.4 layout.
+
+Discovery runs once per client and is shared by every handle. A failure is not
+memoized, so the next request retries. Unsigned public reads (`publicRead`,
+`publicListCollection`, ...) take absolute URLs that may point at another
+server, and do not wait on discovery.
+
+`was.service()` returns what discovery found:
+
+```ts
+const info = await was.service()
+info.version // '0.5'
+info.entry // the chosen `PwsVersionEntry`
+info.description // the whole `ServiceDescription`
+info.spacesUrl // the Spaces Repository URL, or undefined
+info.features // e.g. ['listing', 'collection-management', ...]
+info.hasFeature('quotas') // false when the token is absent
+
+// Discover again, e.g. before relying on an affordance a host may have dropped.
+await was.service({ refresh: true })
+```
+
+`features` is an open token list. A token this client does not know is carried
+along and otherwise ignored, and an absent token means unsupported. The client
+gates no behavior on the document's `instance` member.
+
+A caller that already holds the document (from a cache, say) can pass it as the
+`serviceDescription` constructor option. The client then selects a version from
+that copy without fetching, and `service({ refresh: true })` discovers afresh.
+
 ### The handle model
 
 The client exposes the WAS containment model
@@ -220,22 +265,25 @@ one item" footgun. The next sections cover each level in turn.
 
 A Space is the top-level container, created from the spaces repository. The
 server requires a `name`; `controller` defaults to the client's own DID, and the
-server generates the id unless you pass one.
+server generates the id unless you pass one. `createSpace()` and `listSpaces()`
+address the Spaces Repository URL the service description names (see
+[Service discovery](#service-discovery)). Against a server whose description has
+no `spaces` URL, they throw `NotSupportedError` without sending anything.
 
 ```ts
-const space = await was.createSpace({ name: 'Home' }) // POST /spaces/
+const space = await was.createSpace({ name: 'Home' }) // POST {spacesUrl}
 
 // Lazy handle to an existing space by id -- no I/O until a verb runs.
 const same = was.space(space.id)
 
-// Read the Space Description (null if missing or not visible to you).
+// Read the Space Metadata object (null if missing or not visible to you).
 const desc = await space.describe() // { id, type: ['Space'], name, controller } | null
 
-// Upsert: merges the given fields over the current description.
+// Upsert: merges the given fields over the current Metadata object.
 await space.configure({ name: 'Home (renamed)' })
 
-// Lost-update-safe writes: read the description with its ETag, then write
-// it under `ifMatch` (412 `PreconditionFailedError` if it changed), or
+// Lost-update-safe writes: read the Metadata object with its ETag, then
+// write it under `ifMatch` (412 `PreconditionFailedError` if it changed), or
 // create-if-absent under `ifNoneMatch` (412 if the Space already exists).
 // Nothing is read or merged on the client, so `controller` is required.
 const read = await space.describeWithEtag() // { description, etag? } | null
@@ -248,7 +296,7 @@ await was
   .replaceDescription(
     { name: 'Fresh', controller: 'did:key:z6Mk...' },
     { ifNoneMatch: true }
-  ) // { description, etag? }: a create echoes the description
+  ) // { description, etag? }: a create echoes the Metadata object
 
 await space.delete() // idempotent
 
@@ -286,10 +334,10 @@ const collection = await space.createCollection({
 // Lazy handle to an existing collection by id.
 const same = space.collection(collection.id)
 
-// Read the Collection Description (null if missing or not visible).
+// Read the Collection Metadata object (null if missing or not visible).
 const desc = await collection.describe() // { id, type: ['Collection'], name } | null
 
-// Update (upsert; merges over the current description).
+// Update (upsert; merges over the current Metadata object).
 await collection.configure({ name: 'Credentials' })
 
 // List the collections in a space.
@@ -314,17 +362,16 @@ await collection.delete() // deletes the whole collection; idempotent
 To delete a single resource instead of the whole collection, use
 `collection.resource(id).delete()`.
 
-The Description's `name` is server-visible plaintext. An encrypted collection
-leaves it unpopulated by convention and carries its name and tags on the
-[Collection metadata](#collection-metadata) surface instead, where they are
-encrypted.
+The Collection Metadata object's top-level `name` is server-visible plaintext.
+An encrypted collection leaves it unpopulated by convention and carries its name
+and tags on the same object's [`custom`](#collection-metadata) member instead,
+where they are encrypted.
 
 An application that provisions a collection can record who it was provisioned
 for, with the optional `generator` (the application's DID) and `generatorOrigin`
-(the Web origin that DID was bound to) description fields. Both are accepted at
-create time and stay writable afterwards, so an existing collection can be
-backfilled; they are controller assertions the server persists but does not
-verify.
+(the Web origin that DID was bound to) fields. Both are accepted at create time
+and stay writable afterwards, so an existing collection can be backfilled; they
+are controller assertions the server persists but does not verify.
 
 ```ts
 await space.createCollection({
@@ -544,10 +591,14 @@ collection listings; updating one updates the other.
 
 ### Collection metadata
 
-A Collection has the same metadata surface at its own reserved `/meta` path:
-server-managed properties (`createdAt` / `updatedAt` / `createdBy`) plus a
-user-writable `custom` object (`name` and `tags`). A server without the endpoint
-surfaces its 501 as `NotImplementedError`.
+A Collection's configuration (`name`, `backend`, `encryption`, `generator`, read
+by [`describe()`](#collections)) and its annotations live in one object at the
+Collection's reserved `/meta` path: server-managed properties (`createdAt` /
+`updatedAt` / `createdBy`) plus a user-writable `custom` object (`name` and
+`tags`), under one `metaVersion` validator. `meta()` is that same object with
+`custom` decoded through the codec; `describe()` does not resolve the codec at
+all, so on an encrypted collection it reports `custom` as the opaque envelope. A
+server without the endpoint surfaces its 501 as `NotImplementedError`.
 
 ```ts
 const meta = await collection.meta() // CollectionMetadata | null (null on a miss)
@@ -561,19 +612,31 @@ await collection.setTags({ app: 'wallet' }) // keeps existing name
 
 // Conditional metadata write, against a `conditional-writes` backend.
 await collection.setMeta({ custom: { name: 'Vault' } }, { ifMatch: meta?.etag })
-// ...or write only if no metadata is set yet:
+// ...or create the Collection only if it does not exist yet:
 await collection.setMeta({ custom: { name: 'Vault' } }, { ifNoneMatch: true })
 ```
 
 A failed precondition throws `PreconditionFailedError` (412). This `/meta` ETag
-(`metaVersion`) is versioned independently of the Collection Description's ETag
-and of every Resource's versions: writing one never bumps the other.
+(`metaVersion`) is independent of every Resource's versions, but not of the
+configuration members: one validator covers the whole Collection Metadata
+object, so `configure()` and `setMeta()` advance the same counter.
+
+The write is a full replacement of that one object, so an annotation write
+re-sends the configuration members (and any member this client does not model)
+as read, and `configure()` merges over the version it pins to. Two consequences
+worth knowing. `ifNoneMatch: true` is the only annotation write that may create:
+it means "create the Collection only if it does not exist", creates it with no
+configuration, and encodes `custom` with the plaintext codec, since the body it
+sends declares no encryption descriptor (pass a per-handle `encryption` override
+to state one). Every other annotation write requires a readable current object
+and throws `NotFoundError` when there is none -- a masked 404 cannot turn a
+rename into a create.
 
 On an encrypted collection `custom` is encrypted into an envelope before it is
 sent, so `name` / `tags` are never stored as server-visible plaintext, and
 `meta()` decrypts them back for a keyed reader. This is the encrypted
-collection's name/tags surface: by convention the plaintext Description `name`
-is left unpopulated there.
+collection's name/tags surface: by convention the plaintext top-level `name` is
+left unpopulated there.
 
 #### The governing history log
 
@@ -594,11 +657,12 @@ await collection.putHistoryLog(log.body + nextLine, { ifMatch: log.etag })
 
 From the create on, `describe()` serves `encryption` as the log head's `state`
 with `history: { method, resource }` stamped on, and a direct `encryption` write
-on the Description throws `ConflictError`. The create is refused the same way on
-a Collection whose Description already carries a client-written descriptor. A
-lost race throws `PreconditionFailedError` (412). These are the raw transport
-methods; the `/log` subpath's `resourceLogStore({ collection })` (below) drives
-them as the resource-log store port.
+on the Collection Metadata object throws `ConflictError`. The create is refused
+the same way on a Collection whose Metadata object already carries a
+client-written descriptor. A lost race throws `PreconditionFailedError` (412).
+These are the raw transport methods; the `/log` subpath's
+`resourceLogStore({ collection })` (below) drives them as the resource-log store
+port.
 
 A reader that holds the descriptor but not the convention follows its `history`
 pointer through the `/edv` subpath's `logGovernedCollectionDescriptorStore`, the
@@ -759,10 +823,9 @@ stores faithfully). Two things drive it, kept separate:
 
 - **Policy** (is this collection encrypted?) is declared on the collection
   itself: `createCollection({ encryption: { scheme: 'edv' } })` writes a
-  non-secret `encryption` descriptor to the Collection Description. Any
+  non-secret `encryption` descriptor to the Collection Metadata object. Any
   authorized reader -- including a delegated consumer that did **not** create
-  the collection -- discovers it by reading the Description, so it knows to
-  decrypt.
+  the collection -- discovers it by reading that object, so it knows to decrypt.
 - **Keys** come from an `encryption` provider you pass to `WasClient` (built
   from the opt-in `@interop/was-client/edv` subpath, so plaintext consumers
   never pull the crypto graph). It is a pure **keystore**: `resolveKeys` returns
@@ -794,21 +857,23 @@ const { id } = await vault.add({ secret: 'hello' }) // encrypted; id is an EDV i
 const back = await vault.get(id) // { secret: 'hello' } -- decrypted
 
 // A consumer that did not create it discovers the descriptor and decrypts with its
-// own keys -- no override needed; one cached read of the Description:
+// own keys -- no override needed; one cached read of the Collection Metadata
+// object:
 const same = was.space(spaceId).collection('vault')
 await same.get(id) // reads the descriptor, then decrypts
 ```
 
 The switch is the **descriptor**: a handle encrypts a collection when its
-Description declares `encryption` (resolution reads the Description once, then
-caches -- no round-trip for plaintext-only clients or when an override is set).
-Keys are then **required**: if the collection is declared encrypted but your
-keystore returns no keys, reads/writes throw `EncryptionError` (fail-closed) --
-they never silently fall back to plaintext.
+Collection Metadata object declares `encryption` (resolution reads that object
+once, then caches -- no round-trip for plaintext-only clients or when an
+override is set). Keys are then **required**: if the collection is declared
+encrypted but your keystore returns no keys, reads/writes throw
+`EncryptionError` (fail-closed) instead of silently falling back to plaintext.
 
 **Per-handle override (escape hatch).** Pass `encryption` in the handle options
-to force the decision and skip the Description read -- `{ scheme: 'edv' }` (keys
-from the keystore), `{ scheme: 'edv', keys }` (keys inline), or `'plaintext'`:
+to force the decision and skip the Collection Metadata read --
+`{ scheme: 'edv' }` (keys from the keystore), `{ scheme: 'edv', keys }` (keys
+inline), or `'plaintext'`:
 
 ```ts
 const vault = was.space(spaceId).collection('vault', {
@@ -820,8 +885,12 @@ const vault = was.space(spaceId).collection('vault', {
 keys-only): re-declare it once with
 `collection.configure({ encryption: { scheme: 'edv' } })` (the descriptor is
 set-once: declaring it on a collection that lacks one is allowed, changing or
-clearing an existing one is rejected). Until then, a per-handle override reads
-it correctly.
+clearing an existing one is rejected). The same write re-seals the stored
+`custom` under the newly declared descriptor, since the server validates the
+envelope against the incoming one; a client that cannot build that codec (no
+keystore, or no keys for the descriptor) sends no `custom` at all rather than
+plaintext beside the descriptor, which loses the stored name and tags. Until the
+collection is re-declared, a per-handle override reads it correctly.
 
 Encrypted collections are a **stricter contract**, not a drop-in (documents-only
 scope for now):
@@ -842,9 +911,9 @@ scope for now):
   endpoint has its own ETag (`metaVersion`), independent of the content ETag.
   The same pair at Collection level (`collection.setName()` / `setTags()` /
   `setMeta()` / `meta()`) is where an encrypted collection carries its own name
-  and tags, since the Description's plaintext `name` is left unpopulated; the
-  collection-level envelope binds no resource id, and a resource-bound envelope
-  served into that slot is refused.
+  and tags, since the Collection Metadata object's plaintext `name` is left
+  unpopulated; the collection-level envelope binds no resource id, and a
+  resource-bound envelope served into that slot is refused.
 - **Binary.** A `Blob`/`Uint8Array` up to `maxBlobBytes` (512 KiB by default) is
   encrypted as a single document. A larger one is routed automatically by
   `add()` to the chunked-stream path: one document plus its chunk resources,
@@ -1113,7 +1182,8 @@ large Blobs to disk.)
 `was.request(...)` mirrors ezcap's generic `request()` for hand-built calls. As
 a deliberate escape hatch it returns the raw `HttpResponse` and throws raw
 ezcap/ky errors -- it does not apply the null-on-404 or typed-error
-conveniences.
+conveniences. It still waits on service discovery, so against an incompatible
+server it rejects with `IncompatibleServerError`.
 
 ```ts
 const response = await was.request({ path: `/space/${spaceId}`, method: 'GET' })
@@ -1150,6 +1220,12 @@ instead, as `{ outcome: 'not-found' }`, rather than swallowing it.
 Spec endpoints a given server has not yet implemented surface as
 `NotImplementedError` (the server's 501).
 
+`IncompatibleServerError` comes from service discovery, not from a response
+status. Any signed method, read methods included, throws it when the server
+speaks no WAS version this client understands (see
+[Service discovery](#service-discovery)). It carries no `status`, so a read
+method does not mistake it for a 404.
+
 ## Contribute
 
 PRs accepted. See [CONTRIBUTING.md](CONTRIBUTING.md) for editor setup (Prettier,

package/dist/Collection.d.ts

@@ -2,7 +2,7 @@ import type { ClientContext } from './internal/request.js';
 import type { IndexDeclaration, IndexSchema } from './codec.js';
 import { Resource } from './Resource.js';
 import type { ChangeDocument, ChangesCheckpoint, ChangesPage } from '@interop/storage-core';
-import type { AddResult, BackendDescriptor, BackendUsage, CollectionDescription, CollectionMetadata, CollectionWritableFields, EncryptionOverride, FindPage, GrantOptions, HandleOptions, IDelegatedZcap, IZcap, Json, ResourceData, LinkSet, PolicyDocument, CollectionResourcesList, ResourceMetadataCustomInput, ResourceSummary } from './types.js';
+import type { AddResult, BackendDescriptor, BackendUsage, CollectionMetadata, CollectionWritableFields, EncryptionOverride, FindPage, GrantOptions, HandleOptions, IDelegatedZcap, IZcap, Json, ResourceData, LinkSet, PolicyDocument, CollectionResourcesList, ResourceMetadataCustomInput, ResourceSummary } from './types.js';
 export declare class Collection {
     #private;
     readonly spaceId: string;
@@ -26,93 +26,121 @@ export declare class Collection {
         encryption?: EncryptionOverride;
     });
     /**
-     * Reads the Collection Description. Returns `null` if the collection is
-     * missing or not visible to you (WAS returns 404 for both not-found and
-     * unauthorized).
+     * Reads the Collection Metadata object -- the Collection's configuration
+     * (`name`, `backend`, `encryption`, `generator`) beside the server-managed
+     * timestamps and the user-writable `custom`, as one object under one
+     * validator. Returns `null` if the collection is missing or not visible to
+     * you (WAS returns 404 for both not-found and unauthorized).
      *
-     * @returns {Promise<CollectionDescription | null>}
+     * This read never resolves the codec, so it is the configuration read: on an
+     * encrypted Collection the served `custom` is the opaque envelope, exactly as
+     * stored. {@link meta} is the same object with `custom` decoded.
+     *
+     * @returns {Promise<(CollectionMetadata & { etag?: string }) | null>}
      */
-    describe(): Promise<CollectionDescription | null>;
+    describe(): Promise<(CollectionMetadata & {
+        etag?: string;
+    }) | null>;
     /**
-     * Creates or updates the collection by id (upsert). Merges the given fields
-     * over the current description.
+     * {@link describe}, with the object and its `ETag` in separate members. The
+     * `ETag` is the `metaVersion` validator to pass to
+     * {@link replaceDescription}'s `ifMatch` for a lost-update-safe
+     * (compare-and-swap) write. One validator covers the whole object, so it is
+     * also what {@link setMeta} pins against. Returns `null` if the collection is
+     * missing or not visible to you (404 conflation caveat); `etag` is absent
+     * against a backend that does not version the object.
      *
-     * The merge needs a readable current description to be lost-update-safe, and
-     * `describe()` cannot distinguish "absent" from "unreadable" (WAS masks
-     * unauthorized reads as 404). When it returns `null` and either `backend`
-     * or `encryption` is left out, this fails closed rather than sending a PUT
-     * body that would silently drop an existing collection's `backend` (a
-     * data-placement change) or trip `encryption-immutable` by clearing its
-     * descriptor on a replace-semantics server. Supplying only one of the two
-     * does not cover the other: with nothing readable to merge from, the
-     * omitted field is dropped either way. Pass `force: true` to proceed
-     * anyway
-     * -- e.g. when creating a new collection through a handle (or use
-     * `space.createCollection()`, which does not merge).
+     * @returns {Promise<{ description: CollectionMetadata; etag?: string } | null>}
+     */
+    describeWithEtag(): Promise<{
+        description: CollectionMetadata;
+        etag?: string;
+    } | null>;
+    /**
+     * Creates or updates the collection by id (upsert). Merges the given
+     * configuration members over the current ones; the annotations (`custom` and
+     * its `epoch` stamp) are carried forward untouched, unless this write
+     * changes the encryption scheme, in which case `custom` is re-sealed under
+     * the incoming descriptor (see {@link replaceDescription}).
+     *
+     * The merge runs against the same read the write is pinned to, and rebases
+     * with it: a rival configuration change landing in between is re-read and
+     * merged over rather than re-applied stale.
+     *
+     * The merge needs a readable current object to be lost-update-safe, and the
+     * read cannot distinguish "absent" from "unreadable" (WAS masks unauthorized
+     * reads as 404). When it finds nothing and either `backend` or `encryption`
+     * is left out, this fails closed rather than sending a PUT body that would
+     * silently drop an existing collection's `backend` (a data-placement change)
+     * or trip `encryption-immutable` by clearing its descriptor. Supplying only
+     * one of the two does not cover the other: with nothing readable to merge
+     * from, the omitted field is dropped either way. Pass `force: true` to
+     * proceed anyway -- e.g. when creating a new collection through a handle (or
+     * use `space.createCollection()`, which does not merge).
      *
      * @param desc {CollectionWritableFields}   the fields to merge; `encryption`
      *   declares the client-side encryption descriptor, which is set-once on the
      *   server (it may be added to a Collection that lacks one, but
      *   changing/clearing an existing descriptor is rejected -- `ConflictError`,
      *   `encryption-immutable`)
-     * @param [desc.force] {boolean}   proceed even when the current description
+     * @param [desc.force] {boolean}   proceed even when the current object
      *   is unreadable and `backend`/`encryption` are omitted (see above)
-     * @param [desc.current] {CollectionDescription | null}   the current
-     *   description, when the caller has already read it -- the merge and the
-     *   fail-closed check then run against this instead of a second `describe()`
-     *   round trip. `null` means the caller read it and found the collection
-     *   absent or unreadable, which is a supplied answer; omitting the member
-     *   entirely is what asks for the read. Supplying a description this
-     *   handle's own writes have since superseded would merge stale fields
-     *   forward -- dropping a `backend` or tripping `encryption-immutable` --
-     *   so pass only a read the caller itself made and has not written over
-     * @returns {Promise<CollectionDescription>}
+     * @param [desc.current] {CollectionMetadata | null}   the current Collection
+     *   Metadata object, when the caller has already read it -- the merge's first
+     *   attempt then runs against this instead of a second read. It is used only
+     *   while it carries the `etag` the write pins against, so a copy another
+     *   client has since overwritten loses the compare-and-swap and is re-read
+     *   rather than merged forward. `null` means the caller read it and found
+     *   the collection absent or unreadable; omitting the member entirely is
+     *   what asks for the read
+     * @returns {Promise<CollectionMetadata>}
      */
     configure(desc: CollectionWritableFields & {
         force?: boolean;
-        current?: CollectionDescription | null;
-    }): Promise<CollectionDescription>;
+        current?: (CollectionMetadata & {
+            etag?: string;
+        }) | null;
+    }): Promise<CollectionMetadata>;
     /**
-     * Reads the Collection Description together with its `ETag` validator (the
-     * server's `conditional-writes` / description-version support). The `ETag` is
-     * the opaque validator to pass to {@link replaceDescription}'s `ifMatch` for a
-     * lost-update-safe (compare-and-swap) description write. Returns `null` if the
-     * collection is missing or not visible to you (404 conflation caveat); `etag`
-     * is absent against a server that does not version the description.
-     *
-     * @returns {Promise<{ description: CollectionDescription; etag?: string } | null>}
-     */
-    describeWithEtag(): Promise<{
-        description: CollectionDescription;
-        etag?: string;
-    } | null>;
-    /**
-     * Writes (replaces) the Collection Description, optionally under a
-     * precondition: `ifMatch` (the `ETag` from {@link describeWithEtag}) makes
+     * Writes (replaces) the Collection's configuration members, optionally under
+     * a precondition: `ifMatch` (the `ETag` from {@link describeWithEtag}) makes
      * it a compare-and-swap so a concurrent writer cannot be silently clobbered,
      * and `ifNoneMatch: true` makes it a guarded create that proceeds only while
      * no Collection exists under this id. A failed precondition surfaces as
-     * `PreconditionFailedError` (412). Sends the writable fields as the full
-     * body; omit a field to drop it (replace semantics), so callers doing CAS
-     * pass every field forward. Returns the new `ETag` and the fields written.
-     *
-     * This is the generic description-CAS primitive the key-epoch recipient
+     * `PreconditionFailedError` (412). Sends the writable configuration as the
+     * full body; omit a member to drop it (replace semantics), so callers doing
+     * CAS pass every member forward. Members this client does not model are
+     * carried forward from the stored object rather than cleared.
+     *
+     * The annotations (`custom` and its `epoch` stamp) are carried forward
+     * verbatim -- `custom` exactly as served, so an encrypted Collection's
+     * envelope is never re-sealed by an ordinary configuration write. The one
+     * exception is a write that changes the encryption scheme: the server
+     * validates `custom` against the INCOMING descriptor, so a stored plaintext
+     * `custom` cannot travel beside a newly declared `encryption` descriptor.
+     * Such a write re-seals `custom` under the incoming descriptor's codec, and
+     * drops `custom` (and its stamp) when this client cannot build that codec.
+     * A Collection with no stored `custom` sends none, which clears an
+     * already-empty value on an encrypted Collection just as on a plaintext one.
+     * Returns the new `ETag`, and the object the server answers a create with.
+     *
+     * This is the generic compare-and-swap primitive the key-epoch recipient
      * operations build on (add/remove a reader is a CAS of the `encryption`
      * descriptor); it is not epoch-specific.
      *
      * @param description {CollectionWritableFields}
      * @param options {object}
      * @param [options.ifMatch] {string}   the prior `ETag`; the write applies only
-     *   if the description is unchanged
+     *   if the object is unchanged
      * @param [options.ifNoneMatch] {boolean}   write only if the Collection does
      *   not exist yet
-     * @returns {Promise<{ description: CollectionDescription; etag?: string }>}
+     * @returns {Promise<{ description: CollectionMetadata; etag?: string }>}
      */
     replaceDescription(description: CollectionWritableFields, options?: {
         ifMatch?: string;
         ifNoneMatch?: boolean;
     }): Promise<{
-        description: CollectionDescription;
+        description: CollectionMetadata;
         etag?: string;
     }>;
     /**
@@ -123,23 +151,25 @@ export declare class Collection {
      */
     delete(): Promise<void>;
     /**
-     * Reads the Collection's metadata object (server-managed timestamps,
-     * `createdBy` and the encrypted-`custom` key `epoch`, plus the user-writable
-     * `custom` object). Returns `null` if the collection is missing or not
-     * visible to you (404 conflation caveat). A server without Collection
-     * metadata support surfaces its 501 as `NotImplementedError`.
+     * Reads the Collection Metadata object with its user-writable `custom`
+     * decoded -- {@link describe} plus the codec. Returns `null` if the
+     * collection is missing or not visible to you (404 conflation caveat). A
+     * server without Collection metadata support surfaces its 501 as
+     * `NotImplementedError`.
      *
      * On an encrypted collection the stored `custom` is an opaque envelope; this
      * decodes it (decrypts, via the codec) so a caller always sees plaintext
      * `{ name, tags }`. A collection with no user metadata reports `custom` as
-     * `{}`.
+     * `{}`. Resolving the codec can fail closed on a collection this client holds
+     * no keys for, which is why {@link describe} -- the configuration read -- goes
+     * without it.
      *
      * Against a backend with the `conditional-writes` feature the result also
-     * carries the metadata's current `etag` (the `/meta` `metaVersion`
-     * validator) -- pass it as `setMeta(meta, { ifMatch })` for a
-     * lost-update-safe metadata update. That validator is independent of the
-     * Collection Description's ETag ({@link describeWithEtag}) and of every
-     * Resource's versions: writing one never bumps the other.
+     * carries the object's current `etag` (its `metaVersion` validator) -- pass it
+     * as `setMeta(meta, { ifMatch })` for a lost-update-safe update. One
+     * validator covers the whole object: a configuration write and an annotation
+     * write advance the same counter, so a client holds one ETag for the
+     * Collection rather than one per surface.
      *
      * @returns {Promise<(CollectionMetadata & { etag?: string }) | null>}
      */
@@ -147,24 +177,33 @@ export declare class Collection {
         etag?: string;
     }) | null>;
     /**
-     * Replaces the Collection's user-writable metadata (`custom`). This is a full
-     * replacement: any property omitted from `custom` is cleared, and an omitted
-     * `custom` clears them all. Does not create the collection -- a `PUT` to the
-     * metadata of a nonexistent collection throws `NotFoundError`. Servers
-     * without Collection metadata support surface their 501 as
-     * `NotImplementedError`.
+     * Replaces the Collection's user-writable annotations (`custom`). This is a
+     * full replacement of `custom`: any property omitted from it is cleared, and
+     * an omitted `custom` clears them all. The Collection's configuration
+     * members are carried forward -- the same `PUT` replaces the whole
+     * Collection Metadata object, so they are read and re-sent rather than
+     * dropped.
      *
      * On an encrypted collection `custom` is encrypted into an opaque envelope by
      * the codec before it is sent, so `name` / `tags` are never stored as
      * server-visible plaintext -- transparently, the same call works on plaintext
-     * and encrypted collections alike.
-     *
-     * Conditional metadata writes (the backend's `conditional-writes` feature):
-     * pass `ifMatch` (the `etag` from a prior `meta()`) for an
-     * update-if-unchanged, or `ifNoneMatch: true` for a
-     * write-only-if-no-metadata. A failed precondition throws
-     * `PreconditionFailedError` (412). The `/meta` ETag (`metaVersion`) is
-     * independent of the Collection Description's ETag. Returns the new `etag`.
+     * and encrypted collections alike. The key epoch the codec stamps the
+     * envelope with travels as a top-level `epoch` member of the same body.
+     *
+     * Conditional writes (the backend's `conditional-writes` feature): pass
+     * `ifMatch` (the `etag` from a prior {@link meta} or {@link describe}) for an
+     * update-if-unchanged, and a failed precondition throws
+     * `PreconditionFailedError` (412). Without one the write is pinned to the
+     * version it composed the configuration from and rebases on a lost race.
+     * `ifNoneMatch: true` is the guarded create: one validator covers the whole
+     * object, which exists exactly as long as its Collection does, so it means
+     * "create the Collection only if it does not exist" -- and creates it with no
+     * configuration, the plaintext codec encoding its `custom` (nothing is
+     * stored yet to declare encryption, and a per-handle override is the only
+     * way to state it). Every other annotation write requires the Collection to
+     * be there: one that cannot read the current object throws `NotFoundError`
+     * rather than upserting a configuration-less Collection over one this
+     * capability cannot see. Returns the new `etag`.
      *
      * @param meta {object}
      * @param [meta.custom] {ResourceMetadataCustomInput}   the user-writable
@@ -172,9 +211,10 @@ export declare class Collection {
      *   Collection-level `custom` also carries the persisted `indexSchema`)
      *   while `name` / `tags` themselves stay checked at their stored types
      * @param options {object}
-     * @param [options.ifMatch] {string}       update only if the `/meta` ETag matches
-     * @param [options.ifNoneMatch] {boolean}  write only if no metadata is set
-     * @returns {Promise<{ etag?: string }>}   the metadata's new ETag
+     * @param [options.ifMatch] {string}       update only if the `ETag` matches
+     * @param [options.ifNoneMatch] {boolean}  create only if the Collection does
+     *   not exist
+     * @returns {Promise<{ etag?: string }>}   the object's new ETag
      */
     setMeta(meta?: {
         custom?: ResourceMetadataCustomInput;
@@ -185,19 +225,20 @@ export declare class Collection {
         etag?: string;
     }>;
     /**
-     * Sets the Collection's metadata-level human-readable `name`, preserving any
-     * existing `tags`. Convenience over `setMeta()`. The write is pinned to the
-     * `etag` the `meta()` read returned (when the backend supports
-     * `conditional-writes`), so a concurrent metadata write surfaces as
-     * `PreconditionFailedError` instead of being silently erased by this
+     * Sets the Collection's annotation-level human-readable `name`, preserving
+     * any existing `tags`. Convenience over `setMeta()`. The write is pinned to
+     * the `etag` the `meta()` read returned (when the backend supports
+     * `conditional-writes`) and rebases on a lost race, so a concurrent write --
+     * an annotation write or a configuration change, which share the one
+     * validator -- is re-read and re-applied rather than silently erased by this
      * full-replacement write.
      *
      * On an encrypted collection this is the collection's client-encrypted name
      * surface: the codec seals it into the `custom` envelope, and by convention
-     * the plaintext Description `name` is left unpopulated. On a plaintext
+     * the plaintext top-level `name` is left unpopulated. On a plaintext
      * collection the two are separate labels -- space-level listings surface the
-     * Description's `name` (set via `configure({ name })`), while this one is
-     * metadata-level.
+     * top-level `name` (set via `configure({ name })`), while this one is inside
+     * `custom`.
      *
      * @param name {string}
      * @returns {Promise<void>}
@@ -213,7 +254,7 @@ export declare class Collection {
      */
     setTags(tags: Record<string, string>): Promise<void>;
     /**
-     * The absolute URL of the Collection's governing history log, the `/meta/log`
+     * The absolute URL of the Collection's governing history log, the `meta/log`
      * sub-resource {@link getHistoryLog} reads. A log-governed descriptor's
      * `history.resource` names this URL; a verifying reader compares the two
      * before opening the log.