@mdbase-dev/connect 0.1.0-beta.121 → 0.1.0-beta.123

package/dist/browser/mdbase-connect.min.js.sha384

@@ -1 +1 @@
-sha384-Nv0Du948fR/kSC/QXiny8mY1SZ2akUFBT7QmsPb3irgnUGNN0LgsWDubjxozn5cU
+sha384-oeF346B54GbocYns1w4tBu6zmyDtayo5iL/ujiP4qtf4pk1NsES2mMQj/0lIYmBb

package/dist/change-events.d.ts

@@ -0,0 +1,6 @@
+import { type CollectionChange as WireChange, type CollectionChangesPage as WirePage } from "@mdbase-dev/connect-protocol";
+import type { CollectionChange, CollectionChangesPage } from "./operation-types.js";
+/** Normalize authority events once, without inferring metadata missing on older authorities. */
+export declare function normalizeCollectionChange(raw: WireChange): CollectionChange;
+export declare function normalizeChangesPage(raw: WirePage): CollectionChangesPage;
+export declare function invalidatesDescription(change: CollectionChange): boolean;

package/dist/change-events.js

@@ -0,0 +1,102 @@
+import { CHANGE_EVENT_KINDS } from "@mdbase-dev/connect-protocol";
+import { clientFileDescriptor } from "./file-descriptor.js";
+const RECORD_FIELDS = Object.entries({
+    path: string, from: string, to: string, revision: string, previous_revision: string,
+    types: strings, previous_types: strings, changed_fields: strings, body_changed: boolean,
+    before: object, after: object
+});
+const RESOURCE_FIELDS = Object.entries({ path: string, name: string, revision: string, previous_revision: string, reason: string });
+const REMOVED_FILE_FIELDS = Object.entries({ previous_path: string, revision: string });
+/** Normalize authority events once, without inferring metadata missing on older authorities. */
+export function normalizeCollectionChange(raw) {
+    const base = { cursor: raw.cursor, type: raw.type, occurredAt: raw.occurred_at, payload: raw.payload, raw };
+    const unknown = (reason) => ({ ...base, kind: "unknown", reason });
+    const kind = Object.hasOwn(CHANGE_EVENT_KINDS, raw.type)
+        ? CHANGE_EVENT_KINDS[raw.type]
+        : undefined;
+    if (!kind)
+        return unknown("unrecognized_type");
+    const p = raw.payload;
+    if (!object(p))
+        return unknown("invalid_payload");
+    if (kind.startsWith("record.")) {
+        if (!validFields(p, RECORD_FIELDS))
+            return unknown("invalid_payload");
+        const data = p;
+        const metadata = {
+            ...(data.revision == null ? {} : { revision: data.revision }),
+            ...(data.previous_revision == null ? {} : { previousRevision: data.previous_revision }),
+            ...(data.types == null ? {} : { types: data.types }),
+            ...(data.previous_types == null ? {} : { previousTypes: data.previous_types }),
+            ...(data.changed_fields == null ? {} : { changedFields: data.changed_fields }),
+            ...(data.body_changed == null ? {} : { bodyChanged: data.body_changed }),
+            ...(data.before == null ? {} : { before: data.before }),
+            ...(data.after == null ? {} : { after: data.after })
+        };
+        if (kind === "record.renamed") {
+            return string(p.from) && string(p.to)
+                ? { ...base, ...metadata, kind, from: p.from, to: p.to }
+                : unknown("invalid_payload");
+        }
+        if (kind === "record.created" || kind === "record.updated" || kind === "record.deleted") {
+            return string(p.path) ? { ...base, ...metadata, kind, path: p.path } : unknown("invalid_payload");
+        }
+    }
+    if (kind === "file.put") {
+        return clientFileDescriptorIsValid(p.file)
+            ? { ...base, kind, file: clientFileDescriptor(p.file) }
+            : unknown("invalid_payload");
+    }
+    if (kind === "file.removed") {
+        if (!string(p.file_id) || !validFields(p, REMOVED_FILE_FIELDS))
+            return unknown("invalid_payload");
+        const data = p;
+        return { ...base, kind, fileId: p.file_id,
+            ...(data.previous_path == null ? {} : { previousPath: data.previous_path }),
+            ...(data.revision == null ? {} : { revision: data.revision }) };
+    }
+    if (!validFields(p, RESOURCE_FIELDS))
+        return unknown("invalid_payload");
+    const data = p;
+    if (kind === "gap")
+        return { ...base, kind, ...(data.reason == null ? {} : { reason: data.reason }) };
+    const metadata = {
+        ...(data.revision == null ? {} : { revision: data.revision }),
+        ...(data.previous_revision == null ? {} : { previousRevision: data.previous_revision })
+    };
+    if (kind === "file.changed")
+        return string(p.path) ? { ...base, ...metadata, kind, path: p.path } : unknown("invalid_payload");
+    if (kind === "schema.changed" || kind === "config.changed" || kind === "contract.changed" || kind === "view.changed") {
+        return { ...base, ...metadata, kind,
+            ...(data.path == null ? {} : { path: data.path }),
+            ...(data.name == null ? {} : { name: data.name }) };
+    }
+    throw new Error(`Unhandled change kind: ${kind}`);
+}
+export function normalizeChangesPage(raw) {
+    return {
+        events: raw.reset ? [{ kind: "reset", type: "reset", cursor: raw.cursor, occurredAt: null, payload: {}, raw }] : raw.events.map(normalizeCollectionChange),
+        cursor: raw.cursor,
+        hasMore: raw.has_more,
+        reset: raw.reset
+    };
+}
+export function invalidatesDescription(change) {
+    return change.kind === "schema.changed" || change.kind === "config.changed"
+        || change.kind === "contract.changed" || change.kind === "view.changed"
+        || change.kind === "gap" || change.kind === "reset" || change.kind === "unknown";
+}
+function string(value) { return typeof value === "string"; }
+function boolean(value) { return typeof value === "boolean"; }
+function strings(value) { return Array.isArray(value) && value.every(string); }
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function validFields(value, fields) {
+    return fields.every(([key, valid]) => value[key] == null || valid(value[key]));
+}
+function clientFileDescriptorIsValid(value) {
+    return object(value) && string(value.file_id) && string(value.path) && string(value.revision)
+        && string(value.content_digest) && value.content_digest.startsWith("sha256:")
+        && typeof value.size === "number" && Number.isSafeInteger(value.size) && value.size >= 0
+        && ["image", "audio", "video", "pdf", "other"].includes(value.media_class)
+        && string(value.modified_at) && (value.media_type == null || string(value.media_type));
+}

