@nestm/storage 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/workspace/storage-workspace.js

@@ -0,0 +1,849 @@
+import { StorageClient } from '../storage.client.js';
+import { isCanonicalStorageEtag } from '../storage-etag.js';
+import { StorageErrorCode } from '../storage.error.js';
+import { STORAGE_WORKSPACE_MAX_CURSOR_BYTES, decodeStorageWorkspaceCursor, issueStorageWorkspaceCursor, resolveStorageWorkspaceCursorConfiguration, } from './storage-workspace.cursor.js';
+import { sanitizeWorkspaceError, workspaceError, } from './storage-workspace.error.js';
+import { assertWorkspacePath, containsControlCharacter, isPathInside, joinWorkspacePath, workspaceBasename, } from './storage-workspace.path.js';
+import { DEFAULT_STORAGE_WORKSPACE_LIMITS, STORAGE_WORKSPACE_PERMISSIONS, } from './storage-workspace.types.js';
+const DEFAULT_PERMISSIONS = new Set([
+    'list',
+    'read',
+    'search',
+]);
+const PERMISSION_VALUES = new Set(STORAGE_WORKSPACE_PERMISSIONS);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const WORKSPACE_CONSTRUCTOR = Symbol('StorageWorkspace.constructor');
+function operationOptions(options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    return {
+        ...(options.retries !== undefined && { retries: options.retries }),
+        ...(options.signal !== undefined && { signal: options.signal }),
+        ...(options.timeout !== undefined && { timeout: options.timeout }),
+    };
+}
+function positiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${label} must be a positive safe integer.`, { permanent: true });
+    }
+    return value;
+}
+function assertEtag(etag, operation) {
+    if (!isCanonicalStorageEtag(etag)) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} requires a canonical bare etag of at most 1,024 bytes.`, { permanent: true });
+    }
+}
+function writeModeOf(options) {
+    const candidate = options;
+    const mode = candidate?.mode;
+    if (mode === 'create' || mode === 'overwrite' || mode === 'replace') {
+        if (mode !== 'replace' && candidate !== undefined && 'etag' in candidate) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace write options may include an etag only in replace mode.', { permanent: true });
+        }
+        return mode;
+    }
+    throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace write mode must be create, overwrite, or replace.', { permanent: true });
+}
+function hasExplicitMode(options, expected, operation) {
+    if (typeof options !== 'object' || options === null) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} options must be an object.`, { permanent: true });
+    }
+    if (!('mode' in options)) {
+        return false;
+    }
+    if (options.mode !== expected) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} mode must be ${expected}.`, { permanent: true });
+    }
+    if ('etag' in options) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} ${expected} options must not include an etag.`, { permanent: true });
+    }
+    return true;
+}
+function resolveLimits(requested, parent) {
+    const baseline = parent ?? DEFAULT_STORAGE_WORKSPACE_LIMITS;
+    const next = {
+        cursorTtlMs: requested?.cursorTtlMs ?? baseline.cursorTtlMs,
+        maxCursorBytes: requested?.maxCursorBytes ?? baseline.maxCursorBytes,
+        maxPageSize: requested?.maxPageSize ?? baseline.maxPageSize,
+        maxPathBytes: requested?.maxPathBytes ?? baseline.maxPathBytes,
+        maxReadBytes: requested?.maxReadBytes ?? baseline.maxReadBytes,
+        maxSearchResults: requested?.maxSearchResults ?? baseline.maxSearchResults,
+        maxSearchScan: requested?.maxSearchScan ?? baseline.maxSearchScan,
+        maxWriteBytes: requested?.maxWriteBytes ?? baseline.maxWriteBytes,
+    };
+    for (const [name, value] of Object.entries(next)) {
+        positiveSafeInteger(value, `limits.${name}`);
+        const parentValue = baseline[name];
+        if (parent !== undefined && value > parentValue) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `Child workspace limit "${name}" cannot exceed its parent limit.`, { permanent: true });
+        }
+    }
+    if (next.maxCursorBytes > STORAGE_WORKSPACE_MAX_CURSOR_BYTES) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `limits.maxCursorBytes cannot exceed ${STORAGE_WORKSPACE_MAX_CURSOR_BYTES}.`, { permanent: true });
+    }
+    return Object.freeze(next);
+}
+function resolvePermissions(requested, parent) {
+    const baseline = parent ?? DEFAULT_PERMISSIONS;
+    const values = requested === undefined ? [...baseline] : [...requested];
+    const permissions = new Set();
+    for (const permission of values) {
+        if (!PERMISSION_VALUES.has(permission)) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `Unknown workspace permission "${String(permission)}".`, { permanent: true });
+        }
+        if (parent !== undefined && !parent.has(permission)) {
+            throw workspaceError(StorageErrorCode.UNAUTHORIZED, `Child workspace cannot add the "${permission}" permission.`, { permanent: true });
+        }
+        permissions.add(permission);
+    }
+    return permissions;
+}
+function logicalFile(metadata, path) {
+    if (!Number.isSafeInteger(metadata.size) ||
+        metadata.size < 0 ||
+        typeof metadata.contentType !== 'string' ||
+        metadata.contentType.length === 0 ||
+        (metadata.etag !== undefined && !isCanonicalStorageEtag(metadata.etag)) ||
+        (metadata.lastModified !== undefined &&
+            !Number.isFinite(new Date(metadata.lastModified).getTime()))) {
+        throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned malformed file metadata.', { permanent: true });
+    }
+    return {
+        contentType: metadata.contentType,
+        ...(metadata.etag !== undefined && { etag: metadata.etag }),
+        kind: 'file',
+        ...(metadata.lastModified !== undefined && {
+            lastModified: new Date(metadata.lastModified),
+        }),
+        name: workspaceBasename(path),
+        path,
+        size: metadata.size,
+    };
+}
+function logicalDirectory(path) {
+    const normalized = path.endsWith('/') ? path.slice(0, -1) : path;
+    return {
+        kind: 'directory',
+        name: normalized.length === 0 ? '' : workspaceBasename(normalized),
+        path: normalized,
+    };
+}
+function segmentGlobMatches(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let starValueIndex = -1;
+    while (valueIndex < value.length) {
+        if (patternIndex < pattern.length &&
+            (pattern[patternIndex] === '?' ||
+                pattern[patternIndex] === value[valueIndex])) {
+            patternIndex += 1;
+            valueIndex += 1;
+        }
+        else if (pattern[patternIndex] === '*') {
+            starIndex = patternIndex;
+            patternIndex += 1;
+            starValueIndex = valueIndex;
+        }
+        else if (starIndex !== -1) {
+            patternIndex = starIndex + 1;
+            starValueIndex += 1;
+            valueIndex = starValueIndex;
+        }
+        else {
+            return false;
+        }
+    }
+    while (pattern[patternIndex] === '*') {
+        patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+}
+function globMatches(pattern, value) {
+    const patternSegments = pattern.split('/');
+    const valueSegments = value.split('/');
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let globstarIndex = -1;
+    let globstarValueIndex = -1;
+    while (valueIndex < valueSegments.length) {
+        const patternSegment = patternSegments[patternIndex];
+        const valueSegment = valueSegments[valueIndex];
+        if (patternSegment === '**') {
+            globstarIndex = patternIndex;
+            globstarValueIndex = valueIndex;
+            patternIndex += 1;
+        }
+        else if (patternSegment !== undefined &&
+            valueSegment !== undefined &&
+            segmentGlobMatches(patternSegment, valueSegment)) {
+            patternIndex += 1;
+            valueIndex += 1;
+        }
+        else if (globstarIndex !== -1) {
+            patternIndex = globstarIndex + 1;
+            globstarValueIndex += 1;
+            valueIndex = globstarValueIndex;
+        }
+        else {
+            return false;
+        }
+    }
+    while (patternSegments[patternIndex] === '**') {
+        patternIndex += 1;
+    }
+    return patternIndex === patternSegments.length;
+}
+function searchMatches(query, path, match, caseInsensitive) {
+    const candidate = caseInsensitive ? path.toLowerCase() : path;
+    const needle = caseInsensitive ? query.toLowerCase() : query;
+    if (match === 'exact') {
+        return candidate === needle;
+    }
+    if (match === 'substring') {
+        return candidate.includes(needle);
+    }
+    return globMatches(needle, candidate);
+}
+async function collectBoundedText(stream, announcedSize, maxBytes, path) {
+    if (announcedSize > maxBytes) {
+        await stream.cancel().catch(() => undefined);
+        throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeds the ${maxBytes}-byte read limit.`, { path, permanent: true });
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done) {
+                break;
+            }
+            if (result.value.byteLength === 0) {
+                throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned an empty non-terminal body chunk.', { path, permanent: true });
+            }
+            size += result.value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeded the ${maxBytes}-byte read limit.`, { path, permanent: true });
+            }
+            chunks.push(result.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `Workspace file "${path}" is not valid UTF-8 text.`, { path, permanent: true });
+    }
+}
+async function collectBoundedBytes(stream, announcedSize, maxBytes, path) {
+    if (announcedSize > maxBytes) {
+        await stream.cancel().catch(() => undefined);
+        throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeds the ${maxBytes}-byte limit.`, { path, permanent: true });
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done) {
+                break;
+            }
+            if (result.value.byteLength === 0) {
+                throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned an empty non-terminal body chunk.', { path, permanent: true });
+            }
+            size += result.value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeded the ${maxBytes}-byte limit.`, { path, permanent: true });
+            }
+            chunks.push(result.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+class StorageWorkspaceImplementation {
+    #state;
+    #permissions;
+    #limits;
+    /** @internal Construct workspaces through {@link mountStorageWorkspace}. */
+    constructor(constructorToken, state, permissions, limits) {
+        if (constructorToken !== WORKSPACE_CONSTRUCTOR) {
+            throw workspaceError(StorageErrorCode.UNAUTHORIZED, 'StorageWorkspace must be created by mountStorageWorkspace().', { permanent: true });
+        }
+        this.#state = state;
+        this.#permissions = permissions;
+        this.#limits = limits;
+    }
+    get permissions() {
+        return new Set(this.#permissions);
+    }
+    get limits() {
+        return Object.freeze({ ...this.#limits });
+    }
+    allows(permission) {
+        return this.#permissions.has(permission);
+    }
+    async stat(path, options) {
+        this.#require('read');
+        const logicalPath = this.#filePath(path);
+        try {
+            const metadata = await this.#state.client.head(this.#scope(logicalPath), options);
+            this.#assertResultPath(metadata.key, logicalPath);
+            return logicalFile(metadata, logicalPath);
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'stat',
+                path: logicalPath,
+            });
+        }
+    }
+    async readText(path, options) {
+        this.#require('read');
+        const logicalPath = this.#filePath(path);
+        const maxBytes = options?.maxBytes ?? this.#limits.maxReadBytes;
+        positiveSafeInteger(maxBytes, 'maxBytes');
+        if (maxBytes > this.#limits.maxReadBytes) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `maxBytes cannot exceed the ${this.#limits.maxReadBytes}-byte workspace read limit.`, { path: logicalPath, permanent: true });
+        }
+        try {
+            const object = await this.#state.client.downloadStream(this.#scope(logicalPath), operationOptions(options));
+            this.#assertResultPath(object.key, logicalPath);
+            const text = await collectBoundedText(object.body, object.size, maxBytes, logicalPath);
+            return { ...logicalFile(object, logicalPath), text };
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'read',
+                path: logicalPath,
+            });
+        }
+    }
+    async readBytes(path, options) {
+        this.#require('read');
+        const logicalPath = this.#filePath(path);
+        const maxBytes = options?.maxBytes ?? this.#limits.maxReadBytes;
+        positiveSafeInteger(maxBytes, 'maxBytes');
+        if (maxBytes > this.#limits.maxReadBytes) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `maxBytes cannot exceed the ${this.#limits.maxReadBytes}-byte workspace read limit.`, { path: logicalPath, permanent: true });
+        }
+        try {
+            const object = await this.#state.client.downloadStream(this.#scope(logicalPath), operationOptions(options));
+            this.#assertResultPath(object.key, logicalPath);
+            const bytes = await collectBoundedBytes(object.body, object.size, maxBytes, logicalPath);
+            return { ...logicalFile(object, logicalPath), bytes };
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'read',
+                path: logicalPath,
+            });
+        }
+    }
+    async list(options = {}) {
+        this.#require('list');
+        const continuation = options.cursor !== undefined
+            ? await decodeStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), 'list', options.cursor)
+            : undefined;
+        if (continuation !== undefined &&
+            ((options.directory !== undefined &&
+                options.directory !== continuation.directory) ||
+                (options.limit !== undefined && options.limit !== continuation.limit) ||
+                (options.recursive !== undefined &&
+                    options.recursive !== continuation.recursive))) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace cursor conflicts with the supplied list query.', { permanent: true });
+        }
+        const directory = this.#directoryPath(continuation?.directory ?? options.directory ?? '');
+        const limit = this.#pageLimit(continuation?.limit ?? options.limit, this.#limits.maxPageSize);
+        const recursive = continuation?.recursive ?? options.recursive === true;
+        const scopedDirectory = this.#scopeDirectory(directory);
+        try {
+            const page = await this.#state.client.list({
+                ...(continuation !== undefined && {
+                    cursor: continuation.backendCursor,
+                }),
+                ...(!recursive && { delimiter: '/' }),
+                limit,
+                ...operationOptions(options),
+                prefix: scopedDirectory,
+            });
+            if (page.items.length + (page.prefixes?.length ?? 0) > limit) {
+                this.#malformedPage();
+            }
+            if (page.cursor !== undefined && page.cursor.length === 0) {
+                this.#malformedPage();
+            }
+            if (page.cursor !== undefined &&
+                (page.items.length + (page.prefixes?.length ?? 0) === 0 ||
+                    page.cursor === continuation?.backendCursor)) {
+                this.#malformedPage();
+            }
+            const entries = [];
+            for (const item of page.items) {
+                const path = this.#unscoped(item.key);
+                if (!isPathInside(directory, path)) {
+                    this.#providerScopeFailure();
+                }
+                if (!recursive) {
+                    const relative = directory.length === 0 ? path : path.slice(directory.length + 1);
+                    if (relative.includes('/')) {
+                        this.#malformedPage();
+                    }
+                }
+                entries.push(logicalFile(item, path));
+            }
+            for (const prefix of page.prefixes ?? []) {
+                const path = this.#unscoped(prefix.endsWith('/') ? prefix.slice(0, -1) : prefix);
+                if (!isPathInside(directory, path)) {
+                    this.#providerScopeFailure();
+                }
+                if (!recursive) {
+                    const relative = directory.length === 0 ? path : path.slice(directory.length + 1);
+                    if (relative.includes('/')) {
+                        this.#malformedPage();
+                    }
+                }
+                entries.push(logicalDirectory(path));
+            }
+            return {
+                ...(page.cursor !== undefined && {
+                    cursor: await issueStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), {
+                        backendCursor: page.cursor,
+                        directory,
+                        limit,
+                        operation: 'list',
+                        recursive,
+                    }),
+                }),
+                entries,
+            };
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'list',
+                ...(directory.length > 0 && { path: directory }),
+            });
+        }
+    }
+    async search(query, options = {}) {
+        this.#require('search');
+        const continuation = options.cursor !== undefined
+            ? await decodeStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), 'search', options.cursor)
+            : undefined;
+        if (continuation !== undefined &&
+            ((query.length > 0 && query !== continuation.query) ||
+                (options.directory !== undefined &&
+                    options.directory !== continuation.directory) ||
+                (options.match !== undefined && options.match !== continuation.match) ||
+                (options.caseInsensitive !== undefined &&
+                    options.caseInsensitive !== continuation.caseInsensitive) ||
+                (options.limit !== undefined && options.limit !== continuation.limit))) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace cursor conflicts with the supplied search query.', { permanent: true });
+        }
+        query = continuation?.query ?? query;
+        if (typeof query !== 'string' || query.length === 0) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Search query must be a non-empty string.', { permanent: true });
+        }
+        if (query.includes('\\') || containsControlCharacter(query)) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Search query contains forbidden characters.', { permanent: true });
+        }
+        if (encoder.encode(query).byteLength > this.#limits.maxPathBytes) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, 'Search query exceeds the workspace path-byte limit.', { permanent: true });
+        }
+        const directory = this.#directoryPath(continuation?.directory ?? options.directory ?? '');
+        const match = continuation?.match ?? options.match ?? 'glob';
+        if (match !== 'glob' && match !== 'substring' && match !== 'exact') {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Search match must be glob, substring, or exact.', { permanent: true });
+        }
+        const caseInsensitive = continuation?.caseInsensitive ?? options.caseInsensitive === true;
+        const limit = this.#pageLimit(continuation?.limit ?? options.limit, this.#limits.maxSearchResults);
+        const prior = {
+            backendCursor: continuation?.backendCursor,
+            scanned: continuation?.scanned ?? 0,
+        };
+        return this.#searchPage(query, {
+            caseInsensitive,
+            directory,
+            limit,
+            match,
+            operation: operationOptions(options),
+            state: prior,
+        });
+    }
+    async writeFile(path, body, options) {
+        const mode = writeModeOf(options);
+        this.#require(mode === 'overwrite' ? 'write' : mode);
+        const logicalPath = this.#filePath(path);
+        if (typeof body !== 'string' && !(body instanceof Uint8Array)) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace writes accept only strings or Uint8Array bodies.', { path: logicalPath, permanent: true });
+        }
+        const size = typeof body === 'string'
+            ? encoder.encode(body).byteLength
+            : body.byteLength;
+        if (size > this.#limits.maxWriteBytes) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace write exceeds the ${this.#limits.maxWriteBytes}-byte limit.`, { path: logicalPath, permanent: true });
+        }
+        try {
+            const common = {
+                ...(options.contentType !== undefined && {
+                    contentType: options.contentType,
+                }),
+                ...(options.metadata !== undefined && { metadata: options.metadata }),
+                ...operationOptions(options),
+            };
+            let result;
+            if (mode === 'overwrite') {
+                result = await this.#state.client.upload(this.#scope(logicalPath), body, common);
+            }
+            else if (mode === 'create') {
+                result = await this.#state.client.uploadConditional(this.#scope(logicalPath), body, { ...common, condition: { type: 'create' } });
+            }
+            else {
+                const etag = options.etag;
+                assertEtag(etag, 'Replace');
+                result = await this.#state.client.uploadConditional(this.#scope(logicalPath), body, {
+                    ...common,
+                    condition: { etag, type: 'replace' },
+                });
+            }
+            this.#assertResultPath(result.key, logicalPath);
+            return logicalFile(result, logicalPath);
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: mode,
+                path: logicalPath,
+            });
+        }
+    }
+    async copyFile(source, destination, options) {
+        this.#require('copy');
+        this.#require('read');
+        const overwrite = hasExplicitMode(options, 'overwrite', 'Copy');
+        this.#require(overwrite ? 'write' : 'create');
+        const sourcePath = this.#filePath(source, 'source path');
+        const destinationPath = this.#filePath(destination, 'destination path');
+        if (sourcePath === destinationPath) {
+            throw workspaceError(StorageErrorCode.CONFLICT, 'Copy destination must differ from its source.', { path: destinationPath, permanent: true });
+        }
+        if (overwrite) {
+            return this.#copyOverwrite(sourcePath, destinationPath, options);
+        }
+        const conditional = options;
+        assertEtag(conditional.etag, 'Copy');
+        const capabilities = this.#state.client.capabilities;
+        if (capabilities.conditionalCreate?.resultEtag !== true ||
+            capabilities.conditionalRead?.etag !== true) {
+            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe copy requires exact-ETag reads and create-only uploads that return an ETag.', { operation: 'copy', path: destinationPath, permanent: true });
+        }
+        return this.#copyCreate(sourcePath, destinationPath, conditional);
+    }
+    async moveFile(source, destination, options) {
+        this.#require('move');
+        this.#require('read');
+        this.#require('create');
+        this.#require('delete');
+        if (typeof options !== 'object' || options === null || 'mode' in options) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace move supports only an ETag-conditional mutation.', { permanent: true });
+        }
+        const sourcePath = this.#filePath(source, 'source path');
+        const destinationPath = this.#filePath(destination, 'destination path');
+        if (sourcePath === destinationPath) {
+            throw workspaceError(StorageErrorCode.CONFLICT, 'Move destination must differ from its source.', { path: destinationPath, permanent: true });
+        }
+        const capabilities = this.#state.client.capabilities;
+        if (capabilities.conditionalCreate?.resultEtag !== true ||
+            capabilities.conditionalDelete?.etag !== true ||
+            capabilities.conditionalRead?.etag !== true) {
+            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe move requires exact-ETag reads, create-only uploads that return an ETag, and conditional delete.', { operation: 'move', permanent: true });
+        }
+        assertEtag(options.etag, 'Move');
+        const copied = await this.#copyCreate(sourcePath, destinationPath, options);
+        if (copied.etag === undefined) {
+            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe move requires the destination provider to return an etag.', { path: destinationPath, permanent: true });
+        }
+        try {
+            await this.#state.client.deleteConditional(this.#scope(sourcePath), {
+                condition: { etag: options.etag },
+                ...operationOptions(options),
+            });
+            return copied;
+        }
+        catch {
+            throw workspaceError(StorageErrorCode.CONFLICT, `Workspace move could not confirm source deletion; destination "${destinationPath}" was retained. Inspect both paths before retrying.`, {
+                applied: true,
+                appliedEtag: copied.etag,
+                operation: 'move',
+                path: destinationPath,
+                permanent: true,
+            });
+        }
+    }
+    async deleteFile(path, options) {
+        this.#require('delete');
+        const logicalPath = this.#filePath(path);
+        const unconditional = hasExplicitMode(options, 'unconditional', 'Delete');
+        if (unconditional) {
+            this.#require('write');
+        }
+        try {
+            if (unconditional) {
+                await this.#state.client.delete(this.#scope(logicalPath), operationOptions(options));
+            }
+            else {
+                const conditional = options;
+                assertEtag(conditional.etag, 'Delete');
+                await this.#state.client.deleteConditional(this.#scope(logicalPath), {
+                    condition: { etag: conditional.etag },
+                    ...operationOptions(conditional),
+                });
+            }
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'delete',
+                path: logicalPath,
+            });
+        }
+    }
+    mount(directory, options = {}) {
+        const path = this.#directoryPath(directory);
+        if (path.length === 0) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'A child workspace mount directory must not be empty.', { permanent: true });
+        }
+        return new StorageWorkspaceImplementation(WORKSPACE_CONSTRUCTOR, {
+            ...this.#state,
+            prefix: joinWorkspacePath(this.#state.prefix, path),
+        }, resolvePermissions(options.permissions, this.#permissions), resolveLimits(options.limits, this.#limits));
+    }
+    async #copyCreate(sourcePath, destinationPath, options) {
+        try {
+            const source = await this.#state.client.downloadConditional(this.#scope(sourcePath), {
+                condition: { etag: options.etag },
+                ...operationOptions(options),
+            });
+            this.#assertResultPath(source.key, sourcePath);
+            if (source.etag !== options.etag) {
+                await source.body.cancel().catch(() => undefined);
+                throw workspaceError(StorageErrorCode.PROVIDER, 'Conditional read returned an unexpected source ETag.', { operation: 'copy', path: sourcePath, permanent: true });
+            }
+            const bytes = await collectBoundedBytes(source.body, source.size, this.#limits.maxWriteBytes, sourcePath);
+            const result = await this.#state.client.uploadConditional(this.#scope(destinationPath), bytes, {
+                condition: { type: 'create' },
+                contentType: source.contentType,
+                ...(source.metadata !== undefined && { metadata: source.metadata }),
+                ...operationOptions(options),
+            });
+            this.#assertResultPath(result.key, destinationPath);
+            return logicalFile(result, destinationPath);
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'copy',
+                path: destinationPath,
+            });
+        }
+    }
+    async #copyOverwrite(sourcePath, destinationPath, options) {
+        try {
+            const source = await this.#state.client.downloadStream(this.#scope(sourcePath), operationOptions(options));
+            this.#assertResultPath(source.key, sourcePath);
+            const bytes = await collectBoundedBytes(source.body, source.size, this.#limits.maxWriteBytes, sourcePath);
+            const result = await this.#state.client.upload(this.#scope(destinationPath), bytes, {
+                contentType: source.contentType,
+                ...(source.metadata !== undefined && { metadata: source.metadata }),
+                ...operationOptions(options),
+            });
+            this.#assertResultPath(result.key, destinationPath);
+            return logicalFile(result, destinationPath);
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'copy',
+                path: destinationPath,
+            });
+        }
+    }
+    async #searchPage(query, context) {
+        const entries = [];
+        let backendCursor = context.state.backendCursor;
+        let scanned = context.state.scanned;
+        try {
+            while (entries.length < context.limit &&
+                scanned < this.#limits.maxSearchScan) {
+                const remaining = this.#limits.maxSearchScan - scanned;
+                const remainingResults = context.limit - entries.length;
+                const page = await this.#state.client.list({
+                    ...(backendCursor !== undefined && { cursor: backendCursor }),
+                    limit: Math.min(this.#limits.maxPageSize, remaining, remainingResults),
+                    ...context.operation,
+                    prefix: this.#scopeDirectory(context.directory),
+                });
+                const requested = Math.min(this.#limits.maxPageSize, remaining, remainingResults);
+                if (page.items.length > requested) {
+                    this.#malformedPage();
+                }
+                if ((page.prefixes?.length ?? 0) > 0) {
+                    this.#malformedPage();
+                }
+                if (page.cursor !== undefined && page.cursor.length === 0) {
+                    this.#malformedPage();
+                }
+                if (page.cursor !== undefined &&
+                    (page.items.length === 0 || page.cursor === backendCursor)) {
+                    this.#malformedPage();
+                }
+                for (let index = 0; index < page.items.length; index += 1) {
+                    const item = page.items[index];
+                    if (item === undefined) {
+                        continue;
+                    }
+                    scanned += 1;
+                    const path = this.#unscoped(item.key);
+                    if (!isPathInside(context.directory, path)) {
+                        this.#providerScopeFailure();
+                    }
+                    if (searchMatches(query, context.directory.length === 0
+                        ? path
+                        : path.slice(context.directory.length + 1), context.match, context.caseInsensitive)) {
+                        entries.push(logicalFile(item, path));
+                    }
+                    if (entries.length === context.limit ||
+                        scanned === this.#limits.maxSearchScan) {
+                        break;
+                    }
+                }
+                backendCursor = page.cursor;
+                if (backendCursor === undefined) {
+                    break;
+                }
+            }
+            const hasMore = backendCursor !== undefined;
+            if (scanned >= this.#limits.maxSearchScan && hasMore) {
+                throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Search exceeded the ${this.#limits.maxSearchScan}-object scan limit.`, { permanent: true });
+            }
+            const nextBackendCursor = backendCursor;
+            return {
+                ...(nextBackendCursor !== undefined && {
+                    cursor: await issueStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), {
+                        backendCursor: nextBackendCursor,
+                        caseInsensitive: context.caseInsensitive,
+                        directory: context.directory,
+                        limit: context.limit,
+                        match: context.match,
+                        operation: 'search',
+                        query,
+                        scanned,
+                    }),
+                }),
+                entries,
+            };
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'search',
+                ...(context.directory.length > 0 && { path: context.directory }),
+            });
+        }
+    }
+    #require(permission) {
+        if (!this.#permissions.has(permission)) {
+            throw workspaceError(StorageErrorCode.UNAUTHORIZED, `Workspace does not allow ${permission} operations.`, { permanent: true });
+        }
+    }
+    #filePath(path, label = 'path') {
+        return assertWorkspacePath(path, this.#limits.maxPathBytes, {
+            allowRoot: false,
+            label,
+        });
+    }
+    #directoryPath(path) {
+        return assertWorkspacePath(path, this.#limits.maxPathBytes, {
+            allowRoot: true,
+            label: 'directory',
+        });
+    }
+    #scope(path) {
+        return `${this.#state.prefix}/${path}`;
+    }
+    #scopeDirectory(directory) {
+        return directory.length === 0
+            ? `${this.#state.prefix}/`
+            : `${this.#state.prefix}/${directory}/`;
+    }
+    #unscoped(key) {
+        const scoped = `${this.#state.prefix}/`;
+        if (!key.startsWith(scoped)) {
+            this.#providerScopeFailure();
+        }
+        const path = key.slice(scoped.length);
+        return assertWorkspacePath(path, this.#limits.maxPathBytes, {
+            allowRoot: false,
+            label: 'backend result path',
+        });
+    }
+    #assertResultPath(key, expected) {
+        if (this.#unscoped(key) !== expected) {
+            this.#providerScopeFailure();
+        }
+    }
+    #providerScopeFailure() {
+        throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned data outside the mounted workspace.', { permanent: true });
+    }
+    #malformedPage() {
+        throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned a malformed workspace page.', { permanent: true });
+    }
+    #pageLimit(value, maximum) {
+        const limit = value ?? maximum;
+        positiveSafeInteger(limit, 'limit');
+        if (limit > maximum) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `limit cannot exceed the workspace maximum of ${maximum}.`, { permanent: true });
+        }
+        return limit;
+    }
+    #cursorBinding() {
+        return {
+            limits: this.#limits,
+            prefix: this.#state.prefix,
+            store: this.#state.client.name,
+        };
+    }
+}
+export function mountStorageWorkspace(client, options) {
+    const limits = resolveLimits(options.limits);
+    const prefix = assertWorkspacePath(options.prefix, limits.maxPathBytes, {
+        allowRoot: false,
+        label: 'workspace prefix',
+    });
+    return new StorageWorkspaceImplementation(WORKSPACE_CONSTRUCTOR, {
+        client,
+        cursor: resolveStorageWorkspaceCursorConfiguration(options.cursor),
+        prefix,
+    }, resolvePermissions(options.permissions), limits);
+}
+/** @deprecated Prefer {@link mountStorageWorkspace}. */
+export const createStorageWorkspace = mountStorageWorkspace;
+//# sourceMappingURL=storage-workspace.js.map