@telecrypt-io/storage 0.5.27 → 0.5.29

package/dist/core/operations.js

@@ -10,12 +10,12 @@
  * config (persistent crypto store, session credentials, etc.) is
  * platform-specific and stays with the caller.
  */
-import { withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
+import { readFileEventMetadata, withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
 import { EventType, MatrixError, RoomCreateTypeField, RoomType, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
 import { Method } from "matrix-js-sdk/lib/http-api/method.js";
-import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./errors.js";
-import { waitForCondition } from "./poll.js";
+import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
+import { ConditionTimeoutError, waitForCondition } from "./poll.js";
 import { validateMatrixEventId } from "./constants.js";
 import { validateName } from "./validation.js";
 import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
@@ -27,15 +27,12 @@ import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markT
  * server-advised backoff. Mirrors the harness library suite's
  * `withRateLimitRetry`; must not mask non-rate-limit failures.
  */
-const RATE_LIMIT_RETRIES = 6;
 const RATE_LIMIT_DEFAULT_DELAY_MS = 15_000;
-const RATE_LIMIT_MAX_DELAY_MS = 30_000;
-const RATE_LIMIT_MAX_TOTAL_DELAY_MS = 90_000;
+// JavaScript timers cannot represent a longer delay reliably. The operation's
+// own deadline remains the authority that stops retrying.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const MAX_DELETION_ROOMS = 4096;
-const DELETION_REFRESH_CONCURRENCY = 8;
 const MAX_DELETION_DEPTH = 128;
-const MAX_FILE_VERSION_CHAIN = 128;
-const MAX_LIST_ITEMS = 10000;
 const DEFAULT_MUTATION_TIMEOUT_MS = 5 * 60_000;
 const MAX_MUTATION_TIMEOUT_MS = 15 * 60_000;
 function createOperationDeadline(options) {
@@ -80,24 +77,17 @@ async function raceOperationDeadline(deadline, pending, kind) {
     finally {
         if (onAbort)
             deadline.signal.removeEventListener("abort", onAbort);
-        void pending.catch(() => undefined);
     }
 }
 async function withOperationDeadline(options, operation, kind = "read") {
     const deadline = createOperationDeadline(options);
-    let pending;
     try {
         ensureOperationActive(deadline.signal);
-        pending = Promise.resolve().then(() => operation(deadline.signal));
+        const pending = Promise.resolve().then(() => operation(deadline.signal));
         return await raceOperationDeadline(deadline, pending, kind);
     }
     finally {
         deadline.close();
-        // A caller-facing deadline must not wait for a broken provider, but the
-        // late result remains observed so an ignored AbortSignal cannot create an
-        // unhandled rejection.
-        if (pending)
-            void pending.catch(() => undefined);
     }
 }
 function isRateLimited(error) {
@@ -108,16 +98,28 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
+function requiresMutationReconciliation(error) {
+    return (error instanceof MutationOutcomeUnknownError ||
+        error instanceof RoomCreationAmbiguousError ||
+        error instanceof RoomCleanupIncompleteError ||
+        (error instanceof Error &&
+            error.cleanupIncomplete === true));
+}
 async function withRateLimitRetry(operation, signal) {
-    let totalDelay = 0;
-    for (let attempt = 0;; attempt++) {
+    for (;;) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         try {
             return await operation();
         }
         catch (error) {
-            if (!isRateLimited(error) || attempt >= RATE_LIMIT_RETRIES)
+            // A mutation that may have committed, or whose compensating cleanup is
+            // incomplete, must be reconciled by its owner before any retry. A
+            // server rate-limit response does not make repeating room creation safe.
+            if (requiresMutationReconciliation(error)) {
+                throw error;
+            }
+            if (!isRateLimited(error))
                 throw error;
             // The server's retry_after_ms only covers one token; tree operations
             // need several (kick + leave + forget). Wait at least 15s so the
@@ -132,12 +134,7 @@ async function withRateLimitRetry(operation, signal) {
                     }
                 }
             }
-            retryAfter = Math.min(retryAfter, RATE_LIMIT_MAX_DELAY_MS);
-            const remaining = RATE_LIMIT_MAX_TOTAL_DELAY_MS - totalDelay;
-            if (remaining <= 0)
-                throw error;
-            retryAfter = Math.min(retryAfter, remaining);
-            totalDelay += retryAfter;
+            retryAfter = Math.min(retryAfter, MAX_TIMER_DELAY_MS);
             await new Promise((resolve, reject) => {
                 let timer;
                 const onAbort = () => {
@@ -170,10 +167,12 @@ async function resolveTree(storage, treeId, signal) {
             signal,
         });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("storage space not found");
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("storage space not found");
+        throw new StorageError("storage space lookup failed", { cause: error });
     }
 }
 function isMarkedTreeDeleted(storage, treeId) {
@@ -198,10 +197,12 @@ async function resolveFile(storage, tree, fileId, signal) {
     try {
         return await waitForCondition(() => (isMarkedFileDeleted(storage, tree.id, fileId) ? null : tree.getFile(fileId)), { timeoutMs: 15000, signal });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("file not found");
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("file not found");
+        throw new StorageError("file lookup failed", { cause: error });
     }
 }
 function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large") {
@@ -224,8 +225,8 @@ function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large")
         try {
             children = tree.getDirectories();
         }
-        catch {
-            throw new StorageError("could not enumerate storage space descendants safely");
+        catch (error) {
+            throw new StorageError("could not enumerate storage space descendants safely", { cause: error });
         }
         if (children.length > MAX_DELETION_ROOMS) {
             throw new StorageError(tooLargeMessage);
@@ -251,13 +252,13 @@ function assertTreeEmptyForDeletion(storage, tree, spaces) {
             .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id) &&
             !isConfirmedDeletedFile(storage.getClient(), tree.id, file));
     }
-    catch {
-        throw new StorageError("could not enumerate storage files safely");
+    catch (error) {
+        throw new StorageError("could not enumerate storage files safely", { cause: error });
     }
     if (files.length > 0)
         throw new NonEmptyTreeError(tree.id);
 }
-async function refreshDeletionRooms(storage, signal) {
+async function refreshDeletionRooms(storage, rootId, signal) {
     const client = storage.getClient();
     const http = client.http;
     // A real MatrixClient always exposes its authenticated HTTP transport. A
@@ -265,48 +266,31 @@ async function refreshDeletionRooms(storage, signal) {
     if (typeof http?.authedRequest !== "function") {
         throw new StorageError("delete graph refresh is unavailable");
     }
-    const roomIds = await storage.listJoinedRoomIds({ signal });
-    if (roomIds.length > MAX_DELETION_ROOMS)
-        throw new StorageError("delete graph is too large");
-    const joined = new Set(roomIds);
-    const roomIdsToRefresh = [];
-    // Matrix has no bounded endpoint that enumerates every invited/non-joined
-    // room carrying a space relation. Refresh every locally visible room and
-    // fail closed for an invite/knock/unknown membership; a joined external
-    // parent remains inspectable and is validated by validateDeletionGraph.
-    for (const room of client.getRooms()) {
-        if (!joined.has(room.roomId)) {
-            const membership = room.getMyMembership?.();
-            if (membership !== "join")
-                throw new StorageError("delete graph inventory is incomplete");
-            roomIdsToRefresh.push(room.roomId);
-        }
+    await storage.refreshRoomState(rootId, { signal });
+    if (signal?.aborted)
+        throw new StorageError("operation cancelled");
+    // The refreshed root owns its parent relation. Verify its one supported
+    // external parent directly; unrelated local rooms are outside this deletion.
+    const parentEvents = readRelationEvents(client, rootId, EventType.SpaceParent);
+    if (parentEvents === null)
+        throw new StorageError("delete graph is unsafe");
+    const parentIds = new Set();
+    for (const event of parentEvents) {
+        if (!isActiveRelationEvent(event))
+            continue;
+        const parentId = relationStateKey(event);
+        if (!parentId)
+            throw new StorageError("delete graph is unsafe");
+        if (parentId !== rootId)
+            parentIds.add(parentId);
     }
-    roomIdsToRefresh.push(...roomIds);
-    let nextRoom = 0;
-    let failed = false;
-    let firstError;
-    const refreshWorker = async () => {
-        while (!failed && !signal?.aborted) {
-            const roomId = roomIdsToRefresh[nextRoom++];
-            if (roomId === undefined)
-                return;
-            try {
-                await storage.refreshRoomState(roomId, { signal });
-            }
-            catch (error) {
-                failed = true;
-                firstError = error;
-                return;
-            }
-        }
-    };
-    const workerCount = Math.min(DELETION_REFRESH_CONCURRENCY, roomIdsToRefresh.length);
-    await Promise.all(Array.from({ length: workerCount }, () => refreshWorker()));
+    if (parentIds.size > 1)
+        throw new StorageError("delete graph is unsafe");
+    const parentId = parentIds.values().next().value;
+    if (parentId)
+        await storage.refreshRoomState(parentId, { signal });
     if (signal?.aborted)
         throw new StorageError("operation cancelled");
-    if (failed)
-        throw firstError;
 }
 async function refreshTreeSpaces(storage, spaces, signal) {
     for (const space of spaces) {
@@ -378,8 +362,8 @@ function validateDeletionGraph(client, root, ids, deletedRooms) {
         try {
             directories = tree.getDirectories();
         }
-        catch {
-            throw new StorageError("delete graph is unsafe");
+        catch (error) {
+            throw new StorageError("delete graph is unsafe", { cause: error });
         }
         for (const child of directories)
             addEdge(id, child.id);
@@ -420,31 +404,11 @@ function validateDeletionGraph(client, root, ids, deletedRooms) {
                 if (id !== root.id || externalParents.includes(parentId)) {
                     throw new StorageError("delete graph is unsafe");
                 }
-                externalParents.push(parentId);
-            }
-        }
-    }
-    const rooms = client.getRooms();
-    if (rooms.length > MAX_DELETION_ROOMS)
-        throw new StorageError("delete graph is too large");
-    for (const room of rooms) {
-        const parentId = room.roomId;
-        const childEvents = readRelationEvents(client, parentId, EventType.SpaceChild);
-        if (childEvents === null)
-            throw new StorageError("delete graph is unsafe");
-        for (const event of childEvents) {
-            if (!isActiveRelationEvent(event))
-                continue;
-            const childId = relationStateKey(event);
-            if (!childId)
-                throw new StorageError("delete graph is unsafe");
-            if (ids.has(childId) && !ids.has(parentId)) {
-                if (childId === root.id) {
-                    if (!externalParents.includes(parentId))
-                        externalParents.push(parentId);
-                    continue;
+                const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, id);
+                if (!childLink?.some((candidate) => isActiveRelationEvent(candidate) && relationStateKey(candidate, id) === id)) {
+                    throw new StorageError("delete graph is unsafe");
                 }
-                throw new StorageError("delete graph is unsafe");
+                externalParents.push(parentId);
             }
         }
     }
@@ -493,8 +457,10 @@ async function unlinkExternalParents(storage, rootId, externalParents, signal) {
         try {
             await relinkExternalParents(storage, rootId, externalParents, new AbortController().signal);
         }
-        catch {
-            throw new StorageError("delete graph unlink cleanup is incomplete");
+        catch (cleanupError) {
+            throw new StorageError("delete graph unlink cleanup is incomplete", {
+                cause: new AggregateError([error, cleanupError], "delete graph unlink and relink both failed", { cause: error }),
+            });
         }
         throw error;
     }
@@ -524,60 +490,78 @@ function isGoneError(error) {
         (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
 }
 async function deleteRoomDeterministically(storage, roomId, signal) {
-    const client = storage.getClient();
-    const tree = storage.getTree(roomId);
-    if (!tree)
-        throw new StorageError("delete graph is unsafe");
-    const self = client.getUserId();
-    if (!self)
-        throw new StorageError("delete graph is unsafe");
-    const members = await storage.listMembers(tree, { signal });
-    if (members.some((member) => member.userId !== self && member.role === "owner" &&
-        (member.membership === "join" || member.membership === "invite" || member.membership === "knock"))) {
-        throw new StorageError("delete will not kick another room owner");
-    }
-    for (const member of members) {
-        const membership = member.membership;
-        if (member.userId === self ||
-            (membership !== "join" && membership !== "invite" && membership !== "knock")) {
-            continue;
-        }
-        try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.kick(roomId, member.userId, "Room deleted"), signal), signal);
-        }
-        catch (error) {
-            if (isGoneError(error))
+    const completedRoomIds = [];
+    const markRoomMutationComplete = () => {
+        if (!completedRoomIds.includes(roomId))
+            completedRoomIds.push(roomId);
+    };
+    try {
+        const client = storage.getClient();
+        const tree = storage.getTree(roomId);
+        if (!tree)
+            throw new StorageError("delete graph is unsafe");
+        const self = client.getUserId();
+        if (!self)
+            throw new StorageError("delete graph is unsafe");
+        const members = await storage.listMembers(tree, { signal });
+        if (members.some((member) => member.userId !== self && member.role === "owner" &&
+            (member.membership === "join" || member.membership === "invite" || member.membership === "knock"))) {
+            throw new StorageError("delete will not kick another room owner");
+        }
+        for (const member of members) {
+            const membership = member.membership;
+            if (member.userId === self ||
+                (membership !== "join" && membership !== "invite" && membership !== "knock")) {
                 continue;
-            if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
-                const currentMembership = await storage.getRoomMembership(roomId, member.userId, { signal });
-                if (currentMembership === "leave" ||
-                    currentMembership === "ban" ||
-                    !currentMembership) {
+            }
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.kick(roomId, member.userId, "Room deleted"), signal), signal);
+                markRoomMutationComplete();
+            }
+            catch (error) {
+                if (isGoneError(error))
                     continue;
+                if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                    const currentMembership = await storage.getRoomMembership(roomId, member.userId, { signal });
+                    if (currentMembership === "leave" ||
+                        currentMembership === "ban" ||
+                        !currentMembership) {
+                        continue;
+                    }
                 }
+                throw error;
+            }
+        }
+        const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
+        if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(roomId), signal), signal);
+                markRoomMutationComplete();
+            }
+            catch (error) {
+                if (!isGoneError(error))
+                    throw error;
             }
-            throw error;
         }
-    }
-    const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
-    if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
         try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(roomId), signal), signal);
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(roomId), signal), signal);
+            markRoomMutationComplete();
         }
         catch (error) {
             if (!isGoneError(error))
                 throw error;
         }
-    }
-    try {
-        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(roomId), signal), signal);
+        removeRoomFromLocalStore(client, roomId);
+        markTreeDeleted(client, roomId);
     }
     catch (error) {
-        if (!isGoneError(error))
+        if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
             throw error;
+        if (completedRoomIds.length > 0) {
+            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped", { cause: error });
+        }
+        throw error;
     }
