@h-ai/storage 1.0.0-beta.21 → 1.0.0-beta.23

package/dist/node.js

@@ -1,20 +1,22 @@
-import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-FK7KRCML.js';
-export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-FK7KRCML.js';
-import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-JAJYHGLI.js';
-export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-JAJYHGLI.js';
+import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-WOVOQXRY.js';
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-WOVOQXRY.js';
+import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-RXYTWURA.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-RXYTWURA.js';
 export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './chunk-6YG3N3CW.js';
 import process from 'node:process';
 import { core, err, ok } from '@h-ai/core';
 import { Buffer } from 'node:buffer';
 import * as crypto from 'node:crypto';
-import { createHash, timingSafeEqual } from 'node:crypto';
+import { timingSafeEqual, createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { Readable } from 'node:stream';
+import { finished, Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { S3Client, HeadBucketCommand, CreateBucketCommand, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, CopyObjectCommand, DeleteObjectsCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { getSystemErrorMessage } from 'node:util';
 
 function toStorageDeleteResult(summary) {
   if (summary.failures.length === 0)
@@ -30,6 +32,68 @@ function toStorageDeleteResult(summary) {
     }
   };
 }
+async function uploadWithSource(data, signal, write) {
+  const readable = data instanceof Readable ? data : void 0;
+  if (readable) {
+    const cleanup = finished(readable, { readable: true, writable: false }, () => cleanup());
+  }
+  let sourceFailure;
+  function failReading(cause) {
+    sourceFailure = new Error("Storage upload source failed", { cause });
+    throw sourceFailure;
+  }
+  function track(source) {
+    return {
+      [Symbol.asyncIterator]() {
+        let iterator;
+        try {
+          iterator = source[Symbol.asyncIterator]();
+        } catch (cause) {
+          return failReading(cause);
+        }
+        return {
+          async next() {
+            try {
+              return await iterator.next();
+            } catch (cause) {
+              return failReading(cause);
+            }
+          },
+          return: iterator.return?.bind(iterator)
+        };
+      }
+    };
+  }
+  try {
+    const input = typeof data === "string" || data instanceof Uint8Array || readable ? data : track(data);
+    const result = await write(input);
+    if (result.success)
+      return result;
+    const { cause } = result.error;
+    const readFailure = sourceFailure;
+    const failedInput = readFailure !== void 0 && cause === readFailure;
+    const originalCause = failedInput ? readFailure.cause : cause;
+    if (signal?.aborted && (Object.is(originalCause, signal.reason) || originalCause instanceof Error && originalCause.name === "AbortError")) {
+      return err({
+        ...result.error,
+        message: storageM("storage_uploadCanceled"),
+        cause: signal.reason
+      });
+    }
+    if (failedInput || readable?.errored && readable.errored === cause) {
+      return err({
+        ...HaiStorageError.UPLOAD_FAILED,
+        message: storageM("storage_uploadSourceReadFailed"),
+        cause: originalCause,
+        ...result.error.ext && { ext: result.error.ext }
+      });
+    }
+    return result;
+  } finally {
+    if (readable && !readable.readableEnded && !readable.destroyed)
+      readable.destroy();
+  }
+}
 async function* toByteStream(data, signal) {
   signal?.throwIfAborted();
   if (typeof data === "string" || data instanceof Uint8Array) {
@@ -38,6 +102,7 @@ async function* toByteStream(data, signal) {
   }
   const iterator = data[Symbol.asyncIterator]();
   let completed = false;
+  let failed = false;
   try {
     while (true) {
       signal?.throwIfAborted();
@@ -63,61 +128,27 @@ async function* toByteStream(data, signal) {
       yield result.value;
     }
     signal?.throwIfAborted();
+  } catch (error) {
+    failed = true;
+    throw error;
   } finally {
     if (!completed && iterator.return) {
-      if (signal?.aborted)
-        void Promise.resolve(iterator.return()).catch(() => {
+      const closed = Promise.resolve().then(() => iterator.return?.());
+      if (failed || signal?.aborted)
+        void closed.catch(() => {
         });
       else
-        await iterator.return();
+        await closed;
     }
   }
 }
 
-// src/providers/storage-operation-log.ts
-function normalizePayloadValue(value) {
-  if (value instanceof Uint8Array) {
-    return { byteLength: value.byteLength };
-  }
-  return value;
-}
-function stringifyOperationPayload(payload, maxLength) {
-  if (maxLength <= 0) {
-    return "";
-  }
-  try {
-    const text = JSON.stringify(payload, (_key, value) => {
-      if (typeof value === "bigint") {
-        return value.toString();
-      }
-      if (typeof value === "function") {
-        return "[Function]";
-      }
-      return normalizePayloadValue(value);
-    });
-    return text.length > maxLength ? `${text.slice(0, maxLength)}...` : text;
-  } catch {
-    const text = String(payload);
-    return text.length > maxLength ? `${text.slice(0, maxLength)}...` : text;
-  }
-}
-function logStorageOperation(logger4, config, category, operation, payload) {
-  if (!config?.[category]) {
-    return;
-  }
-  logger4[config.level]("Storage operation executed", {
-    category,
-    operation,
-    payload: stringifyOperationPayload(payload, config.maxLength)
-  });
-}
-
 // src/providers/storage-provider-local.ts
 var logger = core.logger.child({ module: "storage", scope: "provider-local" });
 var PATH_SEGMENT_SPLIT_REGEX = /[\\/]+/;
 var METADATA_DIRECTORY = ".hai-storage-meta";
 function toStorageError(error, key) {
-  const e = error;
+  const e = error ?? {};
   if (e.code === "EEXIST") {
     return {
       ...HaiStorageError.ALREADY_EXISTS,
@@ -258,9 +289,6 @@ function createLocalProvider() {
     }
     return target;
   }
-  function logOperation(category, operation, payload) {
-    logStorageOperation(logger, config?.operationLog, category, operation, payload);
-  }
   function metadataKey(filePath, stat2) {
     return path.relative(getConfig().root, path.join(path.dirname(filePath), METADATA_DIRECTORY, `${metadataGeneration(stat2)}.meta.json`));
   }
@@ -287,7 +315,6 @@ function createLocalProvider() {
           if (error.code !== "ENOENT")
             throw error;
         }
-        logOperation("write", "file.put", { key, options });
         const dir2 = path.dirname(filePath);
         await fsp.mkdir(dir2, { recursive: true, mode: cfg.directoryMode });
         temporaryPath = `${filePath}.${crypto.randomUUID()}.upload.tmp`;
@@ -329,19 +356,18 @@ function createLocalProvider() {
               await fsp.unlink(previousMetadataPath);
           } catch (error) {
             if (error.code !== "ENOENT")
-              logger.warn("Obsolete local metadata cleanup failed", { key });
+              logger.warn("Obsolete local metadata cleanup failed");
           }
         }
         return ok(metadata);
       } catch (error) {
-        logger.warn("Put file failed", { key, error });
         return err(toStorageError(error, key));
       } finally {
         if (temporaryPath)
           await fsp.unlink(temporaryPath).catch(() => {
           });
         if (preparedMetadataPath && !published)
-          await fsp.unlink(preparedMetadataPath).catch(() => logger.warn("Unpublished local metadata cleanup failed", { key }));
+          await fsp.unlink(preparedMetadataPath).catch(() => logger.warn("Unpublished local metadata cleanup failed"));
       }
     },
     async get(key, options = {}) {
@@ -368,7 +394,6 @@ function createLocalProvider() {
       }
       try {
         const filePath = await fullPath(key);
-        logOperation("read", "file.getStream", { key, options });
         options.signal?.throwIfAborted();
         const stat2 = await fsp.stat(filePath);
         if (stat2.isDirectory()) {
@@ -397,7 +422,6 @@ function createLocalProvider() {
       }
       try {
         const filePath = await fullPath(key);
-        logOperation("read", "file.head", { key });
         for (let attempt = 0; attempt < 3; attempt++) {
           const stat2 = await fsp.stat(filePath, { bigint: true });
           if (stat2.isDirectory()) {
@@ -420,17 +444,9 @@ function createLocalProvider() {
           try {
             customMetadata = JSON.parse(serializedMetadata);
           } catch {
-            logger.warn("Invalid local metadata record", {
-              key,
-              generation: metadataGeneration(stat2)
-            });
             return err(HaiStorageError.OPERATION_FAILED, storageM("storage_metadataInvalid"));
           }
           if (!isMetadataRecord(customMetadata)) {
-            logger.warn("Invalid local metadata shape", {
-              key,
-              generation: metadataGeneration(stat2)
-            });
             return err(HaiStorageError.OPERATION_FAILED, storageM("storage_metadataInvalid"));
           }
           return ok({
@@ -458,7 +474,6 @@ function createLocalProvider() {
       }
       try {
         const filePath = await fullPath(key);
-        logOperation("read", "file.exists", { key });
         await fsp.access(filePath, fs.constants.F_OK);
         return ok(true);
       } catch (error) {
@@ -480,26 +495,22 @@ function createLocalProvider() {
       try {
         const filePath = await fullPath(key);
         const generationKey = metadataKey(filePath, await fsp.stat(filePath, { bigint: true }));
-        logOperation("write", "file.delete", { key });
-        logger.debug("Deleting file", { key });
         await fsp.unlink(filePath);
         try {
           await fsp.unlink(await fullPath(generationKey));
         } catch (error) {
           if (error.code !== "ENOENT")
-            logger.warn("Deleted object metadata cleanup failed", { key });
+            logger.warn("Deleted object metadata cleanup failed");
         }
         return ok(void 0);
       } catch (error) {
         if (error.code === "ENOENT") {
           return ok(void 0);
         }
-        logger.warn("Delete file failed", { key, error });
         return err(toStorageError(error, key));
       }
     },
     async deleteMany(keys) {
-      logOperation("write", "file.deleteMany", { count: keys.length, keys });
       const summary = { deletedKeys: [], failures: [] };
       const uniqueKeys = [
         ...new Set(keys)
@@ -531,7 +542,6 @@ function createLocalProvider() {
       return toStorageDeleteResult(summary);
     },
     async copy(sourceKey, destKey, options = {}) {
-      logOperation("write", "file.copy", { sourceKey, destKey, options });
       const source = await file.head(sourceKey);
       if (!source.success)
         return source;
@@ -554,7 +564,6 @@ function createLocalProvider() {
         if (typeof prefix !== "string" || typeof delimiter !== "string" || !Number.isInteger(maxKeys) || maxKeys < 1 || maxKeys > 1e3 || Buffer.from(prefix).toString("utf8") !== prefix || Buffer.from(delimiter).toString("utf8") !== delimiter) {
           return err(HaiStorageError.INVALID_LIST_OPTIONS, storageM("storage_listOptionsInvalid"));
         }
-        logOperation("read", "dir.list", { options });
         safePath(cfg.root, prefix);
         const root = await fsp.realpath(cfg.root);
         const scope = crypto.createHash("sha256").update(JSON.stringify([root, prefix, delimiter])).digest("hex");
@@ -647,7 +656,6 @@ function createLocalProvider() {
       }
       try {
         const dirPath = await fullPath(prefix);
-        logOperation("write", "dir.delete", { prefix });
         await fsp.rm(dirPath, { recursive: true, force: true });
         return ok(void 0);
       } catch (error) {
@@ -659,16 +667,13 @@ function createLocalProvider() {
     }
   };
   const presign = {
-    async getUrl(key, options) {
-      logOperation("read", "presign.getUrl", { key, options });
+    async getUrl() {
       return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
-    async putUrl(key, options) {
-      logOperation("write", "presign.putUrl", { key, options });
+    async putUrl() {
       return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
-    publicUrl(key) {
-      logOperation("read", "presign.publicUrl", { key });
+    publicUrl() {
       return null;
     }
   };
@@ -686,20 +691,19 @@ function createLocalProvider() {
       }
       try {
         config = cfg;
-        logger.info("Connecting local provider", { root: cfg.root });
+        logger.debug("Connecting local provider");
         await fsp.mkdir(cfg.root, { recursive: true, mode: cfg.directoryMode });
         config = { ...cfg, root: await fsp.realpath(cfg.root) };
         connected = true;
-        logger.info("Local provider connected", { root: cfg.root });
+        logger.debug("Local provider connected");
         return ok(void 0);
       } catch (error) {
-        logger.error("Local provider connect failed", { error });
         config = null;
         return err(toStorageError(error));
       }
     },
     async close() {
-      logger.info("Local provider disconnected");
+      logger.debug("Local provider disconnected");
       config = null;
       connected = false;
     },
@@ -718,8 +722,47 @@ var RETRYABLE_DELETE_CODES = /* @__PURE__ */ new Set([
   "SlowDown",
   "RequestTimeout"
 ]);
+var uploadDiagnostics = new AsyncLocalStorage();
+var UPLOAD_COMMANDS = /* @__PURE__ */ new Set([
+  "PutObject",
+  "CreateMultipartUpload",
+  "UploadPart",
+  "CompleteMultipartUpload",
+  "AbortMultipartUpload"
+]);
+function observeUploadRequests(client) {
+  client.middlewareStack.add((next, context) => async (args) => {
+    const diagnostics = uploadDiagnostics.getStore();
+    if (!diagnostics)
+      return next(args);
+    const operation = context.commandName?.replace(/Command$/, "");
+    const input = args.input;
+    if (!operation || !UPLOAD_COMMANDS.has(operation) || !input || typeof input !== "object" || !("Bucket" in input) || input.Bucket !== diagnostics.bucket || !("Key" in input) || input.Key !== diagnostics.key) {
+      return next(args);
+    }
+    try {
+      const response = await next(args);
+      if (operation === "UploadPart" && (!("ETag" in response.output) || !response.output.ETag)) {
+        const { httpStatusCode, requestId } = response.output.$metadata;
+        const partNumber = "PartNumber" in input && typeof input.PartNumber === "number" ? input.PartNumber : void 0;
+        throw Object.assign(new Error("S3 upload part response is missing ETag"), {
+          name: "MissingETag",
+          partNumber,
+          $metadata: { httpStatusCode, requestId }
+        });
+      }
+      return response;
+    } catch (cause) {
+      if (operation === "AbortMultipartUpload")
+        diagnostics.cleanup = { cause };
+      else
+        diagnostics.failure ??= { cause, operation };
+      throw cause;
+    }
+  }, { step: "initialize", name: "haiStorageObserveUploadRequests" });
+}
 function toStorageError2(error, key) {
-  const e = error;
+  const e = error ?? {};
   if (e.name === "PreconditionFailed" || e.$metadata?.httpStatusCode === 412) {
     return {
       ...HaiStorageError.ALREADY_EXISTS,
@@ -738,7 +781,7 @@ function toStorageError2(error, key) {
       cause: error
     };
   }
-  if (e.name === "AccessDenied" || e.Code === "AccessDenied") {
+  if (e.name === "AccessDenied" || e.Code === "AccessDenied" || e.$metadata?.httpStatusCode === 403) {
     return {
       ...HaiStorageError.PERMISSION_DENIED,
       message: storageM("storage_permissionDenied", {
@@ -843,9 +886,6 @@ function createS3Provider() {
   function fullKey(key) {
     return withPrefix(key, getConfig().prefix);
   }
-  function logOperation(category, operation, payload) {
-    logStorageOperation(logger2, config?.operationLog, category, operation, payload);
-  }
   const file = {
     async put(key, data, options = {}) {
       try {
@@ -865,19 +905,19 @@ function createS3Provider() {
           ContentDisposition: options.contentDisposition,
           IfNoneMatch: options.ifNoneMatch
         };
-        logOperation("write", "file.put", {
-          key,
-          fullPath,
-          byteLength: buffered ? size : void 0,
-          options
-        });
         if (buffered) {
           await s3Client.send(new PutObjectCommand({ ...params, Body: body }), { abortSignal: options.signal });
         } else {
+          const diagnostics = { bucket: s3Config.bucket, key: fullPath };
           async function* counted() {
-            for await (const chunk of toByteStream(data, options.signal)) {
-              size += chunk.byteLength;
-              yield chunk;
+            try {
+              for await (const chunk of toByteStream(data, options.signal)) {
+                size += chunk.byteLength;
+                yield chunk;
+              }
+            } catch (cause) {
+              diagnostics.failure ??= { cause };
+              throw cause;
             }
           }
           const stream = Readable.from(counted(), { objectMode: false });
@@ -888,13 +928,32 @@ function createS3Provider() {
             if (options.signal?.aborted)
               abort();
             const { Upload } = await import('@aws-sdk/lib-storage');
-            await new Upload({
+            const upload = new Upload({
               client: s3Client,
               params: { ...params, Body: stream },
-              queueSize: 2,
+              partSize: s3Config.multipart.partSizeBytes,
+              queueSize: s3Config.multipart.queueSize,
               leavePartsOnError: false,
               abortController: controller
-            }).done();
+            });
+            await uploadDiagnostics.run(diagnostics, () => upload.done());
+          } catch (cause) {
+            const failure = diagnostics.failure;
+            const cleanup = diagnostics.cleanup;
+            const original = cleanup && failure && Object.is(cause, cleanup.cause) ? failure.cause : cause;
+            const error = toStorageError2(original, key);
+            const s3Operation = failure && Object.is(failure.cause, original) ? failure.operation : void 0;
+            if (s3Operation || cleanup) {
+              error.ext = {
+                ...error.ext,
+                s3Operation,
+                ...cleanup && {
+                  cleanupPending: true,
+                  cleanupError: toStorageError2(cleanup.cause)
+                }
+              };
+            }
+            return err(error);
           } finally {
             options.signal?.removeEventListener("abort", abort);
             stream.destroy();
@@ -932,7 +991,6 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
-        logOperation("read", "file.getStream", { key, fullPath, options });
         let Range;
         if (options.rangeStart !== void 0 || options.rangeEnd !== void 0) {
           const start = options.rangeStart ?? 0;
@@ -961,7 +1019,6 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
-        logOperation("read", "file.head", { key, fullPath });
         const response = await s3Client.send(new HeadObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath
@@ -979,7 +1036,6 @@ function createS3Provider() {
       }
     },
     async exists(key) {
-      logOperation("read", "file.exists", { key });
       const result = await file.head(key);
       if (result.success) {
         return ok(true);
@@ -994,7 +1050,6 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
-        logOperation("write", "file.delete", { key, fullPath });
         await s3Client.send(new DeleteObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath
@@ -1008,7 +1063,6 @@ function createS3Provider() {
       try {
         const s3Client = getClient("deleteMany");
         const s3Config = getConfig();
-        logOperation("write", "file.deleteMany", { count: keys.length, keys });
         const uniqueKeys = [
           ...new Set(keys)
         ];
@@ -1110,13 +1164,6 @@ function createS3Provider() {
           s3Config.bucket,
           ...sourceFullPath.split("/")
         ].map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
-        logOperation("write", "file.copy", {
-          sourceKey,
-          destKey,
-          sourceFullPath,
-          destFullPath,
-          options
-        });
         await s3Client.send(new CopyObjectCommand({
           Bucket: s3Config.bucket,
           CopySource: copySource,
@@ -1136,7 +1183,6 @@ function createS3Provider() {
       try {
         const s3Client = getClient();
         const s3Config = getConfig();
-        logOperation("read", "dir.list", { options });
         const response = await s3Client.send(new ListObjectsV2Command({
           Bucket: s3Config.bucket,
           Prefix: withPrefix(options.prefix ?? "", s3Config.prefix) || void 0,
@@ -1165,7 +1211,6 @@ function createS3Provider() {
     },
     async delete(prefix) {
       try {
-        logOperation("write", "dir.delete", { prefix });
         let continuationToken;
         do {
           const listResult = await dir.list({
@@ -1198,7 +1243,6 @@ function createS3Provider() {
         const s3Client = getClient("presign");
         const s3Config = getConfig();
         const fullPath = fullKey(key);
-        logOperation("read", "presign.getUrl", { key, fullPath, options });
         const basePath = publicBasePath;
         const command = new GetObjectCommand({
           Bucket: s3Config.bucket,
@@ -1224,7 +1268,6 @@ function createS3Provider() {
         const s3Client = getClient("presign");
         const s3Config = getConfig();
         const fullPath = fullKey(key);
-        logOperation("write", "presign.putUrl", { key, fullPath, options });
         const basePath = publicBasePath;
         const command = new PutObjectCommand({
           Bucket: s3Config.bucket,
@@ -1249,7 +1292,6 @@ function createS3Provider() {
         return null;
       }
       const fullPath = fullKey(key);
-      logOperation("read", "presign.publicUrl", { key, fullPath });
       return `${s3Config.publicUrl.replace(TRAILING_SLASHES_REGEX, "")}/${fullPath}`;
     }
   };
@@ -1268,11 +1310,7 @@ function createS3Provider() {
       try {
         await closeClients();
         config = cfg;
-        logger2.info("Connecting S3 provider", {
-          bucket: cfg.bucket,
-          region: cfg.region,
-          endpoint: cfg.endpoint ? core.sanitize.sanitizeUrl(cfg.endpoint) : void 0
-        });
+        logger2.debug("Connecting S3 provider");
         const clientConfig = {
           region: cfg.region,
           endpoint: cfg.endpoint,
@@ -1286,6 +1324,7 @@ function createS3Provider() {
           }
         };
         client = new S3Client(clientConfig);
+        observeUploadRequests(client);
         deleteClient = new S3Client({ ...clientConfig, maxAttempts: 1 });
         if (cfg.publicEndpoint) {
           const endpoint = new URL(cfg.publicEndpoint);
@@ -1311,7 +1350,7 @@ function createS3Provider() {
                   CreateBucketConfiguration: { LocationConstraint: cfg.region }
                 }
               }));
-              logger2.info("S3 bucket created", { bucket: cfg.bucket });
+              logger2.debug("S3 bucket created");
             } catch (createError) {
               if (!(createError instanceof Error && createError.name === "BucketAlreadyOwnedByYou"))
                 throw createError;
@@ -1326,10 +1365,9 @@ function createS3Provider() {
         }));
         config = cfg;
         ready = true;
-        logger2.info("S3 provider connected", { bucket: cfg.bucket });
+        logger2.debug("S3 provider connected");
         return ok(void 0);
       } catch (error) {
-        logger2.error("S3 provider connect failed", { error });
         const original = toStorageError2(error);
         try {
           await closeClients();
@@ -1385,9 +1423,136 @@ var checksum = {
     return ok(actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes));
   }
 };
+var logger3 = core.logger.child({ module: "storage", scope: "operations" });
+var ERROR_NAME = /^[\w:-]{1,80}$/;
+var FAILURE_REASONS = {
+  [HaiStorageError.CONNECTION_FAILED.code]: "Storage connection or cleanup failed",
+  [HaiStorageError.OPERATION_FAILED.code]: "Storage operation failed",
+  [HaiStorageError.NOT_FOUND.code]: "Storage object was not found",
+  [HaiStorageError.ALREADY_EXISTS.code]: "Destination object already exists",
+  [HaiStorageError.PERMISSION_DENIED.code]: "Storage access was denied",
+  [HaiStorageError.QUOTA_EXCEEDED.code]: "Storage quota or disk space was exhausted",
+  [HaiStorageError.INVALID_PATH.code]: "Storage path was invalid",
+  [HaiStorageError.IO_ERROR.code]: "Storage read or write failed",
+  [HaiStorageError.NETWORK_ERROR.code]: "Storage network request failed",
+  [HaiStorageError.NOT_INITIALIZED.code]: "Storage provider was not initialized",
+  [HaiStorageError.UNSUPPORTED_TYPE.code]: "Storage provider type was unsupported",
+  [HaiStorageError.CONFIG_ERROR.code]: "Storage configuration was invalid",
+  [HaiStorageError.PRESIGN_FAILED.code]: "Could not sign a storage URL",
+  [HaiStorageError.UPLOAD_FAILED.code]: "Could not read the upload source",
+  [HaiStorageError.DOWNLOAD_FAILED.code]: "Storage download failed",
+  [HaiStorageError.CHECKSUM_FAILED.code]: "Could not calculate the checksum",
+  [HaiStorageError.INVALID_CHECKSUM.code]: "Checksum input was invalid",
+  [HaiStorageError.UNSUPPORTED_OPERATION.code]: "Storage provider does not support this operation",
+  [HaiStorageError.INVALID_LIST_OPTIONS.code]: "Storage list options or cursor were invalid"
+};
+function storageErrorContext(code, cause, cancelled = false) {
+  const details = cause && typeof cause === "object" ? cause : {};
+  const name = "name" in details ? details.name : void 0;
+  const causeCode = "code" in details && typeof details.code === "string" ? details.code : name;
+  const errno = "errno" in details ? details.errno : void 0;
+  const metadata = "$metadata" in details ? details.$metadata : void 0;
+  const status = typeof metadata === "object" && metadata !== null && "httpStatusCode" in metadata ? metadata.httpStatusCode : void 0;
+  const requestId = typeof metadata === "object" && metadata !== null && "requestId" in metadata ? metadata.requestId : void 0;
+  const partNumber = "partNumber" in details ? details.partNumber : void 0;
+  return {
+    code,
+    reason: cancelled || name === "AbortError" || causeCode === "ABORT_ERR" ? "Storage operation was cancelled" : FAILURE_REASONS[code] ?? "Storage operation failed",
+    causeCode: typeof causeCode === "string" && ERROR_NAME.test(causeCode) ? causeCode : void 0,
+    systemReason: typeof errno === "number" && Number.isInteger(errno) && errno < 0 && errno >= -2147483648 ? getSystemErrorMessage(errno) : void 0,
+    httpStatus: typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599 ? status : void 0,
+    providerRequestId: typeof requestId === "string" && ERROR_NAME.test(requestId) ? requestId : void 0,
+    partNumber: typeof partNumber === "number" && Number.isInteger(partNumber) && partNumber >= 1 && partNumber <= 1e4 ? partNumber : void 0
+  };
+}
+function warnFailure(operation, failure, signal) {
+  const batch = failure.ext?.deleteMany;
+  const s3Operation = failure.ext?.s3Operation;
+  const cleanup = failure.ext?.cleanupError;
+  const cleanupContext = cleanup && typeof cleanup === "object" && "code" in cleanup && typeof cleanup.code === "string" && ERROR_NAME.test(cleanup.code) ? storageErrorContext(cleanup.code, "cause" in cleanup ? cleanup.cause : void 0) : void 0;
+  const failures = batch && typeof batch === "object" && "failures" in batch && Array.isArray(batch.failures) ? batch.failures : void 0;
+  logger3.warn("Storage operation failed", {
+    operation,
+    ...storageErrorContext(failure.code, failure.cause, signal?.aborted && Object.is(failure.cause, signal.reason)),
+    s3Operation: typeof s3Operation === "string" && ERROR_NAME.test(s3Operation) ? s3Operation : void 0,
+    cleanupError: cleanupContext,
+    failedCount: failures?.length,
+    failureCodes: failures && [
+      ...new Set(failures.slice(0, 32).flatMap((item) => {
+        if (typeof item === "object" && item !== null && "code" in item && typeof item.code === "string" && ERROR_NAME.test(item.code))
+          return [item.code];
+        return [];
+      }))
+    ]
+  });
+}
+async function logStorageResult(operation, pending, signal) {
+  const result = await pending.catch((cause) => err(HaiStorageError.OPERATION_FAILED, storageM("storage_operationFailed", {
+    params: {
+      error: cause instanceof Error ? cause.message : storageM("storage_unknownError")
+    }
+  }), cause));
+  if (!result.success)
+    warnFailure(operation, result.error, signal);
+  return result;
+}
+async function* logReadStream(stream) {
+  try {
+    yield* stream;
+  } catch (cause) {
+    warnFailure("file.getStream", { code: HaiStorageError.DOWNLOAD_FAILED.code, cause });
+    throw cause;
+  }
+}
+function debugOperation(config, category, operation, summary) {
+  if (!config?.[category])
+    return;
+  const text = summary && config.maxLength > 0 ? JSON.stringify(summary) : "";
+  const payload = text.length > config.maxLength ? `${text.slice(0, config.maxLength)}...` : text;
+  logger3.debug("Storage operation started", { category, operation, payload });
+}
+function withStorageOperationLogs(provider, config) {
+  const { file, dir, presign } = provider;
+  function run(category, operation, invoke, summary) {
+    debugOperation(config, category, operation, summary);
+    return logStorageResult(operation, invoke());
+  }
+  return {
+    file: {
+      put(key, data, options) {
+        debugOperation(config, "write", "file.put", {
+          byteLength: typeof data === "string" ? Buffer.byteLength(data) : data instanceof Uint8Array ? data.byteLength : void 0
+        });
+        return logStorageResult("file.put", uploadWithSource(data, options?.signal, (input) => file.put(key, input, options)), options?.signal);
+      },
+      get: (key, options) => run("read", "file.get", () => file.get(key, options)),
+      async getStream(key, options) {
+        const result = await run("read", "file.getStream", () => file.getStream(key, options));
+        return result.success ? ok(logReadStream(result.data)) : result;
+      },
+      head: (key) => run("read", "file.head", () => file.head(key)),
+      exists: (key) => run("read", "file.exists", () => file.exists(key)),
+      delete: (key) => run("write", "file.delete", () => file.delete(key)),
+      deleteMany: (keys) => run("write", "file.deleteMany", () => file.deleteMany(keys), { count: keys.length }),
+      copy: (source, destination, options) => run("write", "file.copy", () => file.copy(source, destination, options))
+    },
+    dir: {
+      list: (options) => run("read", "dir.list", () => dir.list(options), { maxKeys: options?.maxKeys }),
+      delete: (prefix) => run("write", "dir.delete", () => dir.delete(prefix))
+    },
+    presign: {
+      getUrl: (key, options) => run("read", "presign.getUrl", () => presign.getUrl(key, options)),
+      putUrl: (key, options) => run("write", "presign.putUrl", () => presign.putUrl(key, options)),
+      publicUrl(key) {
+        debugOperation(config, "read", "presign.publicUrl");
+        return presign.publicUrl(key);
+      }
+    }
+  };
+}
 
 // src/storage-main.ts
-var logger3 = core.logger.child({ module: "storage", scope: "main" });
+var logger4 = core.logger.child({ module: "storage", scope: "main" });
 var currentProvider = null;
 var currentConfig = null;
 var initInProgress = false;
@@ -1407,7 +1572,7 @@ async function closeOwnedProvider() {
     pendingProvider = null;
     return ok(void 0);
   } catch (error) {
-    logger3.error("Provider cleanup failed; retaining resource for retry", { error });
+    logger4.error("Provider cleanup failed; retaining resource for retry", storageErrorContext(HaiStorageError.CONNECTION_FAILED.code, error));
     return err({
       ...HaiStorageError.CONNECTION_FAILED,
       message: storageM("storage_operationFailed", {
@@ -1463,8 +1628,16 @@ var notInitializedPresign = new Proxy(
     get: (target, prop, receiver) => prop === "publicUrl" ? () => null : Reflect.get(target, prop, receiver)
   }
 );
+var unavailableOperations = withStorageOperationLogs({
+  file: notInitializedFile,
+  dir: notInitializedDir,
+  presign: notInitializedPresign
+});
 var storage = {
-  checksum,
+  checksum: {
+    generate: (data, options) => logStorageResult("checksum.generate", checksum.generate(data, options)),
+    verify: (data, expected, options) => logStorageResult("checksum.verify", checksum.verify(data, expected, options))
+  },
   /**
    * 初始化存储连接。
    *
@@ -1485,7 +1658,7 @@ var storage = {
    */
   async init(config) {
     if (initInProgress || closingPromise) {
-      logger3.warn("Storage init already in progress, skipping concurrent call");
+      logger4.error("Storage initialization refused during an existing lifecycle operation", { code: HaiStorageError.OPERATION_FAILED.code });
       return err(
         HaiStorageError.OPERATION_FAILED,
         storageM("storage_operationFailed", {
@@ -1502,10 +1675,10 @@ var storage = {
       const cleanup = await closeOwnedProvider();
       if (!cleanup.success)
         return cleanup;
-      logger3.info("Initializing storage module");
+      logger4.debug("Initializing storage module");
       const parseResult = StorageConfigSchema.safeParse(config);
       if (!parseResult.success) {
-        logger3.error("Storage config validation failed", { error: parseResult.error.message });
+        logger4.error("Storage config validation failed", { code: HaiStorageError.CONFIG_ERROR.code, issueCount: parseResult.error.issues.length });
         return err(
           HaiStorageError.CONFIG_ERROR,
           storageM("storage_configError", {
@@ -1515,25 +1688,30 @@ var storage = {
         );
       }
       const parsed = parseResult.data;
-      if (core.module.requiresSharedState(process.env) && parsed.type === "local")
+      if (core.module.requiresSharedState(process.env) && parsed.type === "local") {
+        logger4.error("Storage initialization requires a shared provider", { code: HaiStorageError.CONFIG_ERROR.code, provider: parsed.type });
         return err(HaiStorageError.CONFIG_ERROR, storageM("storage_sharedBackendRequired"));
+      }
       const provider = createProvider(parsed);
       pendingProvider = provider;
       const connectResult = await provider.connect(parsed);
       if (!connectResult.success) {
-        logger3.error("Storage module initialization failed", {
-          code: connectResult.error.code,
-          message: connectResult.error.message
+        logger4.error("Storage module initialization failed", {
+          provider: provider.name,
+          ...storageErrorContext(connectResult.error.code, connectResult.error.cause)
         });
         return await failInitialization(connectResult);
       }
+      currentProvider = {
+        ...provider,
+        ...withStorageOperationLogs(provider, parsed.operationLog)
+      };
       pendingProvider = null;
-      currentProvider = provider;
       currentConfig = parsed;
-      logger3.info("Storage module initialized");
+      logger4.debug("Storage module initialized");
       return ok(void 0);
     } catch (error) {
-      logger3.error("Storage module initialization failed", { error });
+      logger4.error("Storage module initialization failed", storageErrorContext(HaiStorageError.CONNECTION_FAILED.code, error));
       return await failInitialization(err(
         HaiStorageError.CONNECTION_FAILED,
         storageM("storage_operationFailed", {
@@ -1551,15 +1729,15 @@ var storage = {
   },
   /** 文件操作接口。未初始化时所有方法返回 NOT_INITIALIZED 错误 */
   get file() {
-    return currentProvider?.file ?? notInitializedFile;
+    return currentProvider?.file ?? unavailableOperations.file;
   },
   /** 目录操作接口。未初始化时所有方法返回 NOT_INITIALIZED 错误 */
   get dir() {
-    return currentProvider?.dir ?? notInitializedDir;
+    return currentProvider?.dir ?? unavailableOperations.dir;
   },
   /** 签名 URL 操作接口。未初始化时 publicUrl 返回 null，其余返回错误 */
   get presign() {
-    return currentProvider?.presign ?? notInitializedPresign;
+    return currentProvider?.presign ?? unavailableOperations.presign;
   },
   /** 当前脱敏后的存储配置快照；未初始化或已关闭时为 null */
   get config() {