mnemospark 0.1.21 → 0.1.22

package/dist/index.js

@@ -327,6 +327,21 @@ async function createWalletSignatureHeaderValue(method, path, walletAddress, wal
   return encodeBase64Json(headerEnvelope);
 }
 
+// src/cloud-correlation.ts
+var MNEMOSPARK_TRACE_ID_HEADER = "X-Mnemospark-Trace-Id";
+var MNEMOSPARK_OPERATION_ID_HEADER = "X-Mnemospark-Operation-Id";
+function applyCorrelationHeaders(headers, correlation) {
+  const traceId = correlation?.traceId?.trim();
+  if (traceId) {
+    headers[MNEMOSPARK_TRACE_ID_HEADER] = traceId;
+  }
+  const operationId = correlation?.operationId?.trim();
+  if (operationId) {
+    headers[MNEMOSPARK_OPERATION_ID_HEADER] = operationId;
+  }
+  return headers;
+}
+
 // src/cloud-utils.ts
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
@@ -556,9 +571,12 @@ async function requestPriceStorageViaProxy(request, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${PRICE_STORAGE_PROXY_PATH}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const responseBody = await response.text();
@@ -583,6 +601,7 @@ async function requestStorageUploadViaProxy(request, options = {}) {
   const requestHeaders = {
     "Content-Type": "application/json"
   };
+  applyCorrelationHeaders(requestHeaders, options.correlation);
   if (options.idempotencyKey && options.idempotencyKey.trim().length > 0) {
     requestHeaders["Idempotency-Key"] = options.idempotencyKey.trim();
   }
@@ -664,9 +683,12 @@ async function requestStorageUploadConfirmViaProxy(request, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${UPLOAD_CONFIRM_PROXY_PATH}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const responseBody = await response.text();
@@ -781,7 +803,7 @@ async function requestPaymentSettleViaProxy(quoteId, walletAddress, options = {}
   }
   const response = await fetchImpl(targetUrl, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: applyCorrelationHeaders({ "Content-Type": "application/json" }, options.correlation),
     body: JSON.stringify(requestBody)
   });
   return {
@@ -1265,9 +1287,12 @@ async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
   );
   const response = await fetchImpl(`${baseUrl}${proxyPath}`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
+    headers: applyCorrelationHeaders(
+      {
+        "Content-Type": "application/json"
+      },
+      options.correlation
+    ),
     body: JSON.stringify(request)
   });
   const bodyText = await response.text();
@@ -1591,6 +1616,20 @@ function emitProxyEvent(eventType, status, correlation, details = {}) {
     details
   }).catch(() => void 0);
 }