-    removeRoomFromLocalStore(client, roomId);
-    markTreeDeleted(client, roomId);
 }
 /**
  * The SDK normally evicts a room as part of forget(). Keep the local-store
@@ -585,14 +569,7 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
  * may otherwise leave a stale invite visible until the next sync.
  */
 function removeRoomFromLocalStore(client, roomId) {
-    try {
-        client.store?.removeRoom(roomId);
-    }
-    catch {
-        // Server-side leave/forget already completed; a store implementation that
-        // cannot evict synchronously must not turn authoritative cleanup into a
-        // false failure.
-    }
+    client.store?.removeRoom(roomId);
 }
 function isActiveMembership(membership) {
     return membership === "join" || membership === "invite";
@@ -602,12 +579,11 @@ function isRevocableMembership(membership) {
 }
 function safePartialDetail(error) {
     // Provider/Matrix errors can contain response bodies, URLs, or credentials.
-    // StorageError messages are authored by this package and are already
-    // bounded; retain those local policy details so callers still get useful
-    // owner/self-target diagnostics.
+    // StorageError messages are authored by this package; retain those local
+    // policy details so callers still get useful owner/self-target diagnostics.
     if (!(error instanceof StorageError) || error instanceof MutationOutcomeUnknownError)
         return undefined;
-    return error.message.length <= 256 ? error.message : undefined;
+    return error.message;
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
@@ -619,16 +595,12 @@ export async function createVault(storage, name, options) {
             tree = await withRateLimitRetry(() => storage.createTree(name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create vault failed");
+            throw new StorageError("create vault failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: tree.id, name };
@@ -666,7 +638,7 @@ export async function joinVault(storage, vaultId, options) {
                 membership = null;
             }
             else {
-                throw new StorageError("join failed");
+                throw new StorageError("join failed", { cause: err });
             }
         }
         if (membership === "join")
@@ -684,7 +656,7 @@ export async function joinVault(storage, vaultId, options) {
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("join failed");
+            throw new StorageError("join failed", { cause: err });
         }
         ensureOperationActive(signal);
         return { vaultId, joined: true };
@@ -720,8 +692,6 @@ export async function listPendingInvites(storage, options) {
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         const rooms = client.getRooms();
-        if (rooms.length > MAX_LIST_ITEMS)
-            throw new StorageError("invite list is too large");
         const invites = [];
         for (const room of rooms) {
             ensureOperationActive(signal);
@@ -840,7 +810,7 @@ export async function declineInvite(storage, vaultId, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("decline failed");
+            throw new StorageError("decline failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { vaultId, declined: true };
@@ -913,7 +883,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message === "share failed" ||
@@ -922,7 +892,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("share failed");
+                throw new StorageError("share failed", { cause: error });
             }
             return { vaultId, userId, role };
         }, operation.signal);
@@ -988,7 +958,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message.includes("owner") ||
@@ -996,7 +966,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("unshare failed");
+                throw new StorageError("unshare failed", { cause: error });
             }
             return { vaultId, userId, removed: true };
         }, operation.signal);
@@ -1012,10 +982,10 @@ export async function listMembers(storage, vaultId, options) {
         try {
             return await withRateLimitRetry(() => storage.listMembers(tree, { signal }), signal);
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("list members failed");
+            throw new StorageError("list members failed", { cause: error });
         }
     });
 }
@@ -1028,16 +998,12 @@ export async function listFiles(storage, treeId, options) {
             const files = tree
                 .listFiles()
                 .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id));
