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

package/dist/file-descriptor.d.ts

@@ -1,4 +1,5 @@
 import type { CollectionFileDescriptor as WireFile } from "@mdbase-dev/connect-protocol";
+export declare const FILE_ID: RegExp;
 export interface CollectionFileDescriptor {
     fileId: string;
     path: string;
@@ -9,4 +10,5 @@ export interface CollectionFileDescriptor {
     mediaClass: import("@mdbase-dev/connect-protocol").FileMediaClass;
     modifiedAt: string;
 }
+export declare function validFileDescriptor(value: unknown): value is WireFile;
 export declare function clientFileDescriptor(file: WireFile): CollectionFileDescriptor;

package/dist/file-descriptor.js

@@ -1,4 +1,21 @@
+import { connectError } from "./errors.js";
+import { SHA256_DIGEST } from "./file-transfer-internals.js";
+// Match files.v1's UUID format (including nil), not crypto transfer-version rules.
+export const FILE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+export function validFileDescriptor(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const file = value;
+    return typeof file.file_id === "string" && FILE_ID.test(file.file_id)
+        && typeof file.path === "string" && typeof file.revision === "string"
+        && typeof file.content_digest === "string" && SHA256_DIGEST.test(file.content_digest)
+        && Number.isSafeInteger(file.size) && file.size >= 0
+        && ["image", "audio", "video", "pdf", "other"].includes(file.media_class)
+        && typeof file.modified_at === "string" && (file.media_type === undefined || typeof file.media_type === "string");
+}
 export function clientFileDescriptor(file) {
+    if (!validFileDescriptor(file))
+        throw connectError("invalid_operation_response", "The authority returned an invalid file descriptor.");
     return {
         fileId: file.file_id,
         path: file.path,

package/dist/file-metadata.d.ts

@@ -0,0 +1,21 @@
+import type { FileCapability, ListFilesPage } from "@mdbase-dev/connect-protocol";
+import type { ConnectRequestOptions } from "./operation-types.js";
+import { type ConnectOutcome } from "./outcomes.js";
+import { type CollectionFileDescriptor } from "./file-descriptor.js";
+export interface MdbaseFileListOptions extends ConnectRequestOptions {
+    folder?: string;
+    pageSize?: number;
+    /** Called while a cold or changed collection builds its verified binary index. */
+    onIndexing?: () => void;
+}
+export type MdbaseFileStatTarget = {
+    path: string;
+    fileId?: never;
+} | {
+    path?: never;
+    fileId: string;
+};
+export type FileControlRequest = <Result>(method: "GET" | "POST" | "DELETE", path?: string, input?: unknown, signal?: AbortSignal) => Promise<Result>;
+export declare function filePage(request: FileControlRequest, query: URLSearchParams, signal?: AbortSignal, onIndexing?: () => void): Promise<ListFilesPage>;
+export declare function listFiles(capability: () => FileCapability | null, request: FileControlRequest, options: MdbaseFileListOptions, timeoutMs: number | null): AsyncGenerator<CollectionFileDescriptor>;
+export declare function statFile(capability: () => FileCapability | null, request: FileControlRequest, supports: (id: string, options?: ConnectRequestOptions) => Promise<ConnectOutcome<boolean>>, list: (options: MdbaseFileListOptions) => AsyncIterable<CollectionFileDescriptor>, target: MdbaseFileStatTarget, options: ConnectRequestOptions, timeoutMs: number | null): Promise<ConnectOutcome<CollectionFileDescriptor | null>>;

package/dist/file-metadata.js

@@ -0,0 +1,112 @@
+import { abortableDelay } from "./async.js";
+import { authorityCapabilities } from "./authority-features.js";
+import { connectError, MdbaseConnectError } from "./errors.js";
+import { normalizeFileError, throwIfAborted, validPageSize } from "./file-transfer-internals.js";
+import { ALL_CONNECT_PROBLEM_CODES, captureConnectOutcome } from "./outcomes.js";
+import { createRequestBudget, withRequestBudget } from "./request-budget.js";
+import { clientFileDescriptor, FILE_ID } from "./file-descriptor.js";
+export async function filePage(request, query, signal, onIndexing) {
+    while (true) {
+        throwIfAborted(signal);
+        try {
+            const page = await request("GET", `?${query}`, undefined, signal);
+            if (page?.protocol_version !== 1 || page.type !== "files_page" || !Array.isArray(page.files)
+                || (page.next !== undefined && (typeof page.next !== "string" || !page.next))) {
+                throw connectError("invalid_operation_response", "The authority returned an invalid file page.");
+            }
+            authorityCapabilities(page.authority_capabilities);
+            return page;
+        }
+        catch (error) {
+            const normalized = normalizeFileError(error);
+            if (normalized.code !== "file_index_warming")
+                throw normalized;
+            onIndexing?.();
+            await abortableDelay(500, signal);
+        }
+    }
+}
+export async function* listFiles(capability, request, options, timeoutMs) {
+    const budget = createRequestBudget(options, timeoutMs);
+    try {
+        requireList(capability());
+        let after;
+        do {
+            const query = new URLSearchParams({
+                protocol_version: "1",
+                ...(options.folder ? { folder: options.folder } : {}),
+                ...(after ? { after } : {}),
+                ...(options.pageSize ? { limit: String(validPageSize(options.pageSize)) } : {})
+            });
+            const page = await filePage(request, query, budget.signal, options.onIndexing);
+            for (const file of page.files) {
+                throwIfAborted(budget.signal);
+                yield clientFileDescriptor(file);
+            }
+            after = page.next;
+        } while (after);
+    }
+    finally {
+        budget.dispose();
+    }
+}
+export function statFile(capability, request, supports, list, target, options, timeoutMs) {
+    return captureConnectOutcome(() => withRequestBudget(options, timeoutMs, async (budget) => {
+        requireList(capability());
+        if (!target || typeof target !== "object" || Object.keys(target).length !== 1
+            || !(Object.hasOwn(target, "path") && typeof target.path === "string"
+                || Object.hasOwn(target, "fileId") && typeof target.fileId === "string" && FILE_ID.test(target.fileId))) {
+            throw connectError("invalid_request", "File stat requires exactly one path or UUID fileId.");
+        }
+        // Collection-relative wire syntax only. Eligibility, exclusion rules and
+        // filesystem access remain authority-owned, including during legacy listing.
+        if (target.path !== undefined && (target.path.length > 1024 || target.path.includes("\\")
+            || target.path.split("/").some(part => !part || part.startsWith(".")))) {
+            throw connectError("invalid_request", "File stat requires a collection-relative file path.");
+        }
+        const supported = await supports("files-stat-v1", { signal: budget.signal, timeoutMs: null });
+        if (!supported.ok)
+            throw new MdbaseConnectError(supported.problem);
+        throwIfAborted(budget.signal);
+        if (supported.value) {
+            const result = await request("POST", "stat", {
+                protocol_version: 1, type: "stat_file",
+                ...(target.path !== undefined ? { path: target.path } : { file_id: target.fileId })
+            }, budget.signal);
+            if (result?.protocol_version !== 1 || result.type !== "file_stat" || result.file === undefined) {
+                throw connectError("invalid_operation_response", "The authority returned an invalid file stat.");
+            }
+            if (result.file === null)
+                return null;
+            const file = clientFileDescriptor(result.file);
+            if (target.path !== undefined ? portableKey(file.path) !== portableKey(target.path)
+                : file.fileId.toLowerCase() !== target.fileId.toLowerCase()) {
+                throw connectError("invalid_operation_response", "The authority returned a stat for a different file.");
+            }
+            return file;
+        }
+        // Consumers: Writer/Reader/editor/TaskNotes against late-updated authorities.
+        // Remove once the minimum files-stat authority, all consumer pins, and N-1
+        // rollback/connection-cache windows close. Listing is not point-cost or atomic.
+        const folder = target.path?.includes("/") ? target.path.slice(0, target.path.lastIndexOf("/")) : undefined;
+        for await (const file of list({ folder, signal: budget.signal, timeoutMs: null })) {
+            throwIfAborted(budget.signal);
+            if (target.path !== undefined
+                ? portableKey(file.path) === portableKey(target.path)
+                : file.fileId.toLowerCase() === target.fileId.toLowerCase())
+                return file;
+        }
+        throwIfAborted(budget.signal);
+        return null;
+    }), ALL_CONNECT_PROBLEM_CODES);
+}
+function requireList(capability) {
+    if (!capability?.actions.includes("list"))
+        throw connectError("not_authorized", "This connection is not authorized to list files.");
+}
+// File protocol portable identity comparison, not collection eligibility validation.
+function portableKey(path) {
+    // Match Connect's NFC + per-Unicode-scalar lowercase + NFC key, not JS's
+    // context-sensitive whole-string lowercase (e.g. Greek final sigma).
+    return Array.from(path.normalize("NFC"), scalar => scalar.toLowerCase()).join("").normalize("NFC");
+}

package/dist/files.d.ts

@@ -1,6 +1,9 @@
 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 FileControlRequest, type MdbaseFileListOptions, type MdbaseFileStatTarget } from "./file-metadata.js";
+export type { MdbaseFileListOptions, MdbaseFileStatTarget } from "./file-metadata.js";
+import { type ConnectOutcome } from "./outcomes.js";
 import { type FileSource } from "./file-transfer-internals.js";
 import type { ConnectRequestOptions } from "./operation-types.js";
 import { type ResolvedConnectTimeouts } from "./request-budget.js";
@@ -30,12 +33,6 @@ export interface MdbaseFileProgress {
     transferredBytes: number;
     totalBytes: number;
 }
-export interface MdbaseFileListOptions extends ConnectRequestOptions {
-    folder?: string;
-    pageSize?: number;
-    /** Called while a cold or changed collection builds its verified binary index. */
-    onIndexing?: () => void;
-}
 export interface MdbaseFileUploadOptions extends ConnectRequestOptions {
     mediaType?: string;
     ifRevision?: string;
@@ -68,7 +65,6 @@ export interface MdbaseFramedFileTransport {
 export interface MdbaseHostedFileTransport {
     downloadPart(session: FileTransferSession, partIndex: number, expectedLength: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
 }
-type ControlRequest = <Result>(method: "GET" | "POST" | "DELETE", path?: string, input?: unknown, signal?: AbortSignal) => Promise<Result>;
 /** Ergonomic facade over resumable, authority-specific file delivery. */
 export declare class MdbaseFileClient {
     private readonly capability;
@@ -76,8 +72,11 @@ export declare class MdbaseFileClient {
     private readonly framed?;
     private readonly hosted?;
     private readonly timeouts;
-    constructor(capability: () => FileCapability | null, request: ControlRequest, framed?: MdbaseFramedFileTransport | undefined, hosted?: MdbaseHostedFileTransport | undefined, timeouts?: ResolvedConnectTimeouts);
+    private readonly supportsAuthorityFeature;
+    constructor(capability: () => FileCapability | null, request: FileControlRequest, framed?: MdbaseFramedFileTransport | undefined, hosted?: MdbaseHostedFileTransport | undefined, timeouts?: ResolvedConnectTimeouts, supportsAuthorityFeature?: (id: string, options?: ConnectRequestOptions) => Promise<ConnectOutcome<boolean>>);
     list(options?: MdbaseFileListOptions): AsyncGenerator<CollectionFileDescriptor>;
+    /** Current metadata lookup; requires file list approval, not file byte access. */
+    stat(target: MdbaseFileStatTarget, options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionFileDescriptor | null>>;
     upload(path: string, source: MdbaseFileSource, options?: MdbaseFileUploadOptions): Promise<CollectionFileDescriptor>;
     private uploadWithinBudget;
     /**

package/dist/files.js

@@ -1,11 +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;
@@ -13,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 }));

package/dist/index.d.ts

@@ -19,11 +19,11 @@ 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, ReadManyOptions, ReadManyRecord, ReadManyEntry, ReadManyBatchError, ReadManyResult, 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, RecordChangeMetadata, DescribeOptions, 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";

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

@@ -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,17 +66,14 @@ export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
     values?: JsonObject;
     contract?: DataContractViewIdentity;
 }
-/** Query-shaped batched record today; a future authority may supply a revision. */
-export interface ReadManyRecord<Frontmatter extends JsonObject = JsonObject> extends QueryRecord<Frontmatter> {
-    /** Absent on current query authorities. Never synthesized from timestamps or content. */
-    revision?: string;
-}
+/** 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 independent query, default 100; range 1..1,000. */
+    /** 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;
@@ -99,7 +98,7 @@ export interface ReadManyBatchError {
 export interface ReadManyResult<Frontmatter extends JsonObject = JsonObject> {
     /** One entry per input path, in input order, including duplicates. */
     results: ReadManyEntry<Frontmatter>[];
-    /** A failed batch is not proof of missing records; its entries are errors. */
+    /** Batch failures cover the entire batch; semantic item failures cover only their paths. */
     errors: ReadManyBatchError[];
 }
 export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
@@ -145,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;
@@ -177,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
@@ -210,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;
@@ -226,7 +246,7 @@ export interface QueryResult<Record extends JsonObject = JsonObject> {
         snapshot?: string;
     };
 }
-export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
+export interface QueryPagesOptions<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> {
     /** Initial page size. Cursor continuations use this pinned size. */
     firstPageSize?: number;
     /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
@@ -237,19 +257,19 @@ export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
     /** 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 {
+export interface QueryAllOptions<Record extends JsonObject = JsonObject, Row = QueryRecord<Record>> extends ConnectRequestOptions {
     /** Initial page size. Cursor continuations use this pinned size. */
     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 return, independent of page size. */
     maxResults?: number;
-    onProgress?: (page: QueryPage<Record>) => void;
+    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;

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 {};

package/dist/query-pagination.js

@@ -25,7 +25,8 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
             const automaticCursorProbe = pageNumber === 0
                 && requestedCursor === undefined
                 && requestedPagination === undefined
-                && requestedSnapshot === undefined;
+                && requestedSnapshot === undefined
+                && input.output !== "metadata";
             let queried = await query({
                 ...criteria,
                 // Initial size is portable across authorities; continuations use the
@@ -96,6 +97,7 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
             loaded += results.length;
             const complete = loaded >= maxResults || !result.meta?.hasMore || result.results.length === 0;
             const page = {
+                ...(result.output ? { output: result.output } : {}),
                 results,
                 ...(result.meta ? { meta: result.meta } : {}),
                 page: pageNumber,

package/dist/query-wire.d.ts

@@ -0,0 +1,61 @@
+import type { CollectionDescription as WireDescription, DataContractViewIdentity as WireIdentity, JsonObject, QueryRecord as WireQueryRecord } from "@mdbase-dev/connect-protocol";
+import type { CollectionDescription, DataContractViewIdentity, QueryInput, QueryMetadataInput, QueryMetadataResult, QueryRecord, QueryResult } from "./operation-types.js";
+export interface WireQueryResult<Frontmatter extends JsonObject> {
+    output?: "metadata";
+    results: Array<WireQueryRecord<Frontmatter> | import("@mdbase-dev/connect-protocol").QueryMetadataRecord>;
+    meta?: {
+        total_count?: number | null;
+        total_count_outcome?: {
+            status: "deferred";
+            budget: "eager_summary_rows";
+            limit: number;
+        };
+        has_more: boolean;
+        cursor?: string;
+        snapshot?: string;
+    };
+}
+export declare function wireQueryInput(input: QueryInput | QueryMetadataInput): {
+    output?: "metadata" | undefined;
+    types?: string[] | undefined;
+    timezone?: string | undefined;
+    context?: {
+        this: {
+            path: string;
+        };
+    } | undefined;
+    projections?: {
+        [k: string]: {
+            expr: string;
+            description?: string | undefined;
+        };
+    } | undefined;
+    where?: string | undefined;
+    select?: (string | {
+        name: string;
+        expr: string;
+        label?: string | undefined;
+        description?: string | undefined;
+    })[] | undefined;
+    order_by?: import("./operation-types.js").QueryOrder[] | undefined;
+    group_by?: import("./operation-types.js").QueryOrder[] | undefined;
+    summary_functions?: {
+        [k: string]: {
+            expr: string;
+            description?: string | undefined;
+        };
+    } | undefined;
+    summaries?: import("./operation-types.js").QuerySummary[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    pagination?: "cursor" | undefined;
+    cursor?: string | undefined;
+    snapshot?: string | undefined;
+    include_body?: boolean | undefined;
+    frontmatter_mode?: "both" | "effective" | "persisted" | undefined;
+    contract?: import("./operation-types.js").DataContractSelector | undefined;
+};
+export declare function wireDataContractIdentity(value: WireIdentity): DataContractViewIdentity;
+export declare function wireQueryRecord<Frontmatter extends JsonObject>(value: WireQueryRecord<Frontmatter>): QueryRecord<Frontmatter>;
+export declare function wireQueryResult<Frontmatter extends JsonObject>(value: WireQueryResult<Frontmatter>, output: "metadata" | undefined): QueryResult<Frontmatter> | QueryMetadataResult;
+export declare function wireCollectionDescription(value: WireDescription): CollectionDescription;