+function createProxyCorrelation(headers) {
+  const traceId = readHeaderValue(headers[MNEMOSPARK_TRACE_ID_HEADER.toLowerCase()]) ?? randomUUID();
+  const operationId = readHeaderValue(
+    headers[MNEMOSPARK_OPERATION_ID_HEADER.toLowerCase()] ?? headers["idempotency-key"]
+  ) ?? randomUUID();
+  return { trace_id: traceId, operation_id: operationId };
+}
+function emitProxyTerminalFromStatus(correlation, statusCode, details = {}) {
+  if (statusCode >= 200 && statusCode < 300) {
+    emitProxyEvent("terminal.success", "success", correlation, { status: statusCode, ...details });
+    return;
+  }
+  emitProxyEvent("terminal.failure", "failure", correlation, { status: statusCode, ...details });
+}
 function isAlreadySettledConflict(status, bodyText) {
   if (status !== 409) {
     return false;
@@ -1715,10 +1754,7 @@ async function startProxy(options) {
       console.error(`[mnemospark] Response stream error: ${err.message}`);
     });
     if (req.method === "POST" && matchesProxyPath(req.url, PRICE_STORAGE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_price_storage_received");
       emitProxyEvent("request.received", "start", correlation, { path: PRICE_STORAGE_PROXY_PATH });
       try {
@@ -1727,6 +1763,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_price_storage_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud price-storage"
@@ -1736,6 +1773,7 @@ async function startProxy(options) {
         const requestPayload = parsePriceStorageQuoteRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_price_storage_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_id, object_id_hash, gb, provider, region"
@@ -1754,6 +1792,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_price_storage_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         const backendResponse = await forwardPriceStorageToBackend(requestPayload, {
@@ -1779,14 +1818,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -1802,10 +1840,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, PAYMENT_SETTLE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_payment_settle_received");
       emitProxyEvent("request.received", "start", correlation, { path: PAYMENT_SETTLE_PROXY_PATH });
       try {
@@ -1814,6 +1849,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_payment_settle_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark/payment/settle"
@@ -1827,6 +1863,7 @@ async function startProxy(options) {
         const inlinePaymentAuthorization = record?.payment_authorization;
         if (!quoteId || !walletAddress) {
           logProxyEvent("warn", "proxy_payment_settle_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address"
@@ -1835,6 +1872,7 @@ async function startProxy(options) {
         }
         if (inlinePayment !== void 0 && (inlinePayment === null || typeof inlinePayment !== "object" || Array.isArray(inlinePayment))) {
           logProxyEvent("warn", "proxy_payment_settle_invalid_payment_shape");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_payment_shape" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid field: payment must be an object when provided"
@@ -1843,6 +1881,9 @@ async function startProxy(options) {
         }
         if (inlinePaymentAuthorization !== void 0 && !(typeof inlinePaymentAuthorization === "string" || inlinePaymentAuthorization !== null && typeof inlinePaymentAuthorization === "object" && !Array.isArray(inlinePaymentAuthorization))) {
           logProxyEvent("warn", "proxy_payment_settle_invalid_payment_authorization_shape");
+          emitProxyTerminalFromStatus(correlation, 400, {
+            reason: "invalid_payment_authorization_shape"
+          });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid field: payment_authorization must be an object or string when provided"
@@ -1854,6 +1895,7 @@ async function startProxy(options) {
             request_wallet: walletAddress,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1869,6 +1911,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_payment_settle_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         correlation.quote_id = quoteId;
@@ -1903,14 +1946,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -1926,10 +1968,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_upload_received");
       emitProxyEvent("request.received", "start", correlation, { path: UPLOAD_PROXY_PATH });
       try {
@@ -1938,6 +1977,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_upload_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud upload"
@@ -1947,6 +1987,7 @@ async function startProxy(options) {
         const requestPayload = parseStorageUploadRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_upload_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address, object_id, object_id_hash, quoted_storage_price, payload"
@@ -1956,12 +1997,12 @@ async function startProxy(options) {
         correlation.quote_id = requestPayload.quote_id;
         correlation.wallet_address = requestPayload.wallet_address;
         correlation.object_id = requestPayload.object_id;
-        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload" });
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_upload_wallet_mismatch", {
             request_wallet: requestPayload.wallet_address,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1977,6 +2018,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         const requiredMicros = BigInt(
@@ -1996,6 +2038,7 @@ async function startProxy(options) {
             requiredUSD,
             walletAddress: requestPayload.wallet_address
           });
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "insufficient_balance" });
           sendJson(res, 400, {
             error: "insufficient_balance",
             message: `Insufficient USDC balance. Current: ${sufficiency.info.balanceUSD}, Required: ${requiredUSD}`,
@@ -2023,6 +2066,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_settle_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "settle_signature_missing" });
           return;
         }
         const uploadPaymentFetch = createPaymentFetch(walletPrivateKey).fetch;
@@ -2052,6 +2096,9 @@ async function startProxy(options) {
           });
           res.writeHead(settleResponse.status, responseHeaders2);
           res.end(settleResponse.bodyText);
+          emitProxyTerminalFromStatus(correlation, settleResponse.status, {
+            reason: "settle_failed"
+          });
           return;
         }
         if (settledAlready) {
@@ -2063,6 +2110,7 @@ async function startProxy(options) {
             status: settleResponse.status
           });
         }
+        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload" });
         const backendResponse = await forwardStorageUploadToBackend(requestPayload, {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature,
@@ -2087,14 +2135,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2110,13 +2157,16 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_CONFIRM_PROXY_PATH)) {
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_upload_confirm_received");
+      emitProxyEvent("request.received", "start", correlation, { path: UPLOAD_CONFIRM_PROXY_PATH });
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_upload_confirm_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud upload/confirm"
@@ -2126,17 +2176,22 @@ async function startProxy(options) {
         const requestPayload = parseStorageUploadConfirmRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_upload_confirm_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address, object_key, idempotency_key"
           });
           return;
         }
+        correlation.quote_id = requestPayload.quote_id;
+        correlation.wallet_address = requestPayload.wallet_address;
+        correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_upload_confirm_wallet_mismatch", {
             request_wallet: requestPayload.wallet_address,
             proxy_wallet: account.address
           });
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2152,8 +2207,10 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_upload_confirm_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
+        emitProxyEvent("storage.call", "start", correlation, { target: "storage/upload/confirm" });
         const backendResponse = await forwardStorageUploadConfirmToBackend(requestPayload, {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
@@ -2161,6 +2218,7 @@ async function startProxy(options) {
         logProxyEvent("info", "proxy_upload_confirm_backend_response", {
           status: backendResponse.status
         });
+        emitProxyEvent("storage.call", "result", correlation, { status: backendResponse.status });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
@@ -2176,12 +2234,17 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
+        emitProxyEvent("terminal.failure", "failure", correlation, {
+          error: err instanceof Error ? err.message : String(err)
+        });
         logProxyEvent("error", "proxy_upload_confirm_forward_failed", {
           error: err instanceof Error ? err.message : String(err)
         });
@@ -2193,10 +2256,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_LS_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_ls_received");
       emitProxyEvent("request.received", "start", correlation, { path: STORAGE_LS_PROXY_PATH });
       try {
@@ -2205,6 +2265,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_ls_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud ls"
@@ -2214,6 +2275,7 @@ async function startProxy(options) {
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_ls_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2224,6 +2286,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_ls_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2239,6 +2302,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_ls_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/ls" });
@@ -2261,14 +2325,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2284,10 +2347,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DOWNLOAD_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_download_received");
       emitProxyEvent("request.received", "start", correlation, {
         path: STORAGE_DOWNLOAD_PROXY_PATH
@@ -2298,6 +2358,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_download_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud download"
@@ -2307,6 +2368,7 @@ async function startProxy(options) {
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_download_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2317,6 +2379,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_download_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2332,6 +2395,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_download_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/download" });
@@ -2358,6 +2422,7 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         if (backendResponse.status < 200 || backendResponse.status >= 300) {
@@ -2367,6 +2432,7 @@ async function startProxy(options) {
           const responseHeaders = createBackendForwardHeaders(backendResponse);
           res.writeHead(backendResponse.status, responseHeaders);
           res.end(backendResponse.bodyText);
+          emitProxyTerminalFromStatus(correlation, backendResponse.status);
           return;
         }
         const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse, {
@@ -2383,9 +2449,7 @@ async function startProxy(options) {
           file_path: downloadResult.filePath,
           bytes_written: downloadResult.bytesWritten
         });
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: 200
-        });
+        emitProxyTerminalFromStatus(correlation, 200);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2401,10 +2465,7 @@ async function startProxy(options) {
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DELETE_PROXY_PATH)) {
-      const correlation = {
-        trace_id: randomUUID(),
-        operation_id: randomUUID()
-      };
+      const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_delete_received");
       emitProxyEvent("request.received", "start", correlation, { path: STORAGE_DELETE_PROXY_PATH });
       try {
@@ -2413,6 +2474,7 @@ async function startProxy(options) {
           payload = await readProxyJsonBody(req);
         } catch {
           logProxyEvent("warn", "proxy_delete_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Invalid JSON body for /mnemospark-cloud delete"
@@ -2422,6 +2484,7 @@ async function startProxy(options) {
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_delete_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -2432,6 +2495,7 @@ async function startProxy(options) {
         correlation.object_key = requestPayload.object_key;
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
           logProxyEvent("warn", "proxy_delete_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -2447,6 +2511,7 @@ async function startProxy(options) {
           logProxyEvent("warn", "proxy_delete_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
           return;
         }
         emitProxyEvent("storage.call", "start", correlation, { target: "storage/delete" });
@@ -2473,14 +2538,13 @@ async function startProxy(options) {
           });
           res.writeHead(authFailure.status, responseHeaders2);
           res.end(authFailure.bodyText);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
           return;
         }
         const responseHeaders = createBackendForwardHeaders(backendResponse);
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
-        emitProxyEvent("terminal.success", "success", correlation, {
-          status: backendResponse.status
-        });
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
       } catch (err) {
         emitProxyEvent("terminal.failure", "failure", correlation, {
           error: err instanceof Error ? err.message : String(err)
@@ -2989,7 +3053,7 @@ async function createCloudDatastore(homeDir) {
            VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(operation_id) DO UPDATE SET
              type=excluded.type,
-             object_id=excluded.object_id,
+             object_id=COALESCE(excluded.object_id, operations.object_id),
              quote_id=excluded.quote_id,
              status=excluded.status,
              error_code=excluded.error_code,
@@ -4034,7 +4098,12 @@ async function emitCloudEventBestEffort(eventType, details, homeDir) {
   } catch {
   }
 }
-async function runCloudCommandHandler(ctx, options) {
+function buildRequestCorrelation(forcedOperationId, forcedTraceId) {
+  const operationId = forcedOperationId?.trim() || randomUUID3();
+  const traceId = forcedTraceId?.trim() || randomUUID3();
+  return { operationId, traceId };
+}
+async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const parsed = parseCloudArgs(ctx.args);
   const objectLogHomeDir = options.objectLogHomeDir;
   const backupBuilder = options.buildBackupObjectFn;
@@ -4114,9 +4183,10 @@ async function runCloudCommandHandler(ctx, options) {
     };
   }
   if ((parsed.mode === "upload" || parsed.mode === "download") && parsed.async) {
-    const operationId = randomUUID3();
+    const asyncCorrelation = buildRequestCorrelation();
+    const operationId = asyncCorrelation.operationId;
     const opType = parsed.mode;
-    const opObject = parsed.mode === "upload" ? parsed.uploadRequest.object_id : parsed.storageObjectRequest.object_key ?? null;
+    const opObject = parsed.mode === "upload" ? parsed.uploadRequest.object_id : null;
     const opQuote = parsed.mode === "upload" ? parsed.uploadRequest.quote_id : null;
     await datastore.upsertOperation({
       operation_id: operationId,
@@ -4128,7 +4198,10 @@ async function runCloudCommandHandler(ctx, options) {
       error_message: null
     });
     const syncArgs = stripAsyncFlag(ctx.args);
-    void runCloudCommandHandler({ args: syncArgs }, options).then(async (result) => {
+    void runCloudCommandHandler({ args: syncArgs }, options, {
+      forcedOperationId: asyncCorrelation.operationId,
+      forcedTraceId: asyncCorrelation.traceId
+    }).then(async (result) => {
       await datastore.upsertOperation({
         operation_id: operationId,
         type: opType,
@@ -4209,11 +4282,12 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     }
   }
   if (parsed.mode === "price-storage") {
+    const correlation = buildRequestCorrelation();
     try {
-      const quote = await requestPriceStorageQuote(
-        parsed.priceStorageRequest,
-        options.proxyQuoteOptions
-      );
+      const quote = await requestPriceStorageQuote(parsed.priceStorageRequest, {
+        ...options.proxyQuoteOptions,
+        correlation
+      });
       await appendPriceStorageQuoteLog(quote, objectLogHomeDir);
       await datastore.upsertObject({
         object_id: quote.object_id,
@@ -4234,10 +4308,33 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         network: null,
         status: "quoted"
       });
+      await emitCloudEventBestEffort(
+        "price-storage.completed",
+        {
+          operation_id: correlation.operationId,
+          trace_id: correlation.traceId,
+          wallet_address: quote.addr,
+          object_id: quote.object_id,
+          quote_id: quote.quote_id,
+          status: "succeeded"
+        },
+        objectLogHomeDir
+      );
       return {
         text: formatPriceStorageUserMessage(quote)
       };
     } catch (err) {
+      await emitCloudEventBestEffort(
+        "price-storage.completed",
+        {
+          operation_id: correlation.operationId,
+          trace_id: correlation.traceId,
+          wallet_address: parsed.priceStorageRequest.wallet_address,
+          object_id: parsed.priceStorageRequest.object_id,
+          status: "failed"
+        },
+        objectLogHomeDir
+      );
       const message = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
       return {
         text: message ? `Cannot price storage: ${message}` : "Cannot price storage",
@@ -4246,6 +4343,10 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
     }
   }
   if (parsed.mode === "upload") {
+    const uploadCorrelation = buildRequestCorrelation(
+      executionContext.forcedOperationId ?? idempotencyKeyFn(),
+      executionContext.forcedTraceId
+    );
     try {
       const loggedQuote = await datastore.findQuoteById(parsed.uploadRequest.quote_id) ?? await findLoggedPriceStorageQuote(parsed.uploadRequest.quote_id, objectLogHomeDir);
       if (!loggedQuote) {
@@ -4299,7 +4400,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         parsed.uploadRequest.wallet_address,
         objectLogHomeDir
       );
-      const idempotencyKey = idempotencyKeyFn();
+      const idempotencyKey = uploadCorrelation.operationId;
       const shouldSettleBeforeUpload = requestStorageUpload !== requestStorageUploadViaProxy;
       if (shouldSettleBeforeUpload) {
         const paymentFetch = createPayment(walletKey).fetch;
@@ -4308,6 +4409,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
           parsed.uploadRequest.wallet_address,
           {
             ...options.proxyUploadOptions,
+            correlation: uploadCorrelation,
             fetchImpl: (input, init) => paymentFetch(input, init)
           }
         );
@@ -4329,6 +4431,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         {
           ...options.proxyUploadOptions,
           idempotencyKey,
+          correlation: uploadCorrelation,
           fetchImpl: uploadFetchImpl
         }
       );
@@ -4348,7 +4451,10 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
               object_key: uploadResponse.object_key,
               idempotency_key: idempotencyKey
             },
-            options.proxyUploadConfirmOptions
+            {
+              ...options.proxyUploadConfirmOptions,
+              correlation: uploadCorrelation
+            }
           );
         } catch (confirmError) {
           const transId = uploadResponse.trans_id ?? "unknown";
@@ -4424,6 +4530,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "upload.completed",
         {
           operation_id: idempotencyKey,
+          trace_id: uploadCorrelation.traceId,
           wallet_address: finalizedUploadResponse.addr,
           object_id: finalizedUploadResponse.object_id,
           object_key: finalizedUploadResponse.object_key,
@@ -4437,6 +4544,18 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         text: formatStorageUploadUserMessage(finalizedUploadResponse, cronJob.cronId)
       };
     } catch (error) {
+      await emitCloudEventBestEffort(
+        "upload.completed",
+        {
+          operation_id: uploadCorrelation.operationId,
+          trace_id: uploadCorrelation.traceId,
+          wallet_address: parsed.uploadRequest.wallet_address,
+          object_id: parsed.uploadRequest.object_id,
+          quote_id: parsed.uploadRequest.quote_id,
+          status: "failed"
+        },
+        objectLogHomeDir
+      );
       const uploadErrorMessage = extractUploadErrorMessage(error);
       return {
         text: uploadErrorMessage ?? "Cannot upload storage object",
@@ -4454,25 +4573,31 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    const correlation = buildRequestCorrelation();
+    const operationId = correlation.operationId;
+    const knownObject = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
+    const operationObjectId = knownObject?.object_id ?? null;
     await datastore.upsertOperation({
       operation_id: operationId,
       type: "ls",
-      object_id: resolvedRequest.object_key,
+      object_id: operationObjectId,
       quote_id: null,
       status: "started",
       error_code: null,
       error_message: null
     });
     try {
-      const lsResult = await requestStorageLs(resolvedRequest, options.proxyStorageOptions);
+      const lsResult = await requestStorageLs(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!lsResult.success) {
         throw new Error("ls failed");
       }
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "ls",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "succeeded",
         error_code: null,
@@ -4482,6 +4607,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "ls.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "succeeded"
@@ -4495,7 +4621,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "ls",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "failed",
         error_code: "LS_FAILED",
@@ -4505,6 +4631,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "ls.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4527,28 +4654,34 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    const correlation = buildRequestCorrelation(
+      executionContext.forcedOperationId,
+      executionContext.forcedTraceId
+    );
+    const operationId = correlation.operationId;
+    const knownObject = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
+    const operationObjectId = knownObject?.object_id ?? null;
     await datastore.upsertOperation({
       operation_id: operationId,
       type: "download",
-      object_id: resolvedRequest.object_key,
+      object_id: operationObjectId,
       quote_id: null,
       status: "started",
       error_code: null,
       error_message: null
     });
     try {
-      const downloadResult = await requestStorageDownload(
-        resolvedRequest,
-        options.proxyStorageOptions
-      );
+      const downloadResult = await requestStorageDownload(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!downloadResult.success) {
         throw new Error("download failed");
       }
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "download",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "succeeded",
         error_code: null,
@@ -4558,6 +4691,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "download.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "succeeded"
@@ -4571,7 +4705,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "download",
-        object_id: resolvedRequest.object_key,
+        object_id: operationObjectId,
         quote_id: null,
         status: "failed",
         error_code: "DOWNLOAD_FAILED",
@@ -4581,6 +4715,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "download.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4603,10 +4738,14 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
     const resolvedRequest = resolved.request;
-    const operationId = randomUUID3();
+    const correlation = buildRequestCorrelation();
+    const operationId = correlation.operationId;
     const existingObjectByKey = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
     try {
-      const deleteResult = await requestStorageDelete(resolvedRequest, options.proxyStorageOptions);
+      const deleteResult = await requestStorageDelete(resolvedRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
       if (!deleteResult.success) {
         throw new Error("delete failed");
       }
@@ -4615,6 +4754,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
         "delete.completed",
         {
           operation_id: operationId,
+          trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
           object_key: resolvedRequest.object_key,
           status: "failed"
@@ -4672,6 +4812,7 @@ Use /mnemospark-cloud op-status --operation-id ${operationId}`
       "delete.completed",
       {
         operation_id: operationId,
+        trace_id: correlation.traceId,
         wallet_address: resolvedRequest.wallet_address,
         object_key: resolvedRequest.object_key,
         status: "succeeded"