-            if (files.length > MAX_LIST_ITEMS)
-                throw new StorageError("file list is too large");
             return files.map((f) => ({ id: f.id, name: f.getName() }));
         }
         catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            if (error instanceof StorageError && error.message === "file list is too large")
-                throw error;
-            throw new StorageError("list files failed");
+            throw new StorageError("list files failed", { cause: error });
         }
     });
 }
@@ -1050,8 +1016,6 @@ export async function listSubfolders(storage, parentId, options) {
         const directories = tree
             .getDirectories()
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
-        if (directories.length > MAX_LIST_ITEMS)
-            throw new StorageError("folder list is too large");
         return directories.map((d) => ({ id: d.id, name: d.room.name }));
     });
 }
@@ -1064,16 +1028,12 @@ export async function createSubfolder(storage, parentId, name, options) {
             sub = await withRateLimitRetry(() => storage.createSubtree(tree, name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create folder failed");
+            throw new StorageError("create folder failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: sub.id, name };
@@ -1091,12 +1051,7 @@ async function renameTree(storage, treeId, name, options) {
                 const current = storage.getTree(treeId);
                 if (current?.room.name === name)
                     return current;
-                try {
-                    await storage.refreshRoomState(treeId, { signal });
-                }
-                catch {
-                    return null;
-                }
+                await storage.refreshRoomState(treeId, { signal });
                 const refreshed = storage.getTree(treeId);
                 return refreshed?.room.name === name ? refreshed : null;
             }, { timeoutMs: 15000, signal });
@@ -1106,7 +1061,7 @@ async function renameTree(storage, treeId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename failed");
+            throw new StorageError("rename failed", { cause: error });
         }
         return { id: treeId, name };
     }, "mutation");
@@ -1134,10 +1089,11 @@ async function deleteTree(storage, treeId, options) {
             const removedRooms = getDeletedTreeIds(client);
             let graph;
             try {
-                // Re-read every locally visible room before taking the immutable graph
-                // snapshot. Local MSC3089 relations and memberships can lag another
-                // session; deleting from that stale view can orphan shared descendants.
-                await refreshDeletionRooms(storage, operation.signal);
+                // Re-read the candidate graph and any external parents it identifies
+                // before taking the immutable graph snapshot. Unrelated rooms are not
+                // part of this operation and must not block deletion merely because
+                // their membership is not joined.
+                await refreshDeletionRooms(storage, tree.id, operation.signal);
                 const spaces = snapshotTreeSpaces(tree, "delete graph is too large");
                 const activeSpaces = spaces.filter((space) => !removedRooms.has(space.id));
                 const ids = new Set(activeSpaces.map((space) => space.id));
@@ -1151,13 +1107,9 @@ async function deleteTree(storage, treeId, options) {
                 graph = validateDeletionGraph(client, tree, ids, removedRooms);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError ||
-                    error instanceof MutationPartialError ||
-                    error instanceof NonEmptyTreeError)
-                    throw error;
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             // Keep external parent links intact until the room deletion succeeds.
             // Unlinking first would silently detach a live vault on failure.
@@ -1165,16 +1117,9 @@ async function deleteTree(storage, treeId, options) {
                 await unlinkExternalParents(storage, tree.id, graph.externalParents, operation.signal);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
-                if (error instanceof StorageError && error.message === "delete graph unlink cleanup is incomplete") {
-                    throw error;
-                }
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             try {
                 await deleteRoomDeterministically(storage, tree.id, operation.signal);
@@ -1186,16 +1131,14 @@ async function deleteTree(storage, treeId, options) {
                 try {
                     await relinkExternalParents(storage, tree.id, graph.externalParents, new AbortController().signal);
                 }
-                catch {
-                    throw new StorageError("delete cleanup is incomplete");
+                catch (cleanupError) {
+                    throw new StorageError("delete cleanup is incomplete", {
+                        cause: new AggregateError([error, cleanupError], "delete and external-parent relink both failed", { cause: error }),
+                    });
                 }
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             return { id: treeId, deleted: true };
         }, operation.signal);
@@ -1235,7 +1178,7 @@ export async function renameFile(storage, treeId, fileId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename file failed");
+            throw new StorageError("rename file failed", { cause: error });
         }
         return { id: fileId, name };
     }, "mutation");
@@ -1254,11 +1197,11 @@ async function resolveFileVersions(branch, signal) {
     try {
         history = await branch.getVersionHistory();
     }
-    catch {
-        throw new StorageError("could not resolve file version history safely");
+    catch (error) {
+        throw new StorageError("could not resolve file version history safely", { cause: error });
     }
-    if (!Array.isArray(history) || history.length === 0 || history.length > MAX_FILE_VERSION_CHAIN) {
-        throw new StorageError("file version history is invalid or too large");
+    if (!Array.isArray(history) || history.length === 0) {
+        throw new StorageError("file version history is invalid");
     }
     const eventIds = new Set();
     const mediaIds = new Set();
@@ -1272,8 +1215,8 @@ async function resolveFileVersions(branch, signal) {
         try {
             validateMatrixEventId(version.id, "file version event ID");
         }
-        catch {
-            throw new StorageError("file version history contains an invalid event ID");
+        catch (error) {
+            throw new StorageError("file version history contains an invalid event ID", { cause: error });
         }
         if (eventIds.has(version.id)) {
             throw new StorageError("file version history contains a cycle");
@@ -1283,17 +1226,14 @@ async function resolveFileVersions(branch, signal) {
         try {
             fileInfo = await version.getFileInfo();
         }
-        catch {
-            throw new StorageError("could not resolve encrypted file version safely");
+        catch (error) {
+            throw new StorageError("could not resolve encrypted file version safely", { cause: error });
         }
         const mediaId = fileInfo?.info?.url;
         if (typeof mediaId !== "string" || mediaId.length === 0) {
             throw new StorageError("encrypted file version has no media identifier");
         }
         mediaIds.add(mediaId);
-        if (mediaIds.size > MAX_FILE_VERSION_CHAIN) {
-            throw new StorageError("file media version history is too large");
-        }
         versions.push({ branch: version, mediaId });
     }
     return versions;
@@ -1316,7 +1256,7 @@ async function deleteFileMedia(storage, mediaIds, signal) {
             throw error;
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("delete file media failed");
+        throw new StorageError("delete file media failed", { cause: error });
     }
 }
 export async function deleteFile(storage, treeId, fileId, options) {
@@ -1341,9 +1281,9 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             if (signal.aborted) {
-                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled");
+                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled", { cause: error });
             }
-            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped");
+            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped", { cause: error });
         }
         try {
             await waitForCondition(async () => {
@@ -1357,7 +1297,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             const detail = "Matrix deletion completed but the inactive file state could not be verified";
-            throw new MutationPartialError("delete file", completedIds, detail);
+            throw new MutationPartialError("delete file", completedIds, detail, { cause: error });
         }
         for (const { branch: version } of versions) {
             markFileDeleted(storage.getClient(), tree.id, version.id);
@@ -1376,7 +1316,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("upload failed");
+            throw new StorageError("upload failed", { cause: error });
         });
         // The create-file request is acknowledged before the event necessarily
         // arrives in this client's sync timeline. A caller can otherwise report a
@@ -1395,7 +1335,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
         catch (error) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
-            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally");
+            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: fileId, name, mimetype };
@@ -1410,11 +1350,11 @@ export async function downloadFile(storage, treeId, fileId, options) {
             result = await storage.downloadFile(branch, signal);
         }
         catch (error) {
-            if (error instanceof UndecryptableFileError)
+            if (error instanceof StorageError)
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("download failed");
+            throw new StorageError("download failed", { cause: error });
         }
         ensureOperationActive(signal);
         return {
@@ -1444,41 +1384,21 @@ export async function getFileDetails(storage, treeId, fileId, options) {
         let size = null;
         let createdAt = null;
         let updatedAt = null;
-        try {
-            ensureOperationActive(signal);
-            const { info } = await branch.getFileInfo();
-            if (info) {
-                if (typeof info["mimetype"] === "string")
-                    mimetype = info["mimetype"];
-                if (typeof info["size"] === "number")
-                    size = info["size"];
-            }
-        }
-        catch {
-            if (signal.aborted)
-                throw new StorageError("operation cancelled");
-            // Partial metadata is fine — UI shows "—" for unknown fields.
-        }
         try {
             ensureOperationActive(signal);
             const event = await branch.getFileEvent();
-            const content = event.getContent();
-            const infoBlock = content["info"];
-            if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
-                mimetype = infoBlock["mimetype"];
-            }
-            if (size == null && typeof infoBlock?.["size"] === "number") {
-                size = infoBlock["size"];
-            }
-            const eventAny = event;
-            const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
-            createdAt = tsToIso(ts);
+            const metadata = readFileEventMetadata(event.getContent());
+            mimetype = metadata.mimetype;
+            size = metadata.size;
+            createdAt = tsToIso(event.getTs());
             updatedAt = createdAt;
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            // Same as above.
+            if (error instanceof StorageError)
+                throw error;
+            throw new StorageError("get file details failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { name, mimetype, size, createdAt, updatedAt };
@@ -1498,8 +1418,8 @@ async function getTreeDetails(storage, treeId, signal) {
         try {
             memberCount = room.getJoinedMemberCount();
         }
-        catch {
-            memberCount = null;
+        catch (error) {
+            throw new StorageError("member count lookup failed", { cause: error });
         }
     }
     return {