fix(logger): never let structured serialization throw into the caller

In production the JSON branch merged caller-supplied arguments into the log
entry and stringified it with no error handling. A cyclic reference, a BigInt,
or a throwing getter in that metadata raised a TypeError out of `logger.info`
and friends: the line was lost and the caller's code path aborted.

Dev was unaffected — the colorized branch already routes objects through
`formatObject`, which catches — so this class of bug is invisible locally and
only surfaces in production, where it reads as structured logs disappearing
while raw stack traces keep shipping.

Build and serialize through `serializeEntry`, which falls back to a
cycle/BigInt-tolerant replacer and then to a minimal entry flagged with
`serializationError`.

Author: waleedlatif1

packages/logger/src/index.test.ts

@@ -216,4 +216,43 @@ describe('Logger', () => {
       )
     })
   })
+
+  describe('structured serialization safety', () => {
+    const createEnabledLogger = () =>
+      new Logger('Test', { enabled: true, colorize: false, logLevel: LogLevel.DEBUG })
+
+    test('should emit a line instead of throwing on cyclic metadata', () => {
+      const cyclic: Record<string, unknown> = { id: 'x' }
+      cyclic.self = cyclic
+
+      expect(() => createEnabledLogger().info('hello', cyclic)).not.toThrow()
+      expect(consoleLogSpy).toHaveBeenCalledTimes(1)
+      const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string)
+      expect(parsed.message).toBe('hello')
+      expect(parsed.id).toBe('x')
+      expect(parsed.self.self).toBe('[Circular]')
+    })
+
+    test('should emit a line instead of throwing on BigInt metadata', () => {
+      expect(() => createEnabledLogger().error('boom', { size: 10n })).not.toThrow()
+      expect(consoleErrorSpy).toHaveBeenCalledTimes(1)
+      const parsed = JSON.parse(consoleErrorSpy.mock.calls[0][0] as string)
+      expect(parsed.message).toBe('boom')
+      expect(parsed.size).toBe('10')
+    })
+
+    test('should fall back to a minimal entry when a value cannot be serialized at all', () => {
+      const hostile = {
+        get boom() {
+          throw new Error('getter exploded')
+        },
+      }
+
+      expect(() => createEnabledLogger().info('hello', hostile)).not.toThrow()
+      const parsed = JSON.parse(consoleLogSpy.mock.calls[0][0] as string)
+      expect(parsed.message).toBe('hello')
+      expect(parsed.module).toBe('Test')
+      expect(parsed.serializationError).toBe(true)
+    })
+  })
 })

packages/logger/src/index.ts

@@ -139,6 +139,55 @@ const formatObject = (obj: unknown, isDev: boolean): string => {
   }
 }
 
+/** Merges caller-supplied log arguments into the structured entry. */
+const mergeArgs = (entry: Record<string, unknown>, args: unknown[]): Record<string, unknown> => {
+  for (const arg of args) {
+    if (arg === null || arg === undefined) continue
+    if (arg instanceof Error) {
+      entry.error = arg.message
+      entry.stack = arg.stack
+    } else if (typeof arg === 'object') {
+      Object.assign(entry, arg)
+    } else {
+      entry.extra = arg
+    }
+  }
+  return entry
+}
+
+/** JSON replacer that tolerates cyclic references and BigInt values. */
+const tolerantReplacer = () => {
+  const seen = new WeakSet<object>()
+  return (_key: string, value: unknown): unknown => {
+    if (typeof value === 'bigint') return value.toString()
+    if (value !== null && typeof value === 'object') {
+      if (seen.has(value)) return '[Circular]'
+      seen.add(value)
+    }
+    return value
+  }
+}
+
+/**
+ * Builds and serializes a production log entry without ever throwing.
+ *
+ * Caller-supplied arguments are merged in verbatim, so a cyclic reference, a
+ * BigInt, or a throwing getter would otherwise raise inside the caller's code
+ * path — losing the line and aborting whatever was being logged about. A
+ * logger must never be able to break its caller.
+ */
+const serializeEntry = (base: Record<string, unknown>, args: unknown[]): string => {
+  try {
+    return JSON.stringify(mergeArgs({ ...base }, args))
+  } catch {}
+
+  try {
+    return JSON.stringify(mergeArgs({ ...base }, args), tolerantReplacer())
+  } catch {}
+
+  return JSON.stringify({ ...base, serializationError: true }, tolerantReplacer())
+}
+
 /**
  * Logger class for standardized console logging
  *
@@ -280,33 +329,17 @@ export class Logger {
       }
     } else {
       // Structured JSON for production — CloudWatch Log Insights auto-parses JSON lines
-      const entry: Record<string, unknown> = {
+      const base: Record<string, unknown> = {
         timestamp,
         level,
         module: this.module,
         message,
       }
       for (const [k, v] of metadataEntries) {
-        entry[k] = v
-      }
-      // Merge extra args into the entry
-      for (const arg of args) {
-        if (
-          arg !== null &&
-          arg !== undefined &&
-          typeof arg === 'object' &&
-          !(arg instanceof Error)
-        ) {
-          Object.assign(entry, arg)
-        } else if (arg instanceof Error) {
-          entry.error = arg.message
-          entry.stack = arg.stack
-        } else if (arg !== null && arg !== undefined) {
-          entry.extra = arg
-        }
+        base[k] = v
       }
 
-      const line = JSON.stringify(entry)
+      const line = serializeEntry(base, args)
       if (level === LogLevel.ERROR) {
         console.error(line)
       } else {