package/dist/collection-client.d.ts

@@ -1,6 +1,6 @@
 import type { CollectionOperation, CollectionTypeDocument, JsonObject } from "@mdbase-dev/connect-protocol";
 import { type CollectionChangesProblemCode, type CollectionDescriptionProblemCode, type CollectionMutationProblemCode, type CollectionQueryProblemCode, type CollectionReadProblemCode, type CollectionTypeProblemCode, type ConnectOutcome } from "./outcomes.js";
-import type { ChangesInput, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, AssessCollectionSetupInput, AssessTypePackInput, ApplyCollectionSetupInput, ApplyTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, WatchOptions } from "./operation-types.js";
+import type { ChangesInput, DescribeOptions, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, AssessCollectionSetupInput, AssessTypePackInput, ApplyCollectionSetupInput, ApplyTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseCollectionTransport, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadManyOptions, ReadManyResult, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, WatchOptions } from "./operation-types.js";
 /**
  * Typed collection operations independent of OAuth, HTTP, or storage.
  *
@@ -10,11 +10,16 @@ import type { ChangesInput, CollectionChange, CollectionChangesPage, CollectionD
 export declare class MdbaseCollectionClient<Frontmatter extends JsonObject = JsonObject> {
     private readonly transport;
     private readonly requestTimeoutMs;
+    private readonly descriptions;
+    private lastSchemaCursor;
+    /** Local cache generation, not an authority revision or cross-connection identity. */
+    get schemaGeneration(): number;
     constructor(transport: MdbaseCollectionTransport, requestTimeoutMs?: number | null);
     operation<Result>(operation: CollectionOperation, input: unknown, options?: ConnectRequestOptions): Promise<ConnectOutcome<Result>>;
