@zintrust/trace 0.4.83 → 0.4.84

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.83",
-  "buildDate": "2026-04-08T17:13:19.081Z",
+  "version": "0.4.84",
+  "buildDate": "2026-04-08T17:51:22.444Z",
   "buildEnvironment": {
     "node": "v22.22.1",
     "platform": "darwin",
     "arch": "arm64"
   },
   "git": {
-    "commit": "3c792064",
+    "commit": "d4c31a0d",
     "branch": "release"
   },
   "package": {
@@ -22,8 +22,8 @@
   },
   "files": {
     "build-manifest.json": {
-      "size": 14439,
-      "sha256": "dab00c1ade5c0b5fe2b10b5eeeae31dfd9a017f198794e18e7c2b69cfb5560d8"
+      "size": 14440,
+      "sha256": "04b7ac17fd2a9abf208db4df6218eea2f97a4ce4e1dc6ce8d826036924e7ab84"
     },
     "cli-register.d.ts": {
       "size": 255,
@@ -79,7 +79,7 @@
     },
     "index.js": {
       "size": 3255,
-      "sha256": "a293d38a9e56a2ab802f99143eb1eaebb18f854e610f29bc95878746ffe26326"
+      "sha256": "f95401dc3b5ad76937e32978770c9568cf90e453bb1e77d0ecc8611e664b5ce0"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -174,8 +174,8 @@
       "sha256": "5f49df97a830ad895653fa4a18b3a1b31ca4a5066d6f8150ee02dca013e16397"
     },
     "storage/TraceWriteDiagnostics.js": {
-      "size": 4162,
-      "sha256": "06ba6979f5053956f7a5f9ec8dc301864f36276a2c74b0bf63cf733ad7c5eac2"
+      "size": 6714,
+      "sha256": "398b2cb74e2e7278c6a3b5d29537e7a95581e0a1cb9fb5831f7ff13ac70805e4"
     },
     "storage/index.d.ts": {
       "size": 100,

package/dist/storage/TraceWriteDiagnostics.js

@@ -6,19 +6,98 @@ const diagnosticsState = {
     lastLoggedAtByFingerprint: new Map(),
     totalFailures: 0,
 };
+const asRecord = (value) => {
+    if (value === null || typeof value !== 'object')
+        return null;
+    return value;
+};
+const getAttachedErrorDetails = (error) => {
+    if (error instanceof Error && 'details' in error) {
+        const details = error.details;
+        if (details !== undefined)
+            return details;
+    }
+    const record = asRecord(error);
+    return record?.['details'];
+};
+const getTextValue = (value) => {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+};
+const describeBodyDetails = (body) => {
+    const code = getTextValue(body['code']);
+    const message = getTextValue(body['message']);
+    if (code !== null && message !== null)
+        return `${code}: ${message}`;
+    if (code !== null)
+        return code;
+    if (message !== null)
+        return message;
+    return null;
+};
+const describeRecordDetails = (record) => {
+    const body = asRecord(record['body']);
+    if (body !== null) {
+        const describedBody = describeBodyDetails(body);
+        if (describedBody !== null)
+            return describedBody;
+    }
+    const nested = describeErrorDetails(record['details']);
+    if (nested !== null)
+        return nested;
+    const message = getTextValue(record['message']);
+    if (message !== null)
+        return message;
+    const code = getTextValue(record['code']);
+    if (code !== null)
+        return code;
+    return null;
+};
+const describeErrorDetails = (details) => {
+    const text = getTextValue(details);
+    if (text !== null)
+        return text;
+    const record = asRecord(details);
+    if (record === null)
+        return null;
+    return describeRecordDetails(record);
+};
+const withOptionalDetail = (context, errorDetails) => {
+    if (errorDetails === undefined)
+        return context;
+    return { ...context, errorDetails };
+};
 const getErrorMessage = (error) => {
-    if (error instanceof Error && error.message.trim() !== '')
-        return error.message;
-    if (typeof error === 'string' && error.trim() !== '')
-        return error;
-    try {
-        const serialized = JSON.stringify(error);
-        if (typeof serialized === 'string' && serialized !== '')
-            return serialized;
+    let baseMessage = '';
+    if (error instanceof Error && error.message.trim() !== '') {
+        baseMessage = error.message;
+    }
+    else if (typeof error === 'string' && error.trim() !== '') {
+        baseMessage = error;
+    }
+    else {
+        try {
+            const serialized = JSON.stringify(error);
+            if (typeof serialized === 'string' && serialized !== '')
+                baseMessage = serialized;
+        }
+        catch {
+            // ignore serialization failures
+        }
     }
-    catch {
-        // ignore serialization failures
+    const detailsSummary = describeErrorDetails(getAttachedErrorDetails(error));
+    if (detailsSummary !== null &&
+        detailsSummary !== '' &&
+        baseMessage !== '' &&
+        !baseMessage.includes(detailsSummary)) {
+        return `${baseMessage} (${detailsSummary})`;
     }
+    if (baseMessage !== '')
+        return baseMessage;
+    if (detailsSummary !== null && detailsSummary !== '')
+        return detailsSummary;
     return 'Unknown trace storage error';
 };
 const buildFingerprint = (context) => {
@@ -32,25 +111,26 @@ const buildFingerprint = (context) => {
 const reportFailure = (logger, context) => {
     const now = Date.now();
     const errorMessage = getErrorMessage(context.error);
+    const errorDetails = getAttachedErrorDetails(context.error);
     const fingerprint = buildFingerprint(context);
     const lastLoggedAt = diagnosticsState.lastLoggedAtByFingerprint.get(fingerprint);
     diagnosticsState.degraded = true;
     diagnosticsState.lastErrorMessage = errorMessage;
     diagnosticsState.lastFailureAt = now;
     diagnosticsState.totalFailures += 1;
-    if (!logger)
+    if (logger === undefined)
         return;
     if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS)
         return;
     diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
-    logger.warn('[trace] Trace storage write degraded', {
+    logger.warn('[trace] Trace storage write degraded', withOptionalDetail({
         connectionName: context.connectionName,
         error: errorMessage,
         lastFailureAt: now,
         operation: context.operation,
         totalFailures: diagnosticsState.totalFailures,
         watcherType: context.watcherType ?? null,
-    });
+    }, errorDetails));
 };
 const wrapStorageMethod = (method, describeFailure, connectionName, logger) => {
     return async (...args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.83",
+  "version": "0.4.84",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.81"
+    "@zintrust/core": "^0.4.83"
   },
   "publishConfig": {
     "access": "public"

package/src/storage/TraceWriteDiagnostics.ts

@@ -32,17 +32,104 @@ const diagnosticsState: TraceWriteDiagnosticsState = {
   totalFailures: 0,
 };
 
+const asRecord = (value: unknown): Record<string, unknown> | null => {
+  if (value === null || typeof value !== 'object') return null;
+  return value as Record<string, unknown>;
+};
+
+const getAttachedErrorDetails = (error: unknown): unknown => {
+  if (error instanceof Error && 'details' in error) {
+    const details = (error as Error & { details?: unknown }).details;
+    if (details !== undefined) return details;
+  }
+
+  const record = asRecord(error);
+  return record?.['details'];
+};
+
+const getTextValue = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+};
+
+const describeBodyDetails = (body: Record<string, unknown>): string | null => {
+  const code = getTextValue(body['code']);
+  const message = getTextValue(body['message']);
+
+  if (code !== null && message !== null) return `${code}: ${message}`;
+  if (code !== null) return code;
+  if (message !== null) return message;
+
+  return null;
+};
+
+const describeRecordDetails = (record: Record<string, unknown>): string | null => {
+  const body = asRecord(record['body']);
+  if (body !== null) {
+    const describedBody = describeBodyDetails(body);
+    if (describedBody !== null) return describedBody;
+  }
+
+  const nested = describeErrorDetails(record['details']);
+  if (nested !== null) return nested;
+
+  const message = getTextValue(record['message']);
+  if (message !== null) return message;
+
+  const code = getTextValue(record['code']);
+  if (code !== null) return code;
+
+  return null;
+};
+
+const describeErrorDetails = (details: unknown): string | null => {
+  const text = getTextValue(details);
+  if (text !== null) return text;
+
+  const record = asRecord(details);
+  if (record === null) return null;
+  return describeRecordDetails(record);
+};
+
+const withOptionalDetail = (
+  context: Record<string, unknown>,
+  errorDetails: unknown
+): Record<string, unknown> => {
+  if (errorDetails === undefined) return context;
+  return { ...context, errorDetails };
+};
+
 const getErrorMessage = (error: unknown): string => {
-  if (error instanceof Error && error.message.trim() !== '') return error.message;
-  if (typeof error === 'string' && error.trim() !== '') return error;
-
-  try {
-    const serialized = JSON.stringify(error);
-    if (typeof serialized === 'string' && serialized !== '') return serialized;
-  } catch {
-    // ignore serialization failures
+  let baseMessage = '';
+  if (error instanceof Error && error.message.trim() !== '') {
+    baseMessage = error.message;
+  } else if (typeof error === 'string' && error.trim() !== '') {
+    baseMessage = error;
+  } else {
+    try {
+      const serialized = JSON.stringify(error);
+      if (typeof serialized === 'string' && serialized !== '') baseMessage = serialized;
+    } catch {
+      // ignore serialization failures
+    }
   }
 
+  const detailsSummary = describeErrorDetails(getAttachedErrorDetails(error));
+  if (
+    detailsSummary !== null &&
+    detailsSummary !== '' &&
+    baseMessage !== '' &&
+    !baseMessage.includes(detailsSummary)
+  ) {
+    return `${baseMessage} (${detailsSummary})`;
+  }
+
+  if (baseMessage !== '') return baseMessage;
+
+  if (detailsSummary !== null && detailsSummary !== '') return detailsSummary;
+
   return 'Unknown trace storage error';
 };
 
@@ -61,6 +148,7 @@ const reportFailure = (
 ): void => {
   const now = Date.now();
   const errorMessage = getErrorMessage(context.error);
+  const errorDetails = getAttachedErrorDetails(context.error);
   const fingerprint = buildFingerprint(context);
   const lastLoggedAt = diagnosticsState.lastLoggedAtByFingerprint.get(fingerprint);
 
@@ -69,18 +157,24 @@ const reportFailure = (
   diagnosticsState.lastFailureAt = now;
   diagnosticsState.totalFailures += 1;
 
-  if (!logger) return;
+  if (logger === undefined) return;
   if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS) return;
 
   diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
-  logger.warn('[trace] Trace storage write degraded', {
-    connectionName: context.connectionName,
-    error: errorMessage,
-    lastFailureAt: now,
-    operation: context.operation,
-    totalFailures: diagnosticsState.totalFailures,
-    watcherType: context.watcherType ?? null,
-  });
+  logger.warn(
+    '[trace] Trace storage write degraded',
+    withOptionalDetail(
+      {
+        connectionName: context.connectionName,
+        error: errorMessage,
+        lastFailureAt: now,
+        operation: context.operation,
+        totalFailures: diagnosticsState.totalFailures,
+        watcherType: context.watcherType ?? null,
+      },
+      errorDetails
+    )
+  );
 };
 
 const wrapStorageMethod = <TArgs extends unknown[], TResult>(