@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/connection.js

@@ -1,15 +1,18 @@
 import { MdbaseCollectionClient } from "./collection-client.js";
 import { ConnectionNotifications } from "./connection-notifications.js";
 import { ConnectionTransport } from "./connection-transport.js";
-import { MdbaseConnectError, unwrapOperation } from "./errors.js";
+import { MdbaseConnectError } from "./errors.js";
+import { MdbaseFileClient } from "./files.js";
 import { DEFAULT_OPERATIONS } from "./internal-types.js";
 import { assertDeletePreview, assertRenamePreview, deleteEstimate, isCancellation, renameEstimate, throwIfCancelled, uniqueOperations } from "./operation-helpers.js";
+import { AUTHORIZATION_PROBLEM_CODES, COLLECTION_MUTATION_PROBLEM_CODES, DIRECT_ACCESS_PROBLEM_CODES, NOTIFICATION_PROBLEM_CODES, REGISTRATION_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
 export class MdbaseConnection {
     internals;
     collectionId;
     collectionClient;
     notifications;
     transport;
+    files;
     connectionListeners = new Set();
     constructor(internals, collectionId) {
         this.internals = internals;
@@ -24,6 +27,12 @@ export class MdbaseConnection {
             internals,
             onChange: () => this.emitConnection()
         });
+        this.files = new MdbaseFileClient(() => this.fileCapability, (method, path, input, signal) => this.transport.files.control(method, path, input, signal), {
+            uploadChunk: (session, chunkIndex, bytes, signal) => this.transport.files.uploadChunk(session, chunkIndex, bytes, signal),
+            downloadChunk: (session, chunkIndex, signal) => this.transport.files.downloadChunk(session, chunkIndex, signal)
+        }, {
+            downloadPart: (session, partIndex, expectedLength, signal) => this.transport.files.downloadHostedPart(session, partIndex, expectedLength, signal)
+        });
         this.collectionClient = new MdbaseCollectionClient({
             operation: (operation, input, requestOptions) => this.transport.performOperation(operation, input, requestOptions)
         });
@@ -31,7 +40,7 @@ export class MdbaseConnection {
             serverUrl: internals.serverUrl,
             storage: internals.storage,
             authorizedToken: () => this.transport.authorizedToken(),
-            register: () => this.register(),
+            register: () => this.internals.register(),
             notificationKey: (transport) => internals.notificationKey(collectionId, transport)
         });
     }