-    describe(options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
+    describe(options?: DescribeOptions): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
     changes(input?: ChangesInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionChangesPage, CollectionChangesProblemCode>>;
     read(input: ReadInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionReadProblemCode>>;
+    readMany(paths: readonly string[], options?: ReadManyOptions): Promise<ConnectOutcome<ReadManyResult<Frontmatter>, CollectionQueryProblemCode>>;
     query(input?: QueryInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
     queryPages(input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter>, CollectionQueryProblemCode>>;
     queryAll(input?: QueryInput, options?: QueryAllOptions<Frontmatter>): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;

package/dist/collection-client.js

@@ -1,8 +1,11 @@
 import { abortableDelay } from "./async.js";
+import { invalidatesDescription, normalizeChangesPage } from "./change-events.js";
+import { CollectionDescriptionCache } from "./description-cache.js";
 import { coordinatedQueryPages } from "./query-pagination.js";
+import { queryReadMany } from "./read-many.js";
 import { coordinatedSavedViewPages } from "./saved-view-pagination.js";
 import { MdbaseConnectError, connectError, connectProblem, operationProblem } from "./errors.js";
-import { COLLECTION_CHANGES_PROBLEM_CODES, COLLECTION_DESCRIPTION_PROBLEM_CODES, COLLECTION_MUTATION_PROBLEM_CODES, COLLECTION_QUERY_PROBLEM_CODES, COLLECTION_READ_PROBLEM_CODES, COLLECTION_TYPE_PROBLEM_CODES, ALL_CONNECT_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
+import { COLLECTION_CHANGES_PROBLEM_CODES, COLLECTION_MUTATION_PROBLEM_CODES, COLLECTION_QUERY_PROBLEM_CODES, COLLECTION_READ_PROBLEM_CODES, COLLECTION_TYPE_PROBLEM_CODES, ALL_CONNECT_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
 import { createRequestBudget, DEFAULT_REQUEST_TIMEOUT_MS, requestAbortReason } from "./request-budget.js";
 import { watchRetryPolicy } from "./watch-policy.js";
 /**
@@ -14,25 +17,40 @@ import { watchRetryPolicy } from "./watch-policy.js";
 export class MdbaseCollectionClient {
     transport;
     requestTimeoutMs;
+    descriptions;
+    lastSchemaCursor = -1;
+    /** Local cache generation, not an authority revision or cross-connection identity. */
+    get schemaGeneration() { return this.descriptions.schemaGeneration; }
     constructor(transport, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
         this.transport = transport;
         this.requestTimeoutMs = requestTimeoutMs;
+        this.descriptions = new CollectionDescriptionCache(transport, requestTimeoutMs);
     }
     operation(operation, input, options) {
         return captureConnectOutcome(() => this.transport.operation(operation, input, options), ALL_CONNECT_PROBLEM_CODES);
     }
-    async describe(options) {
-        const outcome = await this.rawOperation("describe", {}, COLLECTION_DESCRIPTION_PROBLEM_CODES, options);
-        return mapOutcome(outcome, wireCollectionDescription);
+    describe(options) {
+        return this.descriptions.describe(options);
     }
     async changes(input = {}, options) {
         const outcome = await this.rawOperation("changes", input, COLLECTION_CHANGES_PROBLEM_CODES, options);
-        return mapOutcome(outcome, wireChangesPage);
+        const mapped = mapOutcome(outcome, normalizeChangesPage);
+        if (mapped.ok) {
+            const invalidations = mapped.value.events.filter(invalidatesDescription);
+            if (mapped.value.reset || invalidations.some((event) => event.cursor > this.lastSchemaCursor)) {
+                this.descriptions.invalidate();
+                this.lastSchemaCursor = mapped.value.cursor;
+            }
+        }
+        return mapped;
     }
     async read(input, options) {
         const outcome = await this.envelopeOperation("read", wireReadInput(input), COLLECTION_READ_PROBLEM_CODES, options);
         return mapOutcome(outcome, wireRecordDocument);
     }
+    readMany(paths, options = {}) {
+        return queryReadMany((input, requestOptions) => this.queryAll(input, requestOptions), paths, options, this.requestTimeoutMs);
+    }
     async query(input = {}, options) {
         const outcome = await this.envelopeOperation("query", wireQueryInput(input), COLLECTION_QUERY_PROBLEM_CODES, options);
         return mapOutcome(outcome, ({ results, meta }) => ({
@@ -62,6 +80,7 @@ export class MdbaseCollectionClient {
             for await (const outcome of this.queryPages(input, {
                 firstPageSize: options.firstPageSize,
                 pageSize: options.pageSize,
+                maxResults: options.maxResults,
                 signal: budget.signal,
                 pageTimeoutMs: null,
                 coordination: options.coordination,
@@ -78,11 +97,14 @@ export class MdbaseCollectionClient {
                 throw requestAbortReason(budget.signal);
             return connectSuccess({
                 results,
-                meta: {
-                    totalCount: finalPage?.meta?.totalCount ?? results.length,
-                    hasMore: finalPage ? !finalPage.complete : false,
-                    ...(finalPage?.snapshot ? { snapshot: finalPage.snapshot } : {})
-                }
+                ...(finalPage ? { meta: {
+                        ...(finalPage.meta?.totalCount === undefined
+                            ? (!finalPage.meta?.hasMore ? { totalCount: results.length } : {})
+                            : { totalCount: finalPage.meta.totalCount }),
+                        ...(finalPage.meta?.hasMore && finalPage.meta.totalCountOutcome ? { totalCountOutcome: finalPage.meta.totalCountOutcome } : {}),
+                        hasMore: finalPage.meta?.hasMore ?? false,
+                        ...(finalPage.snapshot ? { snapshot: finalPage.snapshot } : {})
+                    } } : {})
             }, diagnostics);
         }
         catch (error) {
@@ -299,6 +321,9 @@ export class MdbaseCollectionClient {
         if (!envelope.valid) {
             return connectFailure(operationProblem(envelope));
         }
+        if (["create_type", "update_type", "apply_type_pack", "apply_collection_setup", "create_view_source", "update_view_source", "delete_view_source"].includes(operation)) {
+            this.descriptions.invalidate();
+        }
         return connectSuccess(envelope.result, envelope.diagnostics);
     }
 }
@@ -635,47 +660,3 @@ function wireCollectionSetupReceipt(value) {
         cleanupDeferred: value.cleanup_deferred
     };
 }
-function wireChange(value) {
-    return {
-        cursor: value.cursor,
-        type: value.type,
-        occurredAt: value.occurred_at,
-        payload: value.payload
-    };
-}
-function wireChangesPage(value) {
-    return {
-        events: value.events.map(wireChange),
-        cursor: value.cursor,
-        hasMore: value.has_more,
-        reset: value.reset
-    };
-}
-function wireCollectionDescription(value) {
-    return {
-        protocolVersion: value.protocol_version,
-        collectionId: value.collection_id,
-        displayName: value.display_name,
-        specVersion: value.spec_version,
-        operations: value.operations,
-        changeCursor: value.change_cursor,
-        types: value.types,
-        contracts: value.contracts.map((contract) => ({
-            contractType: contract.contract_type,
-            id: contract.id,
-            version: contract.version,
-            digest: contract.digest,
-            schema: contract.schema,
-            ...(contract.binding_schema ? { bindingSchema: contract.binding_schema } : {}),
-            implementations: contract.implementations.map((implementation) => ({
-                typeName: implementation.type_name,
-                typeVersion: implementation.type_version,
-                ...(implementation.type_path ? { typePath: implementation.type_path } : {}),
-                digest: implementation.digest,
-                fields: implementation.fields,
-                ...(implementation.binding ? { binding: implementation.binding } : {})
-            }))
-        })),
-        ...(value.configuration ? { configuration: value.configuration } : {})
-    };
-}

package/dist/connection.d.ts

@@ -1,6 +1,7 @@
 import { MdbasePeopleClient } from "./people-client.js";
 import type { CollectionOperation, CollectionTypeDocument, FileCapability, GrantScope, JsonObject } from "@mdbase-dev/connect-protocol";
 import { type MdbaseApplicationCapabilityId as ApplicationCapabilityId } from "./application-contract.js";
+import { MdbaseCollectionClient } from "./collection-client.js";
 import { type ConnectionTransportInternals } from "./connection-transport.js";
 import type { DirectAccessStatus, MdbaseAuthorizationCapabilities, MdbaseConnectionInfo, MdbaseConnectionRoute, MdbaseSyncConnection } from "./connection-types.js";
 import type { GrantKeyStore } from "./crypto.js";
@@ -8,7 +9,7 @@ import { MdbaseFileClient } from "./files.js";
 import { MdbaseRecords } from "./records.js";
 import { type Application } from "./internal-types.js";
 import type { MdbaseNativeNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNotificationRegistrationOptions } from "./notifications.js";
-import type { ChangesInput, CollectionChangesPage, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, ApplyCollectionSetupInput, ApplyTypePackInput, AssessCollectionSetupInput, AssessTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteProgressOptions, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, PendingMutation, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameProgressOptions, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, MdbaseWatchSubscription, WatchInput } from "./operation-types.js";
+import type { ChangesInput, CollectionChangesPage, DescribeOptions, CollectionDescription, CollectionSetupApplyResult, CollectionSetupAssessment, ApplyCollectionSetupInput, ApplyTypePackInput, AssessCollectionSetupInput, AssessTypePackInput, CreateInput, CreateTypeInput, CreateViewSourceInput, DeleteInput, DeletePreflightResult, DeleteProgressOptions, DeleteResult, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ConnectRequestOptions, PendingMutation, QueryAllOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult, ReadInput, ReadTypeInput, ReadViewSourceInput, RenameInput, RenamePreflightResult, RenameProgressOptions, RenameResult, RecordDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, SavedViewList, SavedViewSourceDocument, TypePackApplyResult, TypePackAssessment, UpdateInput, UpdateTypeInput, UpdateViewSourceInput, MdbaseWatchSubscription, WatchInput } from "./operation-types.js";
 import { type AuthorizationProblemCode, type CollectionChangesProblemCode, type CollectionDescriptionProblemCode, type CollectionMutationProblemCode, type CollectionQueryProblemCode, type CollectionReadProblemCode, type CollectionTypeProblemCode, type ConnectOutcome, type DirectAccessProblemCode, type NotificationProblemCode, type RegistrationProblemCode } from "./outcomes.js";
 import type { MdbaseDeviceAuthorization } from "./connection-types.js";
 import { type ResolvedConnectTimeouts } from "./request-budget.js";
@@ -79,6 +80,7 @@ export declare class MdbaseConnection<Frontmatter extends JsonObject = JsonObjec
     /** Editable record sessions shared by every view of this connection. */
     readonly records: MdbaseRecords<Frontmatter>;
     readonly people: MdbasePeopleClient;
+    readonly readMany: MdbaseCollectionClient<Frontmatter>["readMany"];
     private readonly connectionListeners;
     constructor(internals: MdbaseConnectionInternals<Frontmatter>, collectionId: string);
     get displayName(): string;
@@ -123,7 +125,8 @@ export declare class MdbaseConnection<Frontmatter extends JsonObject = JsonObjec
     unregisterNativeNotifications(options?: ConnectRequestOptions): Promise<ConnectOutcome<void, NotificationProblemCode>>;
     unregisterNotifications(serviceWorker?: ServiceWorkerRegistration, options?: ConnectRequestOptions): Promise<ConnectOutcome<void, NotificationProblemCode>>;
     forget(): void;
-    describe(options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
+    get schemaGeneration(): number;
+    describe(options?: DescribeOptions): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
     changes(input?: ChangesInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionChangesPage, CollectionChangesProblemCode>>;
     read(input: ReadInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<RecordDocument<Frontmatter>, CollectionReadProblemCode>>;
     query(input?: QueryInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;

package/dist/connection.js

@@ -22,6 +22,7 @@ export class MdbaseConnection {
     /** Editable record sessions shared by every view of this connection. */
     records;
     people;
+    readMany;
     connectionListeners = new Set();
     constructor(internals, collectionId) {
         this.internals = internals;
@@ -55,6 +56,7 @@ export class MdbaseConnection {
         this.collectionClient = new MdbaseCollectionClient(new CollectionRequestCoordinator({
             operation: (operation, input, requestOptions) => this.transport.performOperation(operation, input, requestOptions)
         }, internals.timeouts.requestMs), internals.timeouts.requestMs);
+        this.readMany = this.collectionClient.readMany.bind(this.collectionClient);
         this.notifications = new ConnectionNotifications({
             serverUrl: internals.serverUrl,
             storage: internals.storage,
@@ -254,9 +256,8 @@ export class MdbaseConnection {
         this.internals.removeToken(this.collectionId, token?.keyHandle, "not_authorized", true);
         this.transport.notifyStorageChanged();
     }
-    describe(options) {
-        return this.collectionClient.describe(options);
-    }
+    get schemaGeneration() { return this.collectionClient.schemaGeneration; }
+    describe(options) { return this.collectionClient.describe(options); }
     changes(input = {}, options) {
         return this.collectionClient.changes(input, options);
     }

package/dist/description-cache.d.ts

@@ -0,0 +1,14 @@
+import type { CollectionDescription, DescribeOptions, MdbaseCollectionTransport } from "./operation-types.js";
+import { type CollectionDescriptionProblemCode, type ConnectOutcome } from "./outcomes.js";
+/** One collection's description lifecycle; no background observer or persisted schema state. */
+export declare class CollectionDescriptionCache {
+    private readonly transport;
+    private readonly requestTimeoutMs;
+    private generation;
+    private description?;
+    private describing?;
+    constructor(transport: MdbaseCollectionTransport, requestTimeoutMs: number | null);
+    get schemaGeneration(): number;
+    invalidate(): void;
+    describe(options?: DescribeOptions): Promise<ConnectOutcome<CollectionDescription, CollectionDescriptionProblemCode>>;
+}

package/dist/description-cache.js

@@ -0,0 +1,73 @@
+import { COLLECTION_DESCRIPTION_PROBLEM_CODES, captureConnectOutcome, connectSuccess } from "./outcomes.js";
+import { withRequestBudget } from "./request-budget.js";
+/** One collection's description lifecycle; no background observer or persisted schema state. */
+export class CollectionDescriptionCache {
+    transport;
+    requestTimeoutMs;
+    generation = 0;
+    description;
+    describing;
+    constructor(transport, requestTimeoutMs) {
+        this.transport = transport;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    get schemaGeneration() { return this.generation; }
+    invalidate() {
+        this.generation += 1;
+        this.description = undefined;
+        this.describing = undefined;
+    }
+    describe(options = {}) {
+        return captureConnectOutcome(() => withRequestBudget(options, this.requestTimeoutMs, async () => {
+            if (!options.fresh && this.description && Date.now() < this.description.expiresAt) {
+                return connectSuccess(this.description.value);
+            }
+            if (!this.describing) {
+                this.description = undefined;
+                const generation = this.generation;
+                // The shared load has its own budget. Cancelling one waiter cannot cancel another.
+                const request = captureConnectOutcome(() => withRequestBudget({}, this.requestTimeoutMs, (budget) => this.transport.operation("describe", {}, { signal: budget.signal, timeoutMs: this.requestTimeoutMs })), COLLECTION_DESCRIPTION_PROBLEM_CODES).then((outcome) => {
+                    if (!outcome.ok)
+                        return outcome;
+                    const value = wireCollectionDescription(outcome.value);
+                    if (this.generation === generation)
+                        this.description = { value, expiresAt: Date.now() + 60_000 };
+                    return connectSuccess(value, outcome.diagnostics);
+                }).finally(() => {
+                    if (this.describing === request)
+                        this.describing = undefined;
+                });
+                this.describing = request;
+            }
+            return this.describing;
+        }), COLLECTION_DESCRIPTION_PROBLEM_CODES).then((outcome) => outcome.ok ? outcome.value : outcome);
+    }
+}
+function wireCollectionDescription(value) {
+    return {
+        protocolVersion: value.protocol_version,
+        collectionId: value.collection_id,
+        displayName: value.display_name,
+        specVersion: value.spec_version,
+        operations: value.operations,
+        changeCursor: value.change_cursor,
+        types: value.types,
+        contracts: value.contracts.map((contract) => ({
+            contractType: contract.contract_type,
+            id: contract.id,
+            version: contract.version,
+            digest: contract.digest,
+            schema: contract.schema,
+            ...(contract.binding_schema ? { bindingSchema: contract.binding_schema } : {}),
+            implementations: contract.implementations.map((implementation) => ({
+                typeName: implementation.type_name,
+                typeVersion: implementation.type_version,
+                ...(implementation.type_path ? { typePath: implementation.type_path } : {}),
+                digest: implementation.digest,
+                fields: implementation.fields,
+                ...(implementation.binding ? { binding: implementation.binding } : {})
+            }))
+        })),
+        ...(value.configuration ? { configuration: value.configuration } : {})
+    };
+}

package/dist/file-crypto.js

@@ -42,9 +42,9 @@ export class GrantFileTransferCipher {
         const payload = await crypto.subtle.encrypt({
             name: "AES-GCM",
             iv: chunkNonce(header.chunk_index),
-            additionalData: arrayBuffer(authenticatedData),
+            additionalData: webCryptoBytes(authenticatedData),
             tagLength: 128
-        }, this.key, arrayBuffer(plaintext));
+        }, this.key, webCryptoBytes(plaintext));
         return encodeFileFrame({ kind, header, payload: new Uint8Array(payload) });
     }
     async decryptChunk(encoded) {
@@ -55,9 +55,9 @@ export class GrantFileTransferCipher {
             const plaintext = await crypto.subtle.decrypt({
                 name: "AES-GCM",
                 iv: chunkNonce(frame.header.chunk_index),
-                additionalData: arrayBuffer(authenticatedData),
+                additionalData: webCryptoBytes(authenticatedData),
                 tagLength: 128
-            }, this.key, arrayBuffer(frame.payload));
+            }, this.key, webCryptoBytes(frame.payload));
             return new Uint8Array(plaintext);
         }
         catch {
@@ -127,6 +127,10 @@ function chunkNonce(index) {
     new DataView(nonce.buffer).setBigUint64(4, BigInt(index), false);
     return nonce;
 }
-function arrayBuffer(bytes) {
-    return Uint8Array.from(bytes).buffer;
+function webCryptoBytes(bytes) {
+    // WebCrypto snapshots BufferSource synchronously, including the view bounds.
+    // SharedArrayBuffer is not a valid BufferSource and still needs an owned copy.
+    return bytes.buffer instanceof ArrayBuffer
+        ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+        : Uint8Array.from(bytes);
 }

package/dist/file-descriptor.d.ts

@@ -0,0 +1,12 @@
+import type { CollectionFileDescriptor as WireFile } from "@mdbase-dev/connect-protocol";
+export interface CollectionFileDescriptor {
+    fileId: string;
+    path: string;
+    revision: string;
+    contentDigest: `sha256:${string}`;
+    size: number;
+    mediaType?: string;
+    mediaClass: import("@mdbase-dev/connect-protocol").FileMediaClass;
+    modifiedAt: string;
+}
+export declare function clientFileDescriptor(file: WireFile): CollectionFileDescriptor;

package/dist/file-descriptor.js

@@ -0,0 +1,12 @@
+export function clientFileDescriptor(file) {
+    return {
+        fileId: file.file_id,
+        path: file.path,
+        revision: file.revision,
+        contentDigest: file.content_digest,
+        size: file.size,
+        ...(file.media_type ? { mediaType: file.media_type } : {}),
+        mediaClass: file.media_class,
+        modifiedAt: file.modified_at
+    };
+}

package/dist/file-sha256.js

@@ -53,7 +53,7 @@ export class IncrementalSha256 {
             }
         }
         while (offset + 64 <= input.byteLength) {
-            this.compress(input.subarray(offset, offset + 64));
+            this.compress(input, offset);
             offset += 64;
         }
         if (offset < input.byteLength) {
@@ -82,10 +82,10 @@ export class IncrementalSha256 {
             .map((word) => word.toString(16).padStart(8, "0"))
             .join("");
     }
-    compress(block) {
+    compress(block, blockOffset = 0) {
         const words = this.words;
         for (let index = 0; index < 16; index += 1) {
-            const offset = index * 4;
+            const offset = blockOffset + index * 4;
             words[index] = ((block[offset] << 24)
                 | (block[offset + 1] << 16)
                 | (block[offset + 2] << 8)

package/dist/files.d.ts

@@ -1,18 +1,10 @@
+import { type CollectionFileDescriptor } from "./file-descriptor.js";
+export type { CollectionFileDescriptor } from "./file-descriptor.js";
 import type { FileCapability, FileTransferSession } from "@mdbase-dev/connect-protocol";
 import { type FileSource } from "./file-transfer-internals.js";
 import type { ConnectRequestOptions } from "./operation-types.js";
 import { type ResolvedConnectTimeouts } from "./request-budget.js";
 export type MdbaseFileSource = FileSource;
-export interface CollectionFileDescriptor {
-    fileId: string;
-    path: string;
-    revision: string;
-    contentDigest: `sha256:${string}`;
-    size: number;
-    mediaType?: string;
-    mediaClass: import("@mdbase-dev/connect-protocol").FileMediaClass;
-    modifiedAt: string;
-}
 export interface MdbaseFileDeleteReceipt {
     protocolVersion: 1;
     type: "file_deleted";
@@ -112,4 +104,3 @@ export declare class MdbaseFileClient {
     private requireAction;
     private abort;
 }
-export {};

package/dist/files.js

@@ -1,3 +1,4 @@
+import { clientFileDescriptor } from "./file-descriptor.js";
 import { FILE_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
 import { abortableDelay } from "./async.js";
 import { MdbaseConnectError, connectError } from "./errors.js";
@@ -220,23 +221,9 @@ export class MdbaseFileClient {
         }
     }
     async download(file, options = {}) {
-        if (file.size > MAX_BUFFERED_DOWNLOAD_BYTES) {
-            throw connectError("invalid_request", `download() buffers at most ${MAX_BUFFERED_DOWNLOAD_BYTES} bytes; use downloadStream() for larger files.`);
-        }
-        const stream = await this.downloadStream(file, options);
-        const chunks = [];
-        const reader = stream.getReader();
-        while (true) {
-            const result = await reader.read();
-            if (result.done)
-                break;
-            chunks.push(result.value);
-        }
-        return new Blob(chunks.map((chunk) => {
-            const copy = new Uint8Array(chunk.byteLength);
-            copy.set(chunk);
-            return copy.buffer;
-        }), { type: file.mediaType ?? "" });
+        const bytes = await this.downloadBytes(file, options);
+        // downloadBytes owns a full, non-shared ArrayBuffer; Blob snapshots it.
+        return new Blob([bytes.buffer], { type: file.mediaType ?? "" });
     }
     /** Download and verify a file with network backpressure and bounded buffering. */
     async downloadStream(file, options = {}) {
@@ -416,7 +403,38 @@ export class MdbaseFileClient {
         });
     }
     async downloadBytes(file, options = {}) {
-        return new Uint8Array(await (await this.download(file, options)).arrayBuffer());
+        if (file.size > MAX_BUFFERED_DOWNLOAD_BYTES) {
+            throw connectError("invalid_request", `download() buffers at most ${MAX_BUFFERED_DOWNLOAD_BYTES} bytes; use downloadStream() for larger files.`);
+        }
+        const stream = await this.downloadStream(file, options);
+        const bytes = new Uint8Array(file.size);
+        const reader = stream.getReader();
+        let offset = 0;
+        try {
+            while (true) {
+                const result = await reader.read();
+                // Reading through EOF is essential: hosted streams verify their digest
+                // only after the final range ends, not when the last bytes arrive.
+                if (result.done)
+                    break;
+                if (result.value.byteLength > bytes.byteLength - offset) {
+                    throw connectError("invalid_operation_response", "Downloaded file bytes failed integrity verification.");
+                }
+                bytes.set(result.value, offset);
+                offset += result.value.byteLength;
+            }
+            if (offset !== bytes.byteLength) {
+                throw connectError("invalid_operation_response", "Downloaded file bytes failed integrity verification.");
+            }
+            return bytes;
+        }
+        catch (error) {
+            await reader.cancel().catch(() => undefined);
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
     }
     async move(file, path, options = {}) {
         return withCooperativeRequestBudget(options, this.timeouts.requestMs, (budget) => this.moveWithinBudget(file, path, { ...options, signal: budget.signal, timeoutMs: null }));
@@ -585,15 +603,3 @@ export class MdbaseFileClient {
         await this.request("DELETE", `transfers/${encodeURIComponent(transferId)}`).catch(() => undefined);
     }
 }
-function clientFileDescriptor(file) {
-    return {
-        fileId: file.file_id,
-        path: file.path,
-        revision: file.revision,
-        contentDigest: file.content_digest,
-        size: file.size,
-        ...(file.media_type ? { mediaType: file.media_type } : {}),
-        mediaClass: file.media_class,
-        modifiedAt: file.modified_at
-    };
-}