@interop/was-client 0.60.0 → 0.61.0

package/dist/internal/codec.js

@@ -1,9 +1,7 @@
 import { prepareBody, parseResource } from './content.js';
-import { describeCollection, unreadableDescriptionError } from './describe.js';
+import { asCollectionMetadata, readCollectionMetadata, storedEncryption, unreadableDescriptionError } from './describe.js';
 import { readIndexSchema } from './indexSchema.js';
-import { readMeta } from './meta.js';
 import { Memo } from './memo.js';
-import { collectionMeta } from './paths.js';
 import { EncryptionError, NotImplementedError } from '../errors.js';
 /**
  * A per-handle codec cache. Memoizes the in-flight resolution so concurrent
@@ -138,32 +136,40 @@ export async function resolveCodec(context, { spaceId, collectionId, override, c
         // descriptor's epoch roster and refuses an override without one
         // fail-closed, so dropping the descriptor here would break every read and
         // write.
-        return buildEncryptingCodec(context, {
+        const { codec } = await buildEncryptingCodec(context, {
             spaceId,
             collectionId,
             scheme: override.scheme,
             keys: override.keys,
-            capability,
             encryption: override
         });
+        // The override skipped the Collection Metadata read, so a searchable
+        // collection's persisted index schema is fetched here.
+        const meta = await loadIndexSchema(context, {
+            spaceId,
+            collectionId,
+            capability,
+            codec
+        });
+        return meta !== undefined ? { codec, meta } : { codec };
     }
     // 2. A plaintext-only client (no keystore) never encrypts; no round-trip.
     if (!context.encryption) {
         return { codec: identityCodec };
     }
     // 3. Otherwise the Collection's declared `encryption` descriptor decides -- but
-    // only if we could actually read the description. An unreadable description
-    // (a resource-scoped capability cannot GET the collection description, and
-    // WAS masks that as a 404) is ambiguous: it is indistinguishable from
-    // "absent", so an encryption-capable client fails closed rather than
-    // silently downgrading to plaintext and writing the caller's secret as
-    // server-visible plaintext into a possibly-encrypted collection.
-    const description = await describeCollection(context, {
+    // only if we could actually read the Collection Metadata object. An
+    // unreadable object (a resource-scoped capability cannot GET it, and WAS
+    // masks that as a 404) is ambiguous: it is indistinguishable from "absent",
+    // so an encryption-capable client fails closed rather than silently
+    // downgrading to plaintext and writing the caller's secret as server-visible
+    // plaintext into a possibly-encrypted collection.
+    const read = await readCollectionMetadata(context, {
         spaceId,
         collectionId,
         capability
     });
-    if (description === null) {
+    if (read === null) {
         throw unreadableDescriptionError({
             operation: `determine whether collection ${spaceId}/${collectionId} is ` +
                 'encrypted',
@@ -174,16 +180,91 @@ export async function resolveCodec(context, { spaceId, collectionId, override, c
             ErrorClass: EncryptionError
         });
     }
-    if (!description.encryption) {
-        return { codec: identityCodec };
+    const declared = storedEncryption(read.metadata);
+    const { codec } = declared
+        ? await buildEncryptingCodec(context, {
+            spaceId,
+            collectionId,
+            scheme: declared.scheme,
+            encryption: declared
+        })
+        : { codec: identityCodec };
+    // The read that decided policy IS the Collection Metadata object, so it is
+    // also the index schema and the `meta()` answer: decode its `custom` with the
+    // codec just built and hand the snapshot on, rather than reading the same
+    // document again. A `custom` this reader cannot open is not the resolution's
+    // business -- only `meta()` and the search paths need it -- so the decode
+    // failure leaves the schema empty and the snapshot absent instead of failing
+    // every operation on the handle.
+    const meta = await snapshotFrom({ read, codec });
+    return meta !== undefined ? { codec, meta } : { codec };
+}
+/**
+ * Builds the codec a descriptor names, for a write that states the descriptor
+ * itself rather than discovering it from stored state: the identity codec when
+ * there is no descriptor, and the keystore's codec when there is. Resolves
+ * `null` when this client cannot build that codec (no keystore, no keys, or an
+ * unhandled scheme) -- a caller that must not guess treats `null` as its own
+ * refusal, since nothing here is stored state to fail closed on.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.descriptor] {CollectionEncryption}   the descriptor the write
+ *   declares; absent means plaintext
+ * @returns {Promise<ResourceCodec | null>}
+ */
+export async function codecForDescriptor(context, { spaceId, collectionId, descriptor }) {
+    if (descriptor === undefined) {
+        return identityCodec;
+    }
+    if (!context.encryption) {
+        return null;
     }
-    return buildEncryptingCodec(context, {
+    const codec = await context.encryption.codecFor({
         spaceId,
         collectionId,
-        scheme: description.encryption.scheme,
-        encryption: description.encryption,
-        capability
+        scheme: descriptor.scheme,
+        encryption: descriptor
     });
+    return codec ?? null;
+}
+/**
+ * Turns the Collection Metadata object a resolution read into the snapshot the
+ * resolution carries: `custom` decoded through the codec just built (an opaque
+ * envelope on an encrypted collection), and the codec's persisted index schema
+ * installed from it along the way.
+ *
+ * A `custom` the decode refuses -- a reader removed from the collection whose
+ * epoch key no longer unwraps it, an envelope bound to another slot, a
+ * plaintext object where an envelope belongs -- resolves `undefined` rather
+ * than throwing. The schema then stays empty (a search on an undeclared
+ * attribute still fails loudly at `find()`), and the operations that do not
+ * need `custom` keep working; a `meta()` reads and decodes for itself and is
+ * the call that surfaces the refusal.
+ *
+ * @param options {object}
+ * @param options.read {object}   the stored object and its validator
+ * @param options.codec {ResourceCodec}
+ * @returns {Promise<(CollectionMetadata & { etag?: string }) | undefined>}
+ */
+async function snapshotFrom({ read, codec }) {
+    let custom;
+    try {
+        // The stated slot drives the encrypting codec's binding check: in the
+        // Collection slot it refuses a resource-bound envelope served there.
+        custom = await codec.decodeMeta({ custom: read.metadata.custom }, { kind: 'collection' });
+    }
+    catch {
+        return undefined;
+    }
+    codec.indexing?.applySchema(readIndexSchema(custom));
+    return {
+        ...asCollectionMetadata(read.metadata),
+        custom,
+        ...(read.etag !== undefined && { etag: read.etag })
+    };
 }
 /**
  * Builds the encrypting codec for a collection known to be encrypted, failing
@@ -196,12 +277,12 @@ export async function resolveCodec(context, { spaceId, collectionId, override, c
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param options.scheme {string}
+ * @param [options.encryption] {CollectionEncryption}   the descriptor, passed
+ *   whole to the provider
  * @param [options.keys] {unknown}   override-supplied key material
- * @param [options.capability] {IZcap}   the handle's bound capability, used for
- *   the index-schema read
  * @returns {Promise<CodecResolution>}
  */
-async function buildEncryptingCodec(context, { spaceId, collectionId, scheme, encryption, keys, capability }) {
+async function buildEncryptingCodec(context, { spaceId, collectionId, scheme, encryption, keys }) {
     const where = `${spaceId}/${collectionId}`;
     if (!context.encryption) {
         throw new EncryptionError(`Collection ${where} is encrypted (scheme "${scheme}") but this client ` +
@@ -220,20 +301,14 @@ async function buildEncryptingCodec(context, { spaceId, collectionId, scheme, en
             'holds no keys for it (or does not handle the scheme). Supply keys via ' +
             'your keystore (resolveKeys) or a per-handle encryption override.');
     }
-    const meta = await loadIndexSchema(context, {
-        spaceId,
-        collectionId,
-        capability,
-        codec
-    });
-    return meta !== undefined ? { codec, meta } : { codec };
+    return { codec };
 }
 /**
- * Loads the collection's persisted index schema onto a freshly-built codec, so
- * writes through it emit index tokens for the declared attributes and searches
- * can be built for them. A no-op for a codec with no search capability -- which
- * is every codec on a collection whose descriptor declares no blinding key, so
- * an ordinary encrypted collection pays no round-trip here.
+ * Loads the collection's persisted index schema onto a codec built from a
+ * per-handle encryption override -- the one path that skipped the Collection
+ * Metadata read, so the schema is not already in hand. A no-op for a codec with
+ * no search capability, which is every codec on a collection whose descriptor
+ * declares no blinding key.
  *
  * The schema is discovered rather than declared per app: it is the reason
  * declarations are persisted at all, so a reader that did not create the
@@ -247,7 +322,7 @@ async function buildEncryptingCodec(context, { spaceId, collectionId, scheme, en
  * failing the resolution: neither says the collection is broken, and every
  * search on an undeclared attribute still fails loudly at `find()`.
  *
- * The decoded metadata is returned so the caller that paid for this read can
+ * The decoded metadata is returned so the caller that paid for the read can
  * hand it to a `meta()` that would otherwise repeat it -- it is exactly what
  * `Collection.meta()` produces, decrypted `custom` and `etag` included.
  *
@@ -262,17 +337,14 @@ async function buildEncryptingCodec(context, { spaceId, collectionId, scheme, en
  *   no read happened at all
  */
 async function loadIndexSchema(context, { spaceId, collectionId, capability, codec }) {
-    const { indexing } = codec;
-    if (!indexing) {
+    if (!codec.indexing) {
         return undefined;
     }
-    let meta;
+    let read;
     try {
-        meta = await readMeta(context, {
-            metaPath: collectionMeta(spaceId, collectionId),
-            codec: Promise.resolve(codec),
-            subject: `collection "${collectionId}"`,
-            slot: { kind: 'collection' },
+        read = await readCollectionMetadata(context, {
+            spaceId,
+            collectionId,
             capability
         });
     }
@@ -282,10 +354,9 @@ async function loadIndexSchema(context, { spaceId, collectionId, capability, cod
         }
         throw err;
     }
-    if (meta === null) {
+    if (read === null) {
         return null;
     }
-    indexing.applySchema(readIndexSchema(meta.custom));
-    return meta;
+    return snapshotFrom({ read, codec });
 }
 //# sourceMappingURL=codec.js.map

package/dist/internal/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"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"}

package/dist/internal/describe.d.ts

@@ -2,19 +2,44 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * Reads a Collection Description with a single GET. Shared by
- * `Collection.describe()` and the standalone-resource codec's descriptor
- * discovery so the request shape (path, capability, null-unwrap) lives in one
- * place. Also owns the masked-404 fail-closed policy: WAS returns 404 for both
- * not-found and unauthorized, so a `null` description is ambiguous and an
- * operation that must know the current state fails closed via
+ * Reads a Collection Metadata object with a single GET of the Collection's
+ * `meta` sub-resource, in the wire form the server serves it: `custom` is
+ * whatever is stored there (an opaque envelope on an encrypted Collection),
+ * left undecoded, because the codec that would decode it is itself resolved
+ * from this object's `encryption` member. Shared by `Collection`'s read and
+ * write paths and by the codec resolver's descriptor discovery, so the request
+ * shape (path, capability, null-unwrap, validator) lives in one place.
+ *
+ * Also owns the masked-404 fail-closed policy: WAS returns 404 for both
+ * not-found and unauthorized, so a `null` read is ambiguous and an operation
+ * that must know the current state fails closed via
  * `unreadableDescriptionError` rather than guessing. `collectionWritableFields`
- * lives here too: it is the one inclusion rule for the writable description
- * fields, shared by every path that builds a description body.
+ * lives here too: it is the one inclusion rule for the writable configuration
+ * members a caller supplies, beside `carriedForward`, the rule for the stored
+ * members a full-replacement write re-sends unchanged.
  */
 import type { ClientContext } from './request.js';
 import type { WasError } from '../errors.js';
-import type { CollectionDescription, CollectionEncryption, CollectionWritableFields, IZcap } from '../types.js';
+import type { CollectionEncryption, CollectionMetadata, CollectionWritableFields, IZcap } from '../types.js';
+/**
+ * A Collection Metadata object exactly as the server served it. Typed as an
+ * open record rather than as `CollectionMetadata`, because `custom` here is the
+ * stored value (an opaque encryption envelope on an encrypted Collection) and
+ * because a write forwards members this client does not model verbatim rather
+ * than dropping them (see {@link carriedForward}).
+ */
+export type StoredCollectionMetadata = Record<string, unknown>;
+/**
+ * Reads a stored Collection Metadata object as the `CollectionMetadata` wire
+ * type. The stored form is typed as an open record -- `custom` is the stored
+ * value and a write forwards members this client does not model -- while the
+ * server guarantees the object's shape, so the assertion lives here once
+ * instead of at each reader.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @returns {CollectionMetadata}
+ */
+export declare function asCollectionMetadata(stored: StoredCollectionMetadata): CollectionMetadata;
 /**
  * Whether a served encryption descriptor is the server-derived projection of
  * a Collection governed by its history log (it carries the `history` pointer)
@@ -31,38 +56,87 @@ export declare function isGovernedDescriptor(descriptor: CollectionEncryption):
     };
 };
 /**
- * Picks the writable Collection Description fields that are set. The one
- * inclusion rule (`!== undefined`) behind every description body -- the
- * `configure` / `replaceDescription` request bodies and their echoed return
- * descriptions, and `Space.createCollection`'s create body -- so the paths
- * cannot drift and a new writable field is added in one place.
+ * Picks the writable Collection configuration members that are set. The one
+ * inclusion rule (`!== undefined`) behind every Collection Metadata write body
+ * -- the `configure` / `replaceDescription` request bodies and their echoed
+ * returns, and `Space.createCollection`'s create body -- so the paths cannot
+ * drift and a new writable member is added in one place.
  *
  * @param fields {CollectionWritableFields}
  * @returns {CollectionWritableFields}
  */
 export declare function collectionWritableFields(fields: CollectionWritableFields): CollectionWritableFields;
 /**
- * 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).
+ * The Collection's configuration members: what a configuration write
+ * (`configure`, `replaceDescription`) states in full and an annotation write
+ * carries forward.
+ */
+export declare const CONFIGURATION_MEMBERS: readonly string[];
+/**
+ * The Collection's annotation members: the user-writable `custom` and the key
+ * epoch its envelope was sealed under. What an annotation write (`setMeta` and
+ * its sugar) states and a configuration write carries forward.
+ */
+export declare const ANNOTATION_MEMBERS: readonly string[];
+/**
+ * Reads a stored `encryption` descriptor at its wire type. The one place the
+ * open stored record is narrowed to `CollectionEncryption`, shared by the
+ * compose paths and the codec resolver so the assertion is not repeated.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @returns {CollectionEncryption | undefined}
+ */
+export declare function storedEncryption(stored: StoredCollectionMetadata): CollectionEncryption | undefined;
+/**
+ * Picks the stored members a full-replacement write carries forward: every
+ * member except the ones the server manages and the ones this write states
+ * itself. A denylist rather than an allowlist, so a member this client does
+ * not model -- `plaintext`, or one a newer server serves -- survives a write
+ * it is not about instead of being silently cleared.
+ *
+ * A governed `encryption` descriptor is deliberately dropped: on a
+ * log-governed Collection the served descriptor is the server's projection of
+ * the history log's head, and a write that carries it is refused
+ * (`encryption-history-log-governed`). Omitting the member leaves the derived
+ * descriptor in place.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @param options {object}
+ * @param options.replacing {readonly string[]}   the members this write states
+ *   itself (`CONFIGURATION_MEMBERS` on a configuration write,
+ *   `ANNOTATION_MEMBERS` on an annotation write)
+ * @returns {StoredCollectionMetadata}
+ */
+export declare function carriedForward(stored: StoredCollectionMetadata, { replacing }: {
+    replacing: readonly string[];
+}): StoredCollectionMetadata;
+/**
+ * Reads the Collection Metadata object with its `metaVersion` validator, in the
+ * stored wire form. Returns `null` if the collection is missing or not visible
+ * to you (WAS returns 404 for both not-found and unauthorized); `etag` is
+ * absent against a backend that does not version the object.
  *
  * @param context {ClientContext}
  * @param options {object}
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param [options.capability] {IZcap}   capability attached to the request
- * @returns {Promise<CollectionDescription | null>}
+ * @returns {Promise<{ metadata: StoredCollectionMetadata; etag?: string } | null>}
  */
-export declare function describeCollection(context: ClientContext, options: {
+export declare function readCollectionMetadata(context: ClientContext, options: {
     spaceId: string;
     collectionId: string;
     capability?: IZcap;
-}): Promise<CollectionDescription | null>;
+}): Promise<{
+    metadata: StoredCollectionMetadata;
+    etag?: string;
+} | null>;
 /**
- * Builds the fail-closed error for an operation that needs a description it
- * could not read. The one owner of the masked-404 policy statement ("WAS
- * returns 404 for both not-found and unauthorized, so a null description is
- * ambiguous -- fail closed"); callers supply the operation, its consequence,
- * and the recovery advice.
+ * Builds the fail-closed error for an operation that needs a Collection
+ * Metadata object it could not read. The one owner of the masked-404 policy
+ * statement ("WAS returns 404 for both not-found and unauthorized, so a null
+ * read is ambiguous -- fail closed"); callers supply the operation, its
+ * consequence, and the recovery advice.
  *
  * @param options {object}
  * @param options.operation {string}      what was refused, continuing "Cannot ..."

package/dist/internal/describe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/internal/describe.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAIjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,EACN,MAAM,aAAa,CAAA;AAEpB;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,oBAAoB,GAC/B,UAAU,IAAI,oBAAoB,GAAG;IACtC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C,CAEA;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,wBAAwB,CAU1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACrE,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAKvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAA4B,EAC7B,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,QAAQ,CAAA;CAC/C,GAAG,QAAQ,CAQX"}
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/internal/describe.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAIjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,EACN,MAAM,aAAa,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE9D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,wBAAwB,GAC/B,kBAAkB,CAEpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,oBAAoB,GAC/B,UAAU,IAAI,oBAAoB,GAAG;IACtC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C,CAEA;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,wBAAwB,CAU1B;AAsBD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwB,CAAA;AAExE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,wBAAwB,EAChC,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9C,wBAAwB,CAgB1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACrE,OAAO,CAAC;IAAE,QAAQ,EAAE,wBAAwB,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAYvE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAA4B,EAC7B,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,QAAQ,CAAA;CAC/C,GAAG,QAAQ,CAQX"}

package/dist/internal/describe.js

@@ -1,6 +1,19 @@
-import { readData } from './request.js';
-import { collectionPath } from './paths.js';
+import { readDataWithEtag } from './request.js';
+import { collectionMeta } from './paths.js';
 import { ValidationError } from '../errors.js';
+/**
+ * Reads a stored Collection Metadata object as the `CollectionMetadata` wire
+ * type. The stored form is typed as an open record -- `custom` is the stored
+ * value and a write forwards members this client does not model -- while the
+ * server guarantees the object's shape, so the assertion lives here once
+ * instead of at each reader.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @returns {CollectionMetadata}
+ */
+export function asCollectionMetadata(stored) {
+    return stored;
+}
 /**
  * Whether a served encryption descriptor is the server-derived projection of
  * a Collection governed by its history log (it carries the `history` pointer)
@@ -14,11 +27,11 @@ export function isGovernedDescriptor(descriptor) {
     return descriptor.history !== undefined;
 }
 /**
- * Picks the writable Collection Description fields that are set. The one
- * inclusion rule (`!== undefined`) behind every description body -- the
- * `configure` / `replaceDescription` request bodies and their echoed return
- * descriptions, and `Space.createCollection`'s create body -- so the paths
- * cannot drift and a new writable field is added in one place.
+ * Picks the writable Collection configuration members that are set. The one
+ * inclusion rule (`!== undefined`) behind every Collection Metadata write body
+ * -- the `configure` / `replaceDescription` request bodies and their echoed
+ * returns, and `Space.createCollection`'s create body -- so the paths cannot
+ * drift and a new writable member is added in one place.
  *
  * @param fields {CollectionWritableFields}
  * @returns {CollectionWritableFields}
@@ -35,28 +48,122 @@ export function collectionWritableFields(fields) {
     };
 }
 /**
- * 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).
+ * The members of a Collection Metadata object the server owns: it ignores them
+ * in a request body and re-derives them on every write, so a write never
+ * echoes them back. `id` is stated by the write path itself, `type` is the
+ * server's classification, and the rest are server-observed (the spec's
+ * "server-managed members are read-only" rule).
+ */
+const SERVER_MANAGED_MEMBERS = [
+    'id',
+    'type',
+    // Not a stored member at all: the client-side projection of the validator
+    // that `describe()` returns beside the object, which must not travel back.
+    'etag',
+    'url',
+    'linkset',
+    'createdAt',
+    'updatedAt',
+    'createdBy'
+];
+/**
+ * The Collection's configuration members: what a configuration write
+ * (`configure`, `replaceDescription`) states in full and an annotation write
+ * carries forward.
+ */
+export const CONFIGURATION_MEMBERS = [
+    'name',
+    'backend',
+    'encryption',
+    'generator',
+    'generatorOrigin'
+];
+/**
+ * The Collection's annotation members: the user-writable `custom` and the key
+ * epoch its envelope was sealed under. What an annotation write (`setMeta` and
+ * its sugar) states and a configuration write carries forward.
+ */
+export const ANNOTATION_MEMBERS = ['custom', 'epoch'];
+/**
+ * Reads a stored `encryption` descriptor at its wire type. The one place the
+ * open stored record is narrowed to `CollectionEncryption`, shared by the
+ * compose paths and the codec resolver so the assertion is not repeated.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @returns {CollectionEncryption | undefined}
+ */
+export function storedEncryption(stored) {
+    return stored.encryption;
+}
+/**
+ * Picks the stored members a full-replacement write carries forward: every
+ * member except the ones the server manages and the ones this write states
+ * itself. A denylist rather than an allowlist, so a member this client does
+ * not model -- `plaintext`, or one a newer server serves -- survives a write
+ * it is not about instead of being silently cleared.
+ *
+ * A governed `encryption` descriptor is deliberately dropped: on a
+ * log-governed Collection the served descriptor is the server's projection of
+ * the history log's head, and a write that carries it is refused
+ * (`encryption-history-log-governed`). Omitting the member leaves the derived
+ * descriptor in place.
+ *
+ * @param stored {StoredCollectionMetadata}
+ * @param options {object}
+ * @param options.replacing {readonly string[]}   the members this write states
+ *   itself (`CONFIGURATION_MEMBERS` on a configuration write,
+ *   `ANNOTATION_MEMBERS` on an annotation write)
+ * @returns {StoredCollectionMetadata}
+ */
+export function carriedForward(stored, { replacing }) {
+    const carried = {};
+    for (const [member, value] of Object.entries(stored)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (SERVER_MANAGED_MEMBERS.includes(member) || replacing.includes(member)) {
+            continue;
+        }
+        carried[member] = value;
+    }
+    const encryption = storedEncryption(stored);
+    if (encryption !== undefined && isGovernedDescriptor(encryption)) {
+        delete carried.encryption;
+    }
+    return carried;
+}
+/**
+ * Reads the Collection Metadata object with its `metaVersion` validator, in the
+ * stored wire form. Returns `null` if the collection is missing or not visible
+ * to you (WAS returns 404 for both not-found and unauthorized); `etag` is
+ * absent against a backend that does not version the object.
  *
  * @param context {ClientContext}
  * @param options {object}
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param [options.capability] {IZcap}   capability attached to the request
- * @returns {Promise<CollectionDescription | null>}
+ * @returns {Promise<{ metadata: StoredCollectionMetadata; etag?: string } | null>}
  */
-export async function describeCollection(context, options) {
-    return readData(context, {
-        path: collectionPath(options.spaceId, options.collectionId),
+export async function readCollectionMetadata(context, options) {
+    const read = await readDataWithEtag(context, {
+        path: collectionMeta(options.spaceId, options.collectionId),
         capability: options.capability
     });
+    if (read === null) {
+        return null;
+    }
+    return {
+        metadata: read.data,
+        ...(read.etag !== undefined && { etag: read.etag })
+    };
 }
 /**
- * Builds the fail-closed error for an operation that needs a description it
- * could not read. The one owner of the masked-404 policy statement ("WAS
- * returns 404 for both not-found and unauthorized, so a null description is
- * ambiguous -- fail closed"); callers supply the operation, its consequence,
- * and the recovery advice.
+ * Builds the fail-closed error for an operation that needs a Collection
+ * Metadata object it could not read. The one owner of the masked-404 policy
+ * statement ("WAS returns 404 for both not-found and unauthorized, so a null
+ * read is ambiguous -- fail closed"); callers supply the operation, its
+ * consequence, and the recovery advice.
  *
  * @param options {object}
  * @param options.operation {string}      what was refused, continuing "Cannot ..."

package/dist/internal/describe.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/internal/describe.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAS9C;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAgC;IAIhC,OAAO,UAAU,CAAC,OAAO,KAAK,SAAS,CAAA;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAgC;IAEhC,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QACvD,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAChE,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QACzE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QACtE,GAAG,CAAC,MAAM,CAAC,eAAe,KAAK,SAAS,IAAI;YAC1C,eAAe,EAAE,MAAM,CAAC,eAAe;SACxC,CAAC;KACH,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAsB,EACtB,OAAsE;IAEtE,OAAO,QAAQ,CAAwB,OAAO,EAAE;QAC9C,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC;QAC3D,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,GAAG,eAAe,EAM7B;IACC,OAAO,IAAI,UAAU,CACnB,UAAU,SAAS,sDAAsD;QACvE,kEAAkE;QAClE,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG;QACH,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7C,CAAA;AACH,CAAC"}
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/internal/describe.ts"],"names":[],"mappings":"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"}