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

package/dist/connection.js

@@ -2,9 +2,13 @@ import { MdbasePeopleClient, requestPeople } from "./people-client.js";
 import { capabilityOperationsForContractVersion } from "@mdbase-dev/connect-protocol";
 import { retainedCapabilities, semanticContractVersion, validateAuthorizationSelection } from "./application-contract.js";
 import { MdbaseCollectionClient } from "./collection-client.js";
+import { AuthorityFeatures, authorityCapabilities } from "./authority-features.js";
+import { filePage } from "./file-metadata.js";
+import { wireCollectionDescription } from "./query-wire.js";
+import { CollectionWatchSubscription } from "./watch-policy.js";
 import { ConnectionNotifications } from "./connection-notifications.js";
 import { ConnectionTransport } from "./connection-transport.js";
-import { MdbaseConnectError, connectProblem, operationProblem } from "./errors.js";
+import { MdbaseConnectError, connectError, connectProblem, operationProblem } from "./errors.js";
 import { MdbaseFileClient } from "./files.js";
 import { MdbaseRecords } from "./records.js";
 import { DEFAULT_OPERATIONS } from "./internal-types.js";
@@ -18,10 +22,12 @@ export class MdbaseConnection {
     collectionClient;
     notifications;
     transport;
+    authorityFeatures;
     files;
     /** Editable record sessions shared by every view of this connection. */
     records;
     people;
+    readMany;
     connectionListeners = new Set();
     constructor(internals, collectionId) {
         this.internals = internals;
@@ -35,8 +41,34 @@ export class MdbaseConnection {
             collectionId,
             internals,
             timeouts: internals.timeouts,
-            onChange: () => this.emitConnection()
+            onChange: () => {
+                this.authorityFeatures.refreshLifetime();
+                this.emitConnection();
+            }
         });
+        this.authorityFeatures = new AuthorityFeatures({
+            lifetime: () => {
+                const token = this.transport.currentToken();
+                return JSON.stringify([token?.savedAt, token?.grantId, token?.keyHandle,
+                    token?.authority?.operationsUrl, token?.authority?.filesUrl, token?.authority?.replicaId,
+                    token?.authority?.proofPublicKey, token?.clientId, token?.applicationOrigin,
+                    token?.encryption, token?.scope, token?.operations, token?.fileCapability, this.transport.route]);
+            },
+            operations: () => this.operations,
+            fileCapability: () => this.fileCapability,
+            // Catalog TTL/in-flight loads are not evidence for a new authority route.
+            // B1 owns this authenticated baseline's sharing, deadline and lifetime.
+            describe: async (options) => {
+                const value = wireCollectionDescription(await this.transport.performOperation("describe", {}, options));
+                if (value.collectionId.toLowerCase() !== this.collectionId.toLowerCase())
+                    throw connectError("invalid_operation_response", "The authority described a different collection.");
+                return connectSuccess(value);
+            },
+            filesPage: async (folder, signal) => {
+                const page = await filePage((method, path, input, signal) => this.transport.files.control(method, path, input, signal), new URLSearchParams({ protocol_version: "1", limit: "1", ...(folder ? { folder } : {}) }), signal);
+                return authorityCapabilities(page.authority_capabilities);
+            }
+        }, internals.timeouts.requestMs);
         this.people = new MdbasePeopleClient({
             request: (resource, options) => requestPeople(resource, options ?? {}, {
                 serverUrl: internals.serverUrl, collectionId, requestMs: internals.timeouts.requestMs,
@@ -50,11 +82,12 @@ export class MdbaseConnection {
             downloadChunk: (session, chunkIndex, signal) => this.transport.files.downloadChunk(session, chunkIndex, signal)
         }, {
             downloadPart: (session, partIndex, expectedLength, signal) => this.transport.files.downloadHostedPart(session, partIndex, expectedLength, signal)
-        }, internals.timeouts);
+        }, internals.timeouts, (id, options) => this.supportsAuthorityFeature(id, options));
         this.records = new MdbaseRecords(this, (path) => this.transport.pendingUpdate(path));
         this.collectionClient = new MdbaseCollectionClient(new CollectionRequestCoordinator({
             operation: (operation, input, requestOptions) => this.transport.performOperation(operation, input, requestOptions)
-        }, internals.timeouts.requestMs), internals.timeouts.requestMs);
+        }, internals.timeouts.requestMs), internals.timeouts.requestMs, (id, options) => this.supportsAuthorityFeature(id, options));
+        this.readMany = this.collectionClient.readMany.bind(this.collectionClient);
         this.notifications = new ConnectionNotifications({
             serverUrl: internals.serverUrl,
             storage: internals.storage,
@@ -83,6 +116,11 @@ export class MdbaseConnection {
     get route() {
         return this.transport.route;
     }
+    /** Implementation support for this connection lifetime; not an authorization check. */
+    supportsAuthorityFeature(id, options) {
+        return this.authorityFeatures.supports(id, options);
+    }
+    get authorityCapabilities() { return this.authorityFeatures.capabilities; }
     register(options) {
         return captureConnectOutcome(() => this.internals.register(options), REGISTRATION_PROBLEM_CODES);
     }
@@ -166,6 +204,7 @@ export class MdbaseConnection {
         return () => this.connectionListeners.delete(listener);
     }
     notifyStorageChanged() {
+        this.authorityFeatures.invalidate();
         this.transport.notifyStorageChanged();
     }
     checkDirectAccess(options) {
@@ -254,8 +293,13 @@ 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; }
+    async describe(options) {
+        const outcome = await this.collectionClient.describe(options);
+        if (outcome.ok && outcome.value.collectionId.toLowerCase() !== this.collectionId.toLowerCase()) {
+            return connectFailure(connectProblem("invalid_operation_response", "The authority described a different collection."));
+        }
+        return outcome;
     }
     changes(input = {}, options) {
         return this.collectionClient.changes(input, options);
@@ -267,10 +311,14 @@ export class MdbaseConnection {
         return this.collectionClient.query(input, options);
     }
     queryPages(input = {}, options = {}) {
-        return this.collectionClient.queryPages(input, options);
+        return input.output === "metadata"
+            ? this.collectionClient.queryPages(input, options)
+            : this.collectionClient.queryPages(input, options);
     }
     queryAll(input = {}, options = {}) {
-        return this.collectionClient.queryAll(input, options);
+        return input.output === "metadata"
+            ? this.collectionClient.queryAll(input, options)
+            : this.collectionClient.queryAll(input, options);
     }
     listViews(options) {
         return this.collectionClient.listViews(options);
@@ -492,7 +540,7 @@ export class MdbaseConnection {
             if (initial.value.reset) {
                 throw new MdbaseConnectError(connectProblem("change_cursor_reset", "The collection change cursor expired. Refresh collection state before subscribing again."));
             }
-            return new CollectionWatchSubscription(this.collectionClient, initial.value.cursor, input, input.cursor === undefined ? [] : initial.value.events, this.internals.timeouts.watchStartMs);
+            return new CollectionWatchSubscription(options => this.collectionClient.watch(options), initial.value.cursor, input, input.cursor === undefined ? [] : initial.value.events, this.internals.timeouts.watchStartMs);
         }), COLLECTION_CHANGES_PROBLEM_CODES);
     }
     emitConnection() {
@@ -501,114 +549,6 @@ export class MdbaseConnection {
             listener(connection);
     }
 }
-class CollectionWatchSubscription {
-    client;
-    input;
-    watchStartTimeoutMs;
-    changes = new Set();
-    statuses = new Set();
-    problems = new Set();
-    controller = new AbortController();
-    removeLifetimeAbort;
-    currentStatus;
-    currentProblem = null;
-    pendingChanges;
-    constructor(client, cursor, input, pendingChanges, watchStartTimeoutMs) {
-        this.client = client;
-        this.input = input;
-        this.watchStartTimeoutMs = watchStartTimeoutMs;
-        this.pendingChanges = [...pendingChanges];
-        this.currentStatus = { state: "connected", cursor, recovered: false };
-        const lifetimeSignal = input.lifetimeSignal;
-        if (lifetimeSignal?.aborted)
-            this.close();
-        else if (lifetimeSignal) {
-            const close = () => this.close();
-            lifetimeSignal.addEventListener("abort", close, { once: true });
-            this.removeLifetimeAbort = () => lifetimeSignal.removeEventListener("abort", close);
-        }
-        if (!this.controller.signal.aborted)
-            void this.run(cursor);
-    }
-    get status() {
-        return this.currentStatus;
-    }
-    get problem() {
-        return this.currentProblem;
-    }
-    subscribe(listener, onStatus, onProblem) {
-        this.changes.add(listener);
-        if (onStatus) {
-            this.statuses.add(onStatus);
-            onStatus(this.currentStatus);
-        }
-        if (onProblem) {
-            this.problems.add(onProblem);
-            if (this.currentProblem)
-                onProblem(this.currentProblem);
-        }
-        for (const change of this.pendingChanges)
-            listener(change);
-        this.pendingChanges = [];
-        return () => {
-            this.changes.delete(listener);
-            if (onStatus)
-                this.statuses.delete(onStatus);
-            if (onProblem)
-                this.problems.delete(onProblem);
-        };
-    }
-    close() {
-        if (this.controller.signal.aborted)
-            return;
-        this.controller.abort();
-        this.removeLifetimeAbort?.();
-        this.removeLifetimeAbort = undefined;
-        const cursor = "cursor" in this.currentStatus ? this.currentStatus.cursor : undefined;
-        this.publishStatus({ state: "closed", ...(cursor === undefined ? {} : { cursor }) });
-    }
-    async run(cursor) {
-        let firstStatus = true;
-        const iterator = this.client.watch({
-            cursor,
-            pollIntervalMs: this.input.pollIntervalMs,
-            retry: this.input.retry,
-            signal: this.controller.signal,
-            timeoutMs: this.watchStartTimeoutMs,
-            onStatus: (status) => {
-                if (firstStatus && status.state === "connecting") {
-                    firstStatus = false;
-                    return;
-                }
-                firstStatus = false;
-                this.publishStatus(status);
-            }
-        });
-        try {
-            for await (const outcome of iterator) {
-                if (this.controller.signal.aborted)
-                    return;
-                if (!outcome.ok) {
-                    this.currentProblem = outcome.problem;
-                    for (const listener of this.problems)
-                        listener(outcome.problem);
-                    return;
-                }
-                for (const listener of this.changes)
-                    listener(outcome.value);
-            }
-        }
-        finally {
-            if (!this.controller.signal.aborted)
-                this.close();
-        }
-    }
-    publishStatus(status) {
-        this.currentStatus = status;
-        for (const listener of this.statuses)
-            listener(status);
-    }
-}
 function syncRequestOptions(options, defaultTimeoutMs) {
     return {
         ...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,46 @@
+import { COLLECTION_DESCRIPTION_PROBLEM_CODES, captureConnectOutcome, connectSuccess } from "./outcomes.js";
+import { withRequestBudget } from "./request-budget.js";
+import { wireCollectionDescription } from "./query-wire.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);
+    }
+}

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,14 @@
+import type { CollectionFileDescriptor as WireFile } from "@mdbase-dev/connect-protocol";
+export declare const FILE_ID: RegExp;
+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 validFileDescriptor(value: unknown): value is WireFile;
+export declare function clientFileDescriptor(file: WireFile): CollectionFileDescriptor;

package/dist/file-descriptor.js

@@ -0,0 +1,29 @@
+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,
+        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-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/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,13 @@
+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";
 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";
@@ -38,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;
@@ -76,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;
@@ -84,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;
     /**
@@ -112,4 +103,3 @@ export declare class MdbaseFileClient {
     private requireAction;
     private abort;
 }
-export {};