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

package/dist/files.js

@@ -1,10 +1,12 @@
+import { clientFileDescriptor } from "./file-descriptor.js";
 import { FILE_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
-import { abortableDelay } from "./async.js";
+import { listFiles, statFile } from "./file-metadata.js";
+import { connectSuccess } from "./outcomes.js";
 import { MdbaseConnectError, connectError } from "./errors.js";
 import { IncrementalSha256 } from "./file-sha256.js";
 import { BinaryPartReader } from "./file-stream-source.js";
-import { MAX_BUFFERED_DOWNLOAD_BYTES, MAX_OBJECT_ATTEMPTS, SHA256_DIGEST, UUID, browserObjectHeaders, chunkLength, hashBlob, mapConcurrent, normalizeFileError, requirePreparedPart, requireTransferSession, requireTransferStatus, retryChunk, sourceBlob, throwIfAborted, uploadBodyBytes, uploadBodyLength, validConcurrency, validPageSize } from "./file-transfer-internals.js";
-import { createRequestBudget, resolveConnectTimeouts, withCooperativeRequestBudget } from "./request-budget.js";
+import { MAX_BUFFERED_DOWNLOAD_BYTES, MAX_OBJECT_ATTEMPTS, SHA256_DIGEST, UUID, browserObjectHeaders, chunkLength, hashBlob, mapConcurrent, normalizeFileError, requirePreparedPart, requireTransferSession, requireTransferStatus, retryChunk, sourceBlob, throwIfAborted, uploadBodyBytes, uploadBodyLength, validConcurrency } from "./file-transfer-internals.js";
+import { resolveConnectTimeouts, withCooperativeRequestBudget } from "./request-budget.js";
 /** Ergonomic facade over resumable, authority-specific file delivery. */
 export class MdbaseFileClient {
     capability;
@@ -12,54 +14,21 @@ export class MdbaseFileClient {
     framed;
     hosted;
     timeouts;
-    constructor(capability, request, framed, hosted, timeouts = resolveConnectTimeouts()) {
+    supportsAuthorityFeature;
+    constructor(capability, request, framed, hosted, timeouts = resolveConnectTimeouts(), supportsAuthorityFeature = async () => connectSuccess(false)) {
         this.capability = capability;
         this.request = request;
         this.framed = framed;
         this.hosted = hosted;
         this.timeouts = timeouts;
+        this.supportsAuthorityFeature = supportsAuthorityFeature;
     }
-    async *list(options = {}) {
-        const budget = createRequestBudget(options, this.timeouts.fileIndexMs);
-        const signal = budget.signal;
-        try {
-            this.requireAction("list");
-            let after;
-            do {
-                throwIfAborted(signal);
-                const query = new URLSearchParams({
-                    protocol_version: String(FILE_PROTOCOL_VERSION),
-                    ...(options.folder ? { folder: options.folder } : {}),
-                    ...(after ? { after } : {}),
-                    ...(options.pageSize ? { limit: String(validPageSize(options.pageSize)) } : {})
-                });
-                let page;
-                while (true) {
-                    try {
-                        page = await this.request("GET", `?${query.toString()}`, undefined, signal);
-                        break;
-                    }
-                    catch (error) {
-                        const normalized = normalizeFileError(error);
-                        if (normalized.code !== "file_index_warming")
-                            throw normalized;
-                        options.onIndexing?.();
-                        await abortableDelay(500, signal);
-                    }
-                }
-                if (page.protocol_version !== 1 || page.type !== "files_page" || !Array.isArray(page.files)) {
-                    throw connectError("invalid_operation_response", "The authority returned an invalid file page.");
-                }
-                for (const file of page.files) {
-                    throwIfAborted(signal);
-                    yield clientFileDescriptor(file);
-                }
-                after = page.next;
-            } while (after);
-        }
-        finally {
-            budget.dispose();
-        }
+    list(options = {}) {
+        return listFiles(this.capability, this.request, options, this.timeouts.fileIndexMs);
+    }
+    /** Current metadata lookup; requires file list approval, not file byte access. */
+    stat(target, options = {}) {
+        return statFile(this.capability, this.request, this.supportsAuthorityFeature, options => this.list(options), target, options, this.timeouts.fileIndexMs);
     }
     async upload(path, source, options = {}) {
         return withCooperativeRequestBudget(options, this.timeouts.uploadMs, (budget) => this.uploadWithinBudget(path, source, { ...options, signal: budget.signal, timeoutMs: null }));
@@ -220,23 +189,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 +371,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 +571,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
-    };
-}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export type { MdbaseApplicationSessionOptions, MdbaseApplicationVerificationStore, MdbaseDefinitionUpdate, MdbaseCollectionSetupUpdate, MdbaseApplicationSessionSnapshot } from "./application-session.js";
 export type { MdbaseConnectOptions, MdbaseConnectTimeouts, MdbaseFrontmatter } from "./connect-options.js";
@@ -18,11 +19,13 @@ export type { MdbaseRecordResolution, MdbaseRecordSessionOptions, MdbaseRecordSe
 export { MdbasePeopleClient, PERSON_CONTRACT, sameIdentity } from "./people-client.js";
 export type { CurrentAccount, InvalidPersonRecord, PeopleDirectory, PeopleDirectoryOptions, PersonRecord, PersonResolution } from "./people-client.js";
 export type { AccountIdentity, AccountProfile, CollectionMemberProfile, ApplicationPeopleRequirement, PeoplePermission } from "@mdbase-dev/connect-protocol";
-export type { MdbaseFileSource, CollectionFileDescriptor, MdbaseFileDeleteReceipt, MdbaseFileStreamSource, MdbaseFileProgress, MdbaseFileListOptions, MdbaseFileUploadOptions, MdbaseFileStreamUploadOptions, MdbaseFileDownloadOptions, MdbaseFileMoveOptions, MdbaseFileDeleteOptions } from "./files.js";
+export type { MdbaseFileSource, CollectionFileDescriptor, MdbaseFileDeleteReceipt, MdbaseFileStreamSource, MdbaseFileProgress, MdbaseFileListOptions, MdbaseFileStatTarget, MdbaseFileUploadOptions, MdbaseFileStreamUploadOptions, MdbaseFileDownloadOptions, MdbaseFileMoveOptions, MdbaseFileDeleteOptions } from "./files.js";
 export { parseMdbasePushPayload, parseMdbaseNativeNotificationData, showMdbasePushNotification } from "./notifications.js";
 export type { MdbaseNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNativeNotificationRegistration, MdbaseNativeNotificationData, MdbasePushPayload } from "./notifications.js";
 export type { ConnectSuccess, ConnectFailure, ConnectOutcome, CommonOperationProblemCode, RegistrationProblemCode, AuthorizationProblemCode, NotificationProblemCode, DirectAccessProblemCode, SessionProblemCode, CollectionSetupProblemCode, CollectionDescriptionProblemCode, CollectionReadProblemCode, CollectionQueryProblemCode, CollectionMutationProblemCode, CollectionChangesProblemCode, CollectionTypeProblemCode } from "./outcomes.js";
-export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
+export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, ReadManyOptions, ReadManyRecord, ReadManyEntry, ReadManyBatchError, ReadManyResult, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryMetadataInput, QueryMetadataRecord, QueryMetadataResult, QueryMetadataPage, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, RecordChangeMetadata, DescribeOptions, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
+export { linksTo } from "./query-predicates.js";
+export type { LinksToOptions } from "./query-predicates.js";
 export { externalStore } from "./external-store.js";
 export type { MdbaseExternalStore } from "./external-store.js";
 export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export { MdbaseConnect } from "./mdbase-connect.js";
 export { MdbaseConnection } from "./connection.js";
@@ -8,6 +9,7 @@ export { MdbaseRecords } from "./records.js";
 export { MdbaseRecordSession } from "./record-session.js";
 export { MdbasePeopleClient, PERSON_CONTRACT, sameIdentity } from "./people-client.js";
 export { parseMdbasePushPayload, parseMdbaseNativeNotificationData, showMdbasePushNotification } from "./notifications.js";
+export { linksTo } from "./query-predicates.js";
 export { externalStore } from "./external-store.js";
 export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";
 export { MDBASE_RECORD_CREATED_CONTRACT, MDBASE_TIMER_FIRED_CONTRACT, operationsForApplicationCapabilities } from "@mdbase-dev/connect-protocol";

package/dist/local-file-transport.js

@@ -1,4 +1,4 @@
-import { decodeFileFrame, FILE_PROTOCOL_VERSION, FILE_TRANSFER_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
+import { decodeFileFrame, isMutatingOperation, FILE_PROTOCOL_VERSION, FILE_TRANSFER_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
 import { decryptRelayResponse, encryptRelayRequest } from "./crypto.js";
 import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
 import { GrantFileTransferCipher } from "./file-crypto.js";
@@ -51,7 +51,7 @@ export class LocalFileTransport {
             if (response)
                 this.options.onDirectUnavailable();
         }
-        if (triedDirect && method === "GET") {
+        if (triedDirect && !isMutatingOperation("file_control", controlInput)) {
             token = token.expiresAt > Date.now() + 30_000
                 ? token
                 : await this.options.refreshAuthorization(signal);
@@ -81,7 +81,7 @@ export class LocalFileTransport {
                 return this.controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries + 1, leases);
             }
             if (error.code === "fresh_request_required"
-                && method === "GET"
+                && !isMutatingOperation("file_control", localFileControlInput(method, path, input))
                 && !freshReadRetried) {
                 return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries, leases);
             }
@@ -94,7 +94,7 @@ export class LocalFileTransport {
         const decrypted = await decryptRelayResponse(this.options.keyStore, token.keyHandle, relayBinding(token), encryptedRequest, encryptedResponse);
         if (!decrypted.ok
             && decrypted.problem.code === "fresh_request_required"
-            && method === "GET"
+            && !isMutatingOperation("file_control", localFileControlInput(method, path, input))
             && !freshReadRetried) {
             return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries, leases);
         }
@@ -407,19 +407,21 @@ function localFileControlInput(method, path, input) {
         return transferControl("abort_file_transfer", segments[1]);
     }
     if (method === "POST" && isRecord(input)) {
-        const expectedType = path === "uploads"
-            ? "open_file_upload"
-            : path === "downloads"
-                ? "open_file_download"
-                : segments.length === 3 && segments[0] === "uploads" && segments[2] === "commit"
-                    ? "commit_file_upload"
-                    : segments.length === 2 && segments[1] === "move"
-                        && input.file_id === decodeURIComponent(segments[0])
-                        ? "move_file"
-                        : segments.length === 2 && segments[1] === "delete"
+        const expectedType = path === "stat"
+            ? "stat_file"
+            : path === "uploads"
+                ? "open_file_upload"
+                : path === "downloads"
+                    ? "open_file_download"
+                    : segments.length === 3 && segments[0] === "uploads" && segments[2] === "commit"
+                        ? "commit_file_upload"
+                        : segments.length === 2 && segments[1] === "move"
                             && input.file_id === decodeURIComponent(segments[0])
-                            ? "delete_file"
-                            : null;
+                            ? "move_file"
+                            : segments.length === 2 && segments[1] === "delete"
+                                && input.file_id === decodeURIComponent(segments[0])
+                                ? "delete_file"
+                                : null;
         if (expectedType && input.type === expectedType)
             return { ...input };
     }

package/dist/operation-types.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionOperation, ConnectProblem, ContractRequirement, JsonObject, MutationOperationIdentifier, TypePackProvision } from "@mdbase-dev/connect-protocol";
+import type { CollectionChange as WireCollectionChange, CollectionChangesPage as WireCollectionChangesPage, CollectionOperation, ConnectProblem, ContractRequirement, JsonObject, MutationOperationIdentifier, TypePackProvision } from "@mdbase-dev/connect-protocol";
 export interface MdbaseDesiredTimer {
     /** Stable within the timer namespace. */
     id: string;
@@ -53,6 +53,8 @@ export interface DataContractViewIdentity {
 }
 export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
     path: string;
+    /** Exact-source token when the authority supports query-record-revisions-v1. */
+    revision?: string;
     frontmatter?: Frontmatter;
     effectiveFrontmatter?: Frontmatter;
     body?: string;
@@ -64,6 +66,41 @@ export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
     values?: JsonObject;
     contract?: DataContractViewIdentity;
 }
+/** Query-shaped projection; qualified document batches supply exact-source revisions. */
+export type ReadManyRecord<Frontmatter extends JsonObject = JsonObject> = QueryRecord<Frontmatter>;
+export interface ReadManyOptions extends ConnectRequestOptions {
+    includeBody?: boolean;
+    frontmatterMode?: QueryInput["frontmatterMode"];
+    /** Restrict matching records to these raw collection types, not a contract view. */
+    types?: string[];
+    /** Unique paths per batch, default 100; range 1..1,000. Document authorities cap at 100. */
+    batchSize?: number;
+    /** Independent batches in flight, default 4; range 1..4. Cursor pages stay serial. */
+    concurrency?: number;
+}
+export type ReadManyEntry<Frontmatter extends JsonObject = JsonObject> = {
+    status: "found";
+    path: string;
+    record: ReadManyRecord<Frontmatter>;
+} | {
+    status: "missing";
+    path: string;
+} | {
+    status: "error";
+    path: string;
+    batch: number;
+};
+export interface ReadManyBatchError {
+    batch: number;
+    paths: string[];
+    failure: import("./outcomes.js").ConnectFailure<import("./outcomes.js").CollectionQueryProblemCode>;
+}
+export interface ReadManyResult<Frontmatter extends JsonObject = JsonObject> {
+    /** One entry per input path, in input order, including duplicates. */
+    results: ReadManyEntry<Frontmatter>[];
+    /** Batch failures cover the entire batch; semantic item failures cover only their paths. */
+    errors: ReadManyBatchError[];
+}
 export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
     path: string;
     revision: string;
@@ -107,6 +144,8 @@ export interface CollectionContractDescriptor {
     implementations: CollectionContractImplementationDescriptor[];
 }
 export interface CollectionDescription {
+    /** Immutable authority implementation features; never a permission claim. */
+    authorityCapabilities?: readonly string[];
     protocolVersion: 1;
     collectionId: string;
     displayName: string;
@@ -139,6 +178,7 @@ export interface QuerySummary {
 }
 /** Application-facing form of the canonical mdbase v0.3 query schema. */
 export interface QueryInput {
+    output?: never;
     /**
      * Queries using a semantic contract view accept only `types`, `timezone`,
      * pagination, `frontmatterMode`, and `contract`; filter normalized fields in
@@ -172,8 +212,26 @@ export interface QueryInput {
     /** Select one exact semantic contract/provider view for this query. */
     contract?: DataContractSelector;
 }
-export interface QueryResult<Record extends JsonObject = JsonObject> {
-    results: Array<QueryRecord<Record>>;
+export type QueryMetadataInput = Omit<QueryInput, "output" | "includeBody"> & {
+    output: "metadata";
+    includeBody?: false;
+};
+/** Partial metadata is not a record document; revision and selected values are required. */
+export interface QueryMetadataRecord {
+    path: string;
+    types: string[];
+    revision: string;
+    values: JsonObject;
+    contract?: DataContractViewIdentity;
+}
+export type QueryMetadataResult = QueryResult<JsonObject, QueryMetadataRecord> & {
+    output: "metadata";
+};
+export type QueryMetadataPage = QueryPage<JsonObject, QueryMetadataRecord> & {
+    output: "metadata";
+};
+export interface QueryResult<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> {
+    results: Row[];
     meta?: {
         /** Exact total when it is available within the page summary budget. */
         totalCount?: number;
@@ -188,26 +246,30 @@ export interface QueryResult<Record extends JsonObject = JsonObject> {
         snapshot?: string;
     };
 }
-export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
-    /** Initial page size. Cursor authorities pin this size for the query lifetime. */
+export interface QueryPagesOptions<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> {
+    /** Initial page size. Cursor continuations use this pinned size. */
     firstPageSize?: number;
-    /** Also sets the initial size unless firstPageSize is explicit; authorities may cap it. */
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
+    /** Total rows to deliver, not a page size. Zero makes no data requests. */
+    maxResults?: number;
     signal?: AbortSignal;
     /** Independent budget for each page requested by this caller-driven iterator. */
     pageTimeoutMs?: number | null;
     coordination?: RequestCoordinationOptions;
-    onProgress?: (page: QueryPage<Record>) => void;
+    onProgress?: (page: QueryPage<Record, Row>) => void;
 }
-export interface QueryAllOptions<Record extends JsonObject = JsonObject> extends ConnectRequestOptions {
-    /** Initial page size. Cursor authorities pin this size for the query lifetime. */
+export interface QueryAllOptions<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> extends ConnectRequestOptions {
+    /** Initial page size. Cursor continuations use this pinned size. */
     firstPageSize?: number;
-    /** Also sets the initial size unless firstPageSize is explicit; authorities may cap it. */
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
-    onProgress?: (page: QueryPage<Record>) => void;
+    /** Total rows to return, independent of page size. */
+    maxResults?: number;
+    onProgress?: (page: QueryPage<Record, Row>) => void;
 }
-export interface QueryPage<Record extends JsonObject = JsonObject> {
-    results: QueryResult<Record>["results"];
+export interface QueryPage<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> {
+    results: QueryResult<Record, Row>["results"];
     meta?: QueryResult<Record>["meta"];
     page: number;
     offset: number;
@@ -404,8 +466,12 @@ export interface ExecuteViewInput {
     render?: boolean;
 }
 export interface SavedViewPagesOptions<Frontmatter extends JsonObject = JsonObject> {
+    /** Initial page size, pinned for cursor continuations. */
     firstPageSize?: number;
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
+    /** Total rows to deliver, not a page size. Zero makes no data requests. */
+    maxResults?: number;
     signal?: AbortSignal;
     /** Independent budget for each page requested by this caller-driven iterator. */
     pageTimeoutMs?: number | null;
@@ -685,12 +751,87 @@ export interface MdbaseWatchSubscription {
     subscribe(listener: (change: CollectionChange) => void, onStatus?: (status: WatchStatus) => void, onProblem?: (problem: ConnectProblem) => void): () => void;
     close(): void;
 }
-export interface CollectionChange {
+export interface DescribeOptions extends ConnectRequestOptions {
+    /** Bypass the settled description cache (concurrent requests still share a load). */
+    fresh?: boolean;
+}
+interface ChangeBase {
     cursor: number;
+    /** Original authority event ID. Prefer kind for application logic. */
     type: string;
     occurredAt: string;
     payload: JsonObject;
+    /** Unmodified wire event, including authority-specific metadata. */
+    raw: WireCollectionChange;
+}
+export interface RecordChangeMetadata {
+    revision?: string;
+    previousRevision?: string;
+    types?: string[];
+    previousTypes?: string[];
+    /** Authority field identifiers: local JSON Pointers, hosted top-level keys. Preserved, not guessed. */
+    changedFields?: string[];
+    bodyChanged?: boolean;
+    /** Hosted authorities may supply frontmatter; local authorities need not. */
+    before?: JsonObject;
+    after?: JsonObject;
+}
+interface ResourceChangeBase extends ChangeBase {
+    path?: string;
+    name?: string;
+    revision?: string;
+    previousRevision?: string;
 }
+export type CollectionChange = (ChangeBase & RecordChangeMetadata & {
+    kind: "record.created";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.updated";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.deleted";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.renamed";
+    from: string;
+    to: string;
+}) | (ResourceChangeBase & {
+    kind: "schema.changed";
+}) | (ResourceChangeBase & {
+    kind: "config.changed";
+}) | (ResourceChangeBase & {
+    kind: "contract.changed";
+}) | (ResourceChangeBase & {
+    kind: "view.changed";
+}) | (ChangeBase & {
+    kind: "file.changed";
+    path: string;
+    revision?: string;
+    previousRevision?: string;
+}) | (ChangeBase & {
+    kind: "file.put";
+    file: import("./file-descriptor.js").CollectionFileDescriptor;
+}) | (ChangeBase & {
+    kind: "file.removed";
+    fileId: string;
+    previousPath?: string;
+    revision?: string;
+}) | (ChangeBase & {
+    kind: "gap";
+    reason?: string;
+}) | (ChangeBase & {
+    kind: "unknown";
+    reason: "unrecognized_type" | "invalid_payload";
+})
+/** Synthesized from a reset page, not a new authority event ID. Watch still terminates with change_cursor_reset. */
+ | {
+    kind: "reset";
+    cursor: number;
+    type: "reset";
+    occurredAt: null;
+    payload: JsonObject;
+    raw: WireCollectionChangesPage;
+};
 export interface CollectionChangesPage {
     events: CollectionChange[];
     cursor: number;

package/dist/query-pagination-internals.d.ts

@@ -0,0 +1,9 @@
+/** Owns the latest single-use cursor, including while an iterator is paused at yield. */
+export declare function queryCursorLease(release: (cursor: string) => Promise<void>, signal?: AbortSignal, initialCursor?: string): {
+    startRequest(): void;
+    finishRequest(nextCursor?: string): void;
+    dispose(): void;
+};
+export declare function resultCap(value?: number): number;
+export declare function nonNegativeInteger(value: unknown, fallback: number): number;
+export declare function positiveInteger(value: unknown, fallback: number): number;

package/dist/query-pagination-internals.js

@@ -0,0 +1,52 @@
+/** Owns the latest single-use cursor, including while an iterator is paused at yield. */
+export function queryCursorLease(release, signal, initialCursor) {
+    let cursor = initialCursor;
+    let inFlight = false;
+    const close = () => {
+        if (!cursor)
+            return;
+        const owned = cursor;
+        cursor = undefined;
+        // Collection cleanup has an independent bounded budget, never the data signal.
+        void release(owned).catch(() => undefined);
+    };
+    const abort = () => {
+        // A consumed token can rotate while the request settles. Release the returned
+        // token instead; a paused iterator has no request and closes immediately.
+        if (!inFlight)
+            close();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    return {
+        startRequest() { inFlight = true; },
+        finishRequest(nextCursor) {
+            if (nextCursor)
+                cursor = nextCursor;
+            inFlight = false;
+            if (signal?.aborted)
+                close();
+        },
+        dispose() {
+            signal?.removeEventListener("abort", abort);
+            close();
+        }
+    };
+}
+export function resultCap(value) {
+    if (value === undefined)
+        return Infinity;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError("maxResults must be a non-negative safe integer.");
+    }
+    return value;
+}
+export function nonNegativeInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : fallback;
+}
+export function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : fallback;
+}

package/dist/query-pagination.d.ts

@@ -1,6 +1,10 @@
 import type { JsonObject } from "@mdbase-dev/connect-protocol";
 import { type CollectionQueryProblemCode, type ConnectOutcome } from "./outcomes.js";
-import type { ConnectRequestOptions, QueryInput, QueryPage, QueryPagesOptions, QueryResult } from "./operation-types.js";
-type QueryOperation<Frontmatter extends JsonObject> = (input: QueryInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
-export declare function coordinatedQueryPages<Frontmatter extends JsonObject>(query: QueryOperation<Frontmatter>, releaseQueryCursor: (cursor: string) => Promise<void>, input?: QueryInput, options?: QueryPagesOptions<Frontmatter>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter>, CollectionQueryProblemCode>>;
+import type { ConnectRequestOptions, QueryInput, QueryMetadataInput, QueryRecord, QueryPage, QueryPagesOptions, QueryResult } from "./operation-types.js";
+type QueryOperation<Frontmatter extends JsonObject, Row> = (input: QueryInput | QueryMetadataInput, options?: ConnectRequestOptions) => Promise<ConnectOutcome<QueryResult<Frontmatter, Row> & {
+    output?: "metadata";
+}, CollectionQueryProblemCode>>;
+export declare function coordinatedQueryPages<Frontmatter extends JsonObject, Row = QueryRecord<Frontmatter>>(query: QueryOperation<Frontmatter, Row>, releaseQueryCursor: (cursor: string) => Promise<void>, input?: QueryInput | QueryMetadataInput, options?: QueryPagesOptions<Frontmatter, Row>): AsyncGenerator<ConnectOutcome<QueryPage<Frontmatter, Row> & {
+    output?: "metadata";
+}, CollectionQueryProblemCode>>;
 export {};