@@ -43,11 +52,10 @@ export class MdbaseConnection {
         return [...(this.transport.currentToken()?.operations ?? [])];
     }
     get scope() {
-        const scope = this.transport.currentToken()?.scope;
-        if (!scope) {
-            throw new MdbaseConnectError("not_authorized", "This collection is no longer authorized for this application.");
-        }
-        return scope;
+        return this.transport.currentToken()?.scope ?? null;
+    }
+    get fileCapability() {
+        return this.transport.currentToken()?.fileCapability ?? null;
     }
     get directAccess() {
         return this.transport.directAccess;
@@ -56,7 +64,7 @@ export class MdbaseConnection {
         return this.transport.route;
     }
     register() {
-        return this.internals.register();
+        return captureConnectOutcome(() => this.internals.register(), REGISTRATION_PROBLEM_CODES);
     }
     info() {
         const token = this.transport.currentToken();
@@ -65,6 +73,7 @@ export class MdbaseConnection {
             displayName: token.collectionName,
             operations: [...token.operations],
             scope: token.scope,
+            ...(token.fileCapability ? { fileCapability: token.fileCapability } : {}),
             route: this.transport.route,
             directAccess: this.transport.directAccess
         } : null;
@@ -85,15 +94,16 @@ export class MdbaseConnection {
         return this.authorizationCapabilities(requiredOperations).sufficient;
     }
     authorize(options = {}) {
-        return this.internals.authorize({
+        return captureConnectOutcome(() => this.internals.authorize({
             ...options,
             target: { kind: "collection", collectionId: this.collectionId }
-        });
+        }), AUTHORIZATION_PROBLEM_CODES);
     }
     async requestOperations(requiredOperations, options = {}) {
         const capabilities = this.authorizationCapabilities(requiredOperations);
-        if (capabilities.sufficient)
-            return { kind: "unchanged", connection: this };
+        if (capabilities.sufficient) {
+            return connectSuccess({ kind: "unchanged", connection: this });
+        }
         return this.authorize({
             ...options,
             operations: uniqueOperations([
@@ -111,11 +121,11 @@ export class MdbaseConnection {
         this.transport.notifyStorageChanged();
     }
     checkDirectAccess() {
-        return this.transport.checkDirectAccess();
+        return captureConnectOutcome(() => this.transport.checkDirectAccess(), DIRECT_ACCESS_PROBLEM_CODES);
     }
     /** Call from a user gesture to request browser permission for direct local access. */
     requestDirectAccess() {
-        return this.transport.requestDirectAccess();
+        return captureConnectOutcome(() => this.transport.requestDirectAccess(), DIRECT_ACCESS_PROBLEM_CODES);
     }
     disableDirectAccess() {
         this.transport.disableDirectAccess();
@@ -180,16 +190,16 @@ export class MdbaseConnection {
      * only an opaque cursor and static presentation copy.
      */
     registerNotifications(options) {
-        return this.notifications.registerNotifications(options);
+        return captureConnectOutcome(() => this.notifications.registerNotifications(options), NOTIFICATION_PROBLEM_CODES);
     }
     registerNativeNotifications(options) {
-        return this.notifications.registerNativeNotifications(options);
+        return captureConnectOutcome(() => this.notifications.registerNativeNotifications(options), NOTIFICATION_PROBLEM_CODES);
     }
     unregisterNativeNotifications() {
-        return this.notifications.unregisterNativeNotifications();
+        return captureConnectOutcome(() => this.notifications.unregisterNativeNotifications(), NOTIFICATION_PROBLEM_CODES);
     }
     unregisterNotifications(serviceWorker) {
-        return this.notifications.unregisterNotifications(serviceWorker);
+        return captureConnectOutcome(() => this.notifications.unregisterNotifications(serviceWorker), NOTIFICATION_PROBLEM_CODES);
     }
     forget() {
         const token = this.transport.currentToken();
@@ -268,22 +278,37 @@ export class MdbaseConnection {
         try {
             throwIfCancelled(options.signal);
             emit("preflighting", true);
-            const preview = options.preflight ?? unwrapOperation(await this.preflightRename(input, {
-                signal: options.signal
-            }));
-            assertRenamePreview(input, preview);
+            const previewOutcome = options.preflight
+                ? connectSuccess(options.preflight)
+                : await this.preflightRename(input, { signal: options.signal });
+            if (!previewOutcome.ok)
+                return previewOutcome;
+            const preview = previewOutcome.value;
+            try {
+                assertRenamePreview(input, preview);
+            }
+            catch (error) {
+                if (error instanceof MdbaseConnectError) {
+                    return connectFailure(error.problem);
+                }
+                throw error;
+            }
             estimate = renameEstimate(input, preview);
             emit("ready", true);
             throwIfCancelled(options.signal);
             const cancellable = this.transport.hasResumableMutationTransport();
             emit("applying", cancellable);
             const result = await this.rename(input, cancellable ? { signal: options.signal } : undefined);
-            emit("completed", false, estimate.totalUnits);
+            if (result.ok)
+                emit("completed", false, estimate.totalUnits);
             return result;
         }
         catch (error) {
             if (isCancellation(error, options.signal))
                 emit("cancelled", false);
+            if (error instanceof MdbaseConnectError) {
+                return connectFailure(error.problem);
+            }
             throw error;
         }
     }
@@ -305,30 +330,45 @@ export class MdbaseConnection {
         try {
             throwIfCancelled(options.signal);
             emit("preflighting", true);
-            const preview = options.preflight ?? unwrapOperation(await this.preflightDelete(input, {
-                signal: options.signal
-            }));
-            assertDeletePreview(input, preview);
+            const previewOutcome = options.preflight
+                ? connectSuccess(options.preflight)
+                : await this.preflightDelete(input, { signal: options.signal });
+            if (!previewOutcome.ok)
+                return previewOutcome;
+            const preview = previewOutcome.value;
+            try {
+                assertDeletePreview(input, preview);
+            }
+            catch (error) {
+                if (error instanceof MdbaseConnectError) {
+                    return connectFailure(error.problem);
+                }
+                throw error;
+            }
             estimate = deleteEstimate(preview);
             emit("ready", true);
             throwIfCancelled(options.signal);
             const cancellable = this.transport.hasResumableMutationTransport();
             emit("applying", cancellable);
             const result = await this.delete(input, cancellable ? { signal: options.signal } : undefined);
-            emit("completed", false, estimate.totalUnits);
+            if (result.ok)
+                emit("completed", false, estimate.totalUnits);
             return result;
         }
         catch (error) {
             if (isCancellation(error, options.signal))
                 emit("cancelled", false);
+            if (error instanceof MdbaseConnectError) {
+                return connectFailure(error.problem);
+            }
             throw error;
         }
     }
     pendingMutation() {
         return this.transport.pendingMutation();
     }
-    async resumePendingMutation(input, options) {
-        return this.transport.resumePendingMutation(input, options);
+    resumePendingMutation(input, options) {
+        return captureConnectOutcome(() => this.transport.resumePendingMutation(input, options), COLLECTION_MUTATION_PROBLEM_CODES);
     }
     validate(input = {}) {
         return this.collectionClient.validate(input);
@@ -357,10 +397,10 @@ export class MdbaseConnection {
     reconcileTimers(input) {
         return this.collectionClient.reconcileTimers(input);
     }
-    async *watch(options = {}) {
-        yield* this.collectionClient.watch(options);
+    watch(options = {}) {
+        return this.collectionClient.watch(options);
     }
-    async operation(operation, input, options) {
+    operation(operation, input, options) {
         return this.collectionClient.operation(operation, input, options);
     }
     emitConnection() {

package/dist/crypto.d.ts

@@ -1,4 +1,4 @@
-import { type CollectionOperation, type EncryptedRelayOperationRequest, type EncryptedRelayOperationResponse, type GrantEncryption } from "@mdbase-dev/connect-protocol";
+import { type ConnectProblem, type EncryptedRelayOperation, type EncryptedRelayOperationRequest, type EncryptedRelayOperationResponse, type GrantEncryption } from "@mdbase-dev/connect-protocol";
 export interface GrantKeyRecord {
     handle: string;
     agreementPrivateKey: CryptoKey;
@@ -46,19 +46,18 @@ export interface AuthorityProofInput {
 /** Sign one remote-authority or token-refresh request with the approved grant key. */
 export declare function signAuthorityRequest(store: GrantKeyStore, handle: string, expectedPublicKey: string, input: AuthorityProofInput): Promise<Record<string, string>>;
 export declare function authorityProofMessage(input: Required<Pick<AuthorityProofInput, "method" | "target" | "credential" | "timestamp" | "nonce">> & Pick<AuthorityProofInput, "body">): Promise<string>;
-export declare function encryptRelayRequest(store: GrantKeyStore, handle: string, binding: RelayBinding, operation: CollectionOperation, input: unknown, requestId?: string): Promise<EncryptedRelayOperationRequest>;
+export declare function encryptRelayRequest(store: GrantKeyStore, handle: string, binding: RelayBinding, operation: EncryptedRelayOperation, input: unknown, requestId?: string): Promise<EncryptedRelayOperationRequest>;
 export declare function decryptRelayResponse<Result>(store: GrantKeyStore, handle: string, binding: RelayBinding, request: EncryptedRelayOperationRequest, response: EncryptedRelayOperationResponse): Promise<{
     ok: true;
     result: Result;
 } | {
     ok: false;
-    error: {
-        code: string;
-        message: string;
-    };
+    problem: ConnectProblem;
 }>;
 export declare class RelayCryptoError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/** @internal Shared ECDH primitive used by the independently keyed file data plane. */
+export declare function deriveP256SharedSecret(privateKey: CryptoKey, peerPublicKey: string): Promise<ArrayBuffer>;
 export declare function validateGrantEncryption(encryption: GrantEncryption): void;

package/dist/crypto.js

@@ -1,4 +1,4 @@
-import { ENCRYPTED_RELAY_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, RELAY_ENCRYPTION_SUITE } from "@mdbase-dev/connect-protocol";
+import { ENCRYPTED_RELAY_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, RELAY_ENCRYPTION_SUITE, isConnectProblem } from "@mdbase-dev/connect-protocol";
 const DATABASE_NAME = "mdbase-connect-keys";
 const STORE_NAME = "grant-keys";
 const MAX_U64 = 18446744073709551615n;
@@ -198,9 +198,7 @@ export async function decryptRelayResponse(store, handle, binding, request, resp
         const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(plaintext));
         if (value?.ok === true && "result" in value)
             return value;
-        if (value?.ok === false
-            && typeof value.error?.code === "string"
-            && typeof value.error?.message === "string")
+        if (value?.ok === false && isConnectProblem(value.problem))
             return value;
         throw new Error("invalid response body");
     }
@@ -249,15 +247,7 @@ async function requireSigningKey(store, handle, expectedPublicKey) {
     return record;
 }
 async function deriveDirectionalKey(privateKey, binding, direction) {
-    let peer;
-    let shared;
-    try {
-        peer = await crypto.subtle.importKey("raw", toArrayBuffer(p256PublicKey(binding.encryption.connector_agreement_public_key)), { name: "ECDH", namedCurve: "P-256" }, false, []);
-        shared = await crypto.subtle.deriveBits({ name: "ECDH", public: peer }, privateKey, 256);
-    }
-    catch {
-        throw new RelayCryptoError("invalid_public_key", "The connector relay public key is invalid.");
-    }
+    const shared = await deriveP256SharedSecret(privateKey, binding.encryption.connector_agreement_public_key);
     const material = await crypto.subtle.importKey("raw", shared, "HKDF", false, ["deriveKey"]);
     const contextBytes = new TextEncoder().encode(context(binding));
     const salt = await crypto.subtle.digest("SHA-256", contextBytes);
@@ -268,6 +258,16 @@ async function deriveDirectionalKey(privateKey, binding, direction) {
         info: new TextEncoder().encode(direction === "request" ? REQUEST_INFO : RESPONSE_INFO)
     }, material, { name: "AES-GCM", length: 256 }, false, direction === "request" ? ["encrypt"] : ["decrypt"]);
 }
+/** @internal Shared ECDH primitive used by the independently keyed file data plane. */
+export async function deriveP256SharedSecret(privateKey, peerPublicKey) {
+    try {
+        const peer = await crypto.subtle.importKey("raw", toArrayBuffer(p256PublicKey(peerPublicKey)), { name: "ECDH", namedCurve: "P-256" }, false, []);
+        return await crypto.subtle.deriveBits({ name: "ECDH", public: peer }, privateKey, 256);
+    }
+    catch {
+        throw new RelayCryptoError("invalid_public_key", "The connector relay public key is invalid.");
+    }
+}
 function context(binding) {
     const value = binding.encryption;
     return [

package/dist/errors.d.ts

@@ -1,31 +1,45 @@
-import type { MdbaseDiagnostic, MdbaseOperationEnvelope } from "@mdbase-dev/connect-protocol";
-export type MdbaseRecoveryAction = "retry" | "reauthorize" | "refresh" | "resolve_outcome" | "fix_request" | "none";
-export interface MdbaseConnectErrorOptions {
+import { type ConnectOperationOutcome, type ConnectProblem, type ConnectProblemCode, type ConnectProblemDetailsByCode, type KnownConnectProblem, type MdbaseOperationEnvelope } from "@mdbase-dev/connect-protocol";
+interface ProblemOptions {
+    operationOutcome?: ConnectOperationOutcome;
+    traceId?: string;
     status?: number;
-    retryable?: boolean;
-    requiresAuthorization?: boolean;
-    outcomeUnknown?: boolean;
-    recovery?: MdbaseRecoveryAction;
-    details?: unknown;
     cause?: unknown;
 }
+type ProblemOptionsFor<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? ProblemOptions & {
+    details?: never;
+} : {} extends ConnectProblemDetailsByCode[Code] ? ProblemOptions & {
+    details?: ConnectProblemDetailsByCode[Code];
+} : ProblemOptions & {
+    details: ConnectProblemDetailsByCode[Code];
+};
+type ProblemArguments<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? [options?: ProblemOptionsFor<Code>] : {} extends ConnectProblemDetailsByCode[Code] ? [options?: ProblemOptionsFor<Code>] : [options: ProblemOptionsFor<Code>];
+export interface ConnectErrorContext {
+    status?: number;
+    cause?: unknown;
+}
+/** Internal carrier used while adapting throwing transports into public outcomes. */
 export declare class MdbaseConnectError extends Error {
-    readonly code: string;
+    readonly problem: ConnectProblem;
+    readonly code: ConnectProblem["code"];
     readonly status?: number;
-    readonly retryable: boolean;
-    readonly requiresAuthorization: boolean;
-    readonly outcomeUnknown: boolean;
-    readonly recovery: MdbaseRecoveryAction;
-    readonly details?: unknown;
-    constructor(code: string, message: string, options?: MdbaseConnectErrorOptions);
-}
-export declare class MdbaseOperationValidationError<Result = unknown> extends Error {
-    readonly diagnostics: MdbaseDiagnostic[];
-    readonly result: Result;
-    readonly code = "operation_invalid";
-    constructor(diagnostics: MdbaseDiagnostic[], result: Result);
+    constructor(problem: ConnectProblem, context?: ConnectErrorContext);
+    get retryable(): boolean;
+    get requiresAuthorization(): boolean;
+    get outcomeUnknown(): boolean;
+    get recovery(): "choose_collection" | "contact_support" | "fix_request" | "none" | "reauthorize" | "refresh" | "repair_collection" | "resolve_conflict" | "resolve_outcome" | "resume_connector_access" | "retry" | "upgrade_application" | "upgrade_collection" | "upgrade_connector";
+    get details(): unknown;
 }
-/** Return a valid operation result or throw while preserving every diagnostic. */
-export declare function unwrapOperation<Result>(envelope: MdbaseOperationEnvelope<Result>): Result;
-/** True only when repeating a read/poll is safe without asking the user. */
+export declare function connectProblem<Code extends ConnectProblemCode>(code: Code, message: string, ...[options]: ProblemArguments<Code>): KnownConnectProblem<Code>;
+export declare function unknownConnectProblem(serverCode: string, message: string, options?: ProblemOptions & {
+    details?: unknown;
+}): ConnectProblem;
+export declare function connectError<Code extends ConnectProblemCode>(code: Code, message: string, ...args: ProblemArguments<Code>): MdbaseConnectError;
+export declare function serverConnectError(serverCode: string, message: string, options?: ProblemOptions & {
+    details?: unknown;
+    status?: number;
+    cause?: unknown;
+}): MdbaseConnectError;
+export declare function operationProblem<Result>(envelope: MdbaseOperationEnvelope<Result>): KnownConnectProblem<"collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported" | "operation_invalid">;
+/** True only when repeating an operation is safe without asking the user. */
 export declare function isRetryableConnectError(error: unknown): boolean;
+export {};

package/dist/errors.js

@@ -1,83 +1,142 @@
+import { CONNECT_PROBLEM_CATALOG, CONNECT_PROBLEM_VERSION, normalizeConnectProblem } from "@mdbase-dev/connect-protocol";
+/** Internal carrier used while adapting throwing transports into public outcomes. */
 export class MdbaseConnectError extends Error {
+    problem;
     code;
     status;
-    retryable;
-    requiresAuthorization;
-    outcomeUnknown;
-    recovery;
-    details;
-    constructor(code, message, options = {}) {
-        super(message);
-        this.code = code;
+    constructor(problem, context = {}) {
+        super(problem.message, context.cause === undefined ? undefined : { cause: context.cause });
+        this.problem = problem;
         this.name = "MdbaseConnectError";
-        const classification = classifyConnectError(code, options.status);
-        this.status = options.status;
-        this.retryable = options.retryable ?? classification.retryable;
-        this.requiresAuthorization = options.requiresAuthorization ?? classification.requiresAuthorization;
-        this.outcomeUnknown = options.outcomeUnknown ?? classification.outcomeUnknown;
-        this.recovery = options.recovery ?? classification.recovery;
-        this.details = options.details;
-        if (options.cause !== undefined)
-            Object.defineProperty(this, "cause", { value: options.cause, configurable: true });
+        this.code = problem.code;
+        this.status = context.status;
     }
+    get retryable() {
+        return this.problem.recovery === "retry"
+            && this.problem.operation_outcome !== "unknown";
+    }
+    get requiresAuthorization() {
+        return this.problem.category === "authorization";
+    }
+    get outcomeUnknown() {
+        return this.problem.operation_outcome === "unknown";
+    }
+    get recovery() {
+        return this.problem.recovery;
+    }
+    get details() {
+        return this.problem.details;
+    }
+}
+export function connectProblem(code, message, ...[options = {}]) {
+    const definition = CONNECT_PROBLEM_CATALOG[code];
+    return {
+        problem_version: CONNECT_PROBLEM_VERSION,
+        code,
+        category: definition.category,
+        recovery: definition.recovery,
+        message,
+        ...(options.details === undefined ? {} : { details: options.details }),
+        ...(options.operationOutcome === undefined
+            ? {}
+            : { operation_outcome: options.operationOutcome }),
+        ...(options.traceId === undefined ? {} : { trace_id: options.traceId })
+    };
 }
-export class MdbaseOperationValidationError extends Error {
-    diagnostics;
-    result;
-    code = "operation_invalid";
-    constructor(diagnostics, result) {
-        super(diagnostics.filter((item) => item.severity === "error").map((item) => item.message).join(" ")
-            || diagnostics.map((item) => item.message).join(" ")
-            || "The collection rejected this operation.");
-        this.diagnostics = diagnostics;
-        this.result = result;
-        this.name = "MdbaseOperationValidationError";
+export function unknownConnectProblem(serverCode, message, options = {}) {
+    return normalizeConnectProblem(serverCode, message, {
+        details: options.details,
+        operation_outcome: options.operationOutcome,
+        trace_id: options.traceId
+    });
+}
+export function connectError(code, message, ...args) {
+    const options = args[0];
+    return new MdbaseConnectError(connectProblem(code, message, ...args), {
+        status: options?.status,
+        cause: options?.cause
+    });
+}
+export function serverConnectError(serverCode, message, options = {}) {
+    const { status, cause, ...problemOptions } = options;
+    return new MdbaseConnectError(normalizeConnectProblem(serverCode, message, {
+        details: problemOptions.details,
+        operation_outcome: problemOptions.operationOutcome,
+        trace_id: problemOptions.traceId
+    }), { status, cause });
+}
+export function operationProblem(envelope) {
+    const code = diagnosticProblemCode(envelope.diagnostics);
+    const message = diagnosticMessage(envelope.diagnostics);
+    if (code === "collection_version_unsupported") {
+        const versions = diagnosticVersions(envelope.diagnostics);
+        return connectProblem(code, message, {
+            operationOutcome: "rejected",
+            details: versions
+        });
     }
+    if (code !== "operation_invalid") {
+        return connectProblem(code, message, {
+            operationOutcome: "rejected",
+            details: { diagnostics: envelope.diagnostics }
+        });
+    }
+    return connectProblem(code, message, {
+        operationOutcome: "rejected",
+        details: {
+            diagnostics: envelope.diagnostics,
+            partial_result: envelope.result
+        }
+    });
+}
+function diagnosticProblemCode(diagnostics) {
+    const codes = new Set(diagnostics
+        .filter((diagnostic) => diagnostic.severity === "error")
+        .map((diagnostic) => diagnostic.code));
+    if (["migration_required", "migration_lossy", "unsupported_version"]
+        .some((code) => codes.has(code)))
+        return "collection_version_unsupported";
+    if (["invalid_config", "invalid_configuration", "missing_config", "missing_spec_version"]
+        .some((code) => codes.has(code)))
+        return "collection_configuration_invalid";
+    if ([
+        "duplicate_type",
+        "invalid_contract_definition",
+        "invalid_data_contract",
+        "invalid_type_definition",
+        "invalid_type_path"
+    ].some((code) => codes.has(code)))
+        return "collection_type_registry_invalid";
+    if (["collection_invalid", "collection_open_failed"]
+        .some((code) => codes.has(code)))
+        return "collection_invalid";
+    return "operation_invalid";
+}
+function diagnosticVersions(diagnostics) {
+    const source = diagnostics
+        .map((diagnostic) => diagnostic.details)
+        .find((details) => isRecord(details));
+    return {
+        current_version: typeof source?.current_version === "string"
+            ? source.current_version
+            : "0.2.x",
+        required_version: typeof source?.required_version === "string"
+            ? source.required_version
+            : "0.3.0"
+    };
 }
-/** Return a valid operation result or throw while preserving every diagnostic. */
-export function unwrapOperation(envelope) {
-    if (!envelope.valid)
-        throw new MdbaseOperationValidationError(envelope.diagnostics, envelope.result);
-    return envelope.result;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** True only when repeating a read/poll is safe without asking the user. */
+/** True only when repeating an operation is safe without asking the user. */
 export function isRetryableConnectError(error) {
-    if (error instanceof MdbaseConnectError)
-        return error.retryable && !error.outcomeUnknown;
-    return error instanceof TypeError;
+    return error instanceof MdbaseConnectError && error.retryable;
 }
-function classifyConnectError(code, status) {
-    const authorizationCodes = new Set([
-        "authorization_expired",
-        "direct_operation_rejected",
-        "encryption_required",
-        "insufficient_access",
-        "missing_grant_key",
-        "not_authorized",
-        "relay_authorization_expired"
-    ]);
-    const outcomeUnknown = code === "direct_outcome_unknown" || code === "pending_mutation_unresolved";
-    const requiresAuthorization = authorizationCodes.has(code) || status === 401;
-    const retryableCodes = new Set([
-        "connector_offline",
-        "discovery_failed",
-        "relay_unavailable",
-        "sync_failed",
-        "temporarily_unavailable",
-        "timeout"
-    ]);
-    const retryableStatus = status === 408 || status === 425 || status === 429 || (status !== undefined && status >= 500);
-    const retryable = !outcomeUnknown && !requiresAuthorization && (retryableCodes.has(code) || retryableStatus);
-    const recovery = outcomeUnknown
-        ? "resolve_outcome"
-        : requiresAuthorization
-            ? "reauthorize"
-            : code === "change_cursor_reset"
-                ? "refresh"
-                : retryable
-                    ? "retry"
-                    : status !== undefined && status >= 400 && status < 500
-                        ? "fix_request"
-                        : "none";
-    return { retryable, requiresAuthorization, outcomeUnknown, recovery };
+function diagnosticMessage(diagnostics) {
+    return diagnostics
+        .filter((item) => item.severity === "error")
+        .map((item) => item.message)
+        .join(" ")
+        || diagnostics.map((item) => item.message).join(" ")
+        || "The collection rejected this operation.";
 }

package/dist/file-crypto.d.ts

@@ -0,0 +1,25 @@
+import { type FileFrameHeader, type FileFrameKind, type FileTransferDirection } from "@mdbase-dev/connect-protocol";
+import { type GrantKeyStore, type RelayBinding } from "./crypto.js";
+export interface FileTransferBinding extends RelayBinding {
+    authorityId: string;
+    transferId: string;
+    direction: FileTransferDirection;
+}
+export declare class FileTransferCryptoError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Grant-bound, direction-separated cipher for one resumable file transfer. */
+export declare class GrantFileTransferCipher {
+    private readonly binding;
+    private readonly key;
+    private constructor();
+    static open(store: GrantKeyStore, handle: string, binding: FileTransferBinding): Promise<GrantFileTransferCipher>;
+    /** @internal Enables non-browser key-agreement adapters and compatibility tests. */
+    static fromSharedSecret(sharedSecret: BufferSource, binding: FileTransferBinding): Promise<GrantFileTransferCipher>;
+    encryptChunk(kind: FileFrameKind, header: FileFrameHeader, plaintext: Uint8Array): Promise<Uint8Array>;
+    decryptChunk(encoded: Uint8Array): Promise<Uint8Array>;
+    private validateHeader;
+}
+/** @internal Deterministic HKDF profile shared with connector authorities. */
+export declare function deriveFileTransferKey(sharedSecret: BufferSource, binding: FileTransferBinding): Promise<CryptoKey>;