@l.x/logger 0.0.0

package/.depcheckrc

@@ -0,0 +1,9 @@
+ignores: [
+    # Dependencies that depcheck incorrectly marks as unused
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+
+    # Internal packages / workspaces
+    "logger",
+  ]

package/.eslintrc.js

@@ -0,0 +1,18 @@
+module.exports = {
+  extends: ['@luxfi/eslint-config/lib'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': 'off',
+        // Logger interface defines error(msg, error?, context?) — 3 params is inherent to the contract.
+        // Factory functions take (transport, service, parentContext, minLevel) to match the child() pattern.
+        // Restructuring these into options objects would make the API awkward for a logging library.
+        'max-params': ['error', { max: 6 }],
+      },
+    },
+  ],
+}

package/LICENSE

@@ -0,0 +1,122 @@
+Lux Ecosystem License
+Version 1.2, December 2025
+
+Copyright (c) 2020-2025 Lux Industries Inc.
+All rights reserved.
+
+TECHNOLOGY PORTFOLIO - PATENT APPLICATIONS PLANNED
+Contact: licensing@lux.network
+
+================================================================================
+                          TERMS AND CONDITIONS
+================================================================================
+
+1. DEFINITIONS
+
+   "Lux Primary Network" means the official Lux blockchain with Network ID=1
+   and EVM Chain ID=96369.
+   
+   "Authorized Network" means the Lux Primary Network, official testnets/devnets,
+   and any L1/L2/L3 chain descending from the Lux Primary Network.
+   
+   "Descending Chain" means an L1/L2/L3 chain built on, anchored to, or deriving
+   security from the Lux Primary Network or its authorized testnets.
+   
+   "Research Use" means non-commercial academic research, education, personal
+   study, or evaluation purposes.
+   
+   "Commercial Use" means any use in connection with a product or service
+   offered for sale or fee, internal use by a for-profit entity, or any use
+   to generate revenue.
+
+2. GRANT OF LICENSE
+
+   Subject to these terms, Lux Industries Inc grants you a non-exclusive,
+   royalty-free license to:
+   
+   (a) Use for Research Use without restriction;
+   
+   (b) Operate on the Lux Primary Network (Network ID=1, EVM Chain ID=96369);
+   
+   (c) Operate on official Lux testnets and devnets;
+   
+   (d) Operate L1/L2/L3 chains descending from the Lux Primary Network;
+   
+   (e) Build applications within the Lux ecosystem;
+   
+   (f) Contribute improvements back to the original repositories.
+
+3. RESTRICTIONS
+
+   Without a commercial license from Lux Industries Inc, you may NOT:
+   
+   (a) Fork the Lux Network or any Lux software;
+   
+   (b) Create competing networks not descending from Lux Primary Network;
+   
+   (c) Use for Commercial Use outside the Lux ecosystem;
+   
+   (d) Sublicense or transfer rights outside the Lux ecosystem;
+   
+   (e) Use to create competing blockchain networks, exchanges, custody
+       services, or cryptographic systems outside the Lux ecosystem.
+
+4. NO FORKS POLICY
+
+   Lux Industries Inc maintains ZERO TOLERANCE for unauthorized forks.
+   Any fork or deployment on an unauthorized network constitutes:
+   
+   (a) Breach of this license;
+   (b) Grounds for immediate legal action.
+
+5. RIGHTS RESERVATION
+
+   All rights not explicitly granted are reserved by Lux Industries Inc.
+   
+   We plan to apply for patent protection for the technology in this
+   repository. Any implementation outside the Lux ecosystem may require
+   a separate commercial license.
+
+6. DISCLAIMER OF WARRANTY
+
+   THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+7. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LUX INDUSTRIES INC BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+8. TERMINATION
+
+   This license terminates immediately upon any breach, including but not
+   limited to deployment on unauthorized networks or creation of forks.
+
+9. GOVERNING LAW
+
+   This License shall be governed by the laws of the State of Delaware.
+
+10. COMMERCIAL LICENSING
+
+    For commercial use outside the Lux ecosystem:
+    
+    Lux Industries Inc.
+    Email: licensing@lux.network
+    Subject: Commercial License Request
+
+================================================================================
+                              TL;DR
+================================================================================
+
+- Research/academic use = OK
+- Lux Primary Network (Network ID=1, Chain ID=96369) = OK
+- L1/L2/L3 chains descending from Lux Primary Network = OK
+- Commercial products outside Lux ecosystem = Contact licensing@lux.network
+- Forks = Absolutely not
+
+================================================================================
+
+See LP-0012 for full licensing documentation:
+https://github.com/luxfi/lps/blob/main/LPs/lp-0012-ecosystem-licensing.md

package/README.md

@@ -0,0 +1,3 @@
+# @universe/logger
+
+// TODO

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@l.x/logger",
+  "version": "0.0.0",
+  "dependencies": {
+    "source-map-js": "1.2.1",
+    "@l.x/privacy": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.1",
+    "@typescript/native-preview": "7.0.0-dev.20260311.1",
+    "depcheck": "1.4.7",
+    "eslint": "8.57.1",
+    "typescript": "5.8.3",
+    "@luxfi/eslint-config": "^1.0.5"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts"
+  },
+  "private": false,
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "nx typecheck logger",
+    "typecheck:tsgo": "nx typecheck:tsgo logger",
+    "lint": "nx lint logger",
+    "lint:fix": "nx lint:fix logger",
+    "lint:biome": "nx lint:biome logger",
+    "lint:biome:fix": "nx lint:biome:fix logger",
+    "lint:eslint": "nx lint:eslint logger",
+    "lint:eslint:fix": "nx lint:eslint:fix logger",
+    "check:deps:usage": "nx check:deps:usage logger"
+  }
+}

package/project.json

@@ -0,0 +1,18 @@
+{
+  "name": "@l.x/logger",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "pkgs/logger/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "typecheck": {},
+    "typecheck:tsgo": {},
+    "lint:biome": {},
+    "lint:biome:fix": {},
+    "lint:eslint": {},
+    "lint:eslint:fix": {},
+    "lint": {},
+    "lint:fix": {},
+    "check:deps:usage": {}
+  }
+}

package/src/asyncContext.ts

@@ -0,0 +1,24 @@
+/**
+ * Request Context Types
+ *
+ * Defines the RequestContext shape and the abstract RequestStore contract.
+ * The actual AsyncLocalStorage instance is created at the app boundary —
+ * this module has no Node.js dependencies.
+ */
+
+import type { Logger } from './types'
+import type { WideEvent } from './wideEvent'
+
+/** Typed context stored per-request */
+export interface RequestContext {
+  traceId: string
+  logger: Logger
+  wideEvent: WideEvent
+  userId?: string
+}
+
+/** Abstract store — matches AsyncLocalStorage's shape without importing node:async_hooks */
+export interface RequestStore {
+  getStore(): RequestContext | undefined
+  run<R>(store: RequestContext, callback: () => R): R
+}

package/src/clientLogger.ts

@@ -0,0 +1,114 @@
+/**
+ * Client Logger
+ *
+ * Implements the Logger interface by converting log calls into LogEntry
+ * objects and forwarding them to a LogTransport.
+ */
+
+import type { LogContext, LogEntry, Logger, LoggerFactory, LogLevel, LogTransport } from './types'
+import { LOG_LEVEL_ORDER } from './types'
+
+function shouldLog(level: LogLevel, minLevel: LogLevel): boolean {
+  return LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[minLevel]
+}
+
+function serializeError(err: unknown): LogEntry['error'] | undefined {
+  if (err == null) {
+    return undefined
+  }
+  if (err instanceof Error) {
+    return { message: err.message, stack: err.stack }
+  }
+  return { message: String(err) }
+}
+
+function buildEntry(
+  level: LogLevel,
+  message: string,
+  service: string | undefined,
+  context: LogContext | undefined,
+  error?: unknown,
+): LogEntry {
+  return {
+    timestamp: new Date().toISOString(),
+    level,
+    ...(service ? { service } : {}),
+    message,
+    ...(context && Object.keys(context).length > 0 ? { context } : {}),
+    ...(error != null ? { error: serializeError(error) } : {}),
+  }
+}
+
+export function createClientLogger(
+  transport: LogTransport,
+  service?: string,
+  parentContext?: LogContext,
+  minLevel: LogLevel = 'warn',
+): Logger {
+  function mergeContext(context?: LogContext): LogContext | undefined {
+    if (!parentContext) {
+      return context
+    }
+    if (!context) {
+      return parentContext
+    }
+    return { ...parentContext, ...context }
+  }
+
+  return {
+    trace(message, context?): void {
+      if (!shouldLog('trace', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('trace', message, service, mergeContext(context))])
+    },
+
+    debug(message, context?): void {
+      if (!shouldLog('debug', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('debug', message, service, mergeContext(context))])
+    },
+
+    info(message, context?): void {
+      if (!shouldLog('info', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('info', message, service, mergeContext(context))])
+    },
+
+    warn(message, context?): void {
+      if (!shouldLog('warn', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('warn', message, service, mergeContext(context))])
+    },
+
+    error(message, error?, context?): void {
+      if (!shouldLog('error', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('error', message, service, mergeContext(context), error)])
+    },
+
+    fatal(message, error?, context?): void {
+      if (!shouldLog('fatal', minLevel)) {
+        return
+      }
+      transport.send([buildEntry('fatal', message, service, mergeContext(context), error)])
+    },
+
+    child(context): Logger {
+      const merged = parentContext ? { ...parentContext, ...context } : context
+      return createClientLogger(transport, service, merged, minLevel)
+    },
+  }
+}
+
+export function createClientLoggerFactory(transport: LogTransport, minLevel: LogLevel = 'warn'): LoggerFactory {
+  return {
+    createLogger(service): Logger {
+      return createClientLogger(transport, service, undefined, minLevel)
+    },
+  }
+}

package/src/consoleLogger.ts

@@ -0,0 +1,137 @@
+/**
+ * Console Logger Implementation
+ *
+ * Simple console-based logger for development and debugging.
+ * Structured output with timestamps and context.
+ */
+
+import type { LogContext, Logger, LoggerFactory, LogLevel } from './types'
+import { LOG_LEVEL_ORDER } from './types'
+
+function shouldLog(level: LogLevel, minLevel: LogLevel): boolean {
+  return LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[minLevel]
+}
+
+/**
+ * Format timestamp for log output
+ */
+function formatTimestamp(): string {
+  const now = new Date()
+  return now.toISOString().slice(11, 23) // HH:mm:ss.SSS
+}
+
+/**
+ * Format context for log output
+ */
+function formatContext(context?: LogContext): string {
+  if (!context || Object.keys(context).length === 0) {
+    return ''
+  }
+  return ` ${JSON.stringify(context)}`
+}
+
+/**
+ * Create a console logger with optional service prefix and inherited context
+ */
+export function createConsoleLogger(
+  service?: string,
+  parentContext?: LogContext,
+  minLevel: LogLevel = 'debug',
+): Logger {
+  const prefix = service ? `[${service}]` : ''
+
+  function mergeContext(context?: LogContext): LogContext | undefined {
+    if (!parentContext) {
+      return context
+    }
+    if (!context) {
+      return parentContext
+    }
+    return { ...parentContext, ...context }
+  }
+
+  return {
+    trace(message: string, context?: LogContext): void {
+      if (!shouldLog('trace', minLevel)) {
+        return
+      }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.debug(`${formatTimestamp()} TRACE ${prefix} ${message}${formatContext(mergeContext(context))}`)
+    },
+
+    debug(message: string, context?: LogContext): void {
+      if (!shouldLog('debug', minLevel)) {
+        return
+      }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.debug(`${formatTimestamp()} DEBUG ${prefix} ${message}${formatContext(mergeContext(context))}`)
+    },
+
+    info(message: string, context?: LogContext): void {
+      if (!shouldLog('info', minLevel)) {
+        return
+      }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.info(`${formatTimestamp()} INFO ${prefix} ${message}${formatContext(mergeContext(context))}`)
+    },
+
+    warn(message: string, context?: LogContext): void {
+      if (!shouldLog('warn', minLevel)) {
+        return
+      }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.warn(`${formatTimestamp()} WARN ${prefix} ${message}${formatContext(mergeContext(context))}`)
+    },
+
+    error(message: string, error?: unknown, context?: LogContext): void {
+      if (!shouldLog('error', minLevel)) {
+        return
+      }
+      const errorDetails = error instanceof Error ? { name: error.name, message: error.message } : { error }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.error(`${formatTimestamp()} ERROR ${prefix} ${message}`, errorDetails, mergeContext(context) ?? {})
+    },
+
+    fatal(message: string, error?: unknown, context?: LogContext): void {
+      if (!shouldLog('fatal', minLevel)) {
+        return
+      }
+      const errorDetails = error instanceof Error ? { name: error.name, message: error.message } : { error }
+      // biome-ignore lint/suspicious/noConsole: Logger implementation
+      console.error(`${formatTimestamp()} FATAL ${prefix} ${message}`, errorDetails, mergeContext(context) ?? {})
+    },
+
+    child(context: LogContext): Logger {
+      const merged = parentContext ? { ...parentContext, ...context } : context
+      return createConsoleLogger(service, merged, minLevel)
+    },
+  }
+}
+
+/**
+ * Console logger factory — defaults to 'info' level to suppress DEBUG noise
+ */
+export function createConsoleLoggerFactory(minLevel: LogLevel = 'info'): LoggerFactory {
+  return {
+    createLogger(service: string): Logger {
+      return createConsoleLogger(service, undefined, minLevel)
+    },
+  }
+}
+
+export const consoleLoggerFactory: LoggerFactory = createConsoleLoggerFactory('info')
+
+/**
+ * Default noop logger for when logging is disabled
+ */
+export const noopLogger: Logger = {
+  trace: () => {},
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  fatal: () => {},
+  child(): Logger {
+    return noopLogger
+  },
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Client-safe exports — no Node.js dependencies.
+// Server-only exports (createServerLogger, createStackResolver, etc.) live in @l.x/logger/server.
+
+export { createClientLogger, createClientLoggerFactory } from './clientLogger'
+export { consoleLoggerFactory, createConsoleLogger, createConsoleLoggerFactory, noopLogger } from './consoleLogger'
+export type { RequestScopedContext } from './requestContext'
+export { requestContext } from './requestContext'
+export type { StackResolver, StackResolverCtx } from './sourceMapResolver'
+export {
+  createStructuredJsonLogger,
+  createStructuredJsonLoggerFactory,
+  structuredJsonLoggerFactory,
+} from './structuredJsonLogger'
+export type { BufferedTransportOptions } from './transports/buffered'
+export { createBufferedTransport } from './transports/buffered'
+export { createConsoleTransport } from './transports/console'
+export type { PendingTransport } from './transports/pending'
+export { createPendingTransport } from './transports/pending'
+export type { LogIngestionClient } from './transports/trpc'
+export { createTrpcLogTransport } from './transports/trpc'
+export type { LogContext, LogEntry, Logger, LoggerFactory, LogLevel, LogTransport } from './types'
+export { LOG_LEVEL_ORDER } from './types'
+// Types only — value exports in @l.x/logger/server
+export type { ErrorSource, SerializedError, WideEvent, WideEventFactory } from './wideEvent'

package/src/requestContext.ts

@@ -0,0 +1,54 @@
+/**
+ * Request-scoped context shared between Hono middleware and tRPC.
+ *
+ * Uses a Map keyed by trace_id (set as x-trace-id header on the request).
+ * WeakMap<Request> doesn't work because Hono sub-app routing may create
+ * new Request objects, breaking object identity.
+ */
+
+import type { Logger } from './types'
+import type { WideEvent } from './wideEvent'
+
+export interface RequestScopedContext {
+  wideEvent: WideEvent
+  logger: Logger
+}
+
+interface StoredContext extends RequestScopedContext {
+  createdAt: number
+}
+
+/** Requests older than 5 minutes are considered dead */
+const MAX_AGE_MS = 5 * 60 * 1000
+/** Evict stale entries every 100 requests to bound Map growth */
+const EVICTION_INTERVAL = 100
+
+const contextMap = new Map<string, StoredContext>()
+let operationCount = 0
+
+function evictStaleEntries(): void {
+  const now = Date.now()
+  for (const [key, value] of contextMap) {
+    if (now - value.createdAt > MAX_AGE_MS) {
+      contextMap.delete(key)
+    }
+  }
+}
+
+export const requestContext = {
+  set(traceId: string, ctx: RequestScopedContext): void {
+    contextMap.set(traceId, { ...ctx, createdAt: Date.now() })
+    if (++operationCount % EVICTION_INTERVAL === 0) {
+      evictStaleEntries()
+    }
+  },
+
+  get(traceId: string): RequestScopedContext | undefined {
+    return contextMap.get(traceId)
+  },
+
+  /** Clean up after request completes to prevent memory leaks */
+  delete(traceId: string): void {
+    contextMap.delete(traceId)
+  },
+}

package/src/server.ts

@@ -0,0 +1,18 @@
+// Server-only exports — requires Node.js.
+// Re-exports everything from the client-safe barrel for convenience.
+
+export type { RequestContext, RequestStore } from './asyncContext'
+export * from './index'
+export type { RequestScopedContext } from './requestContext'
+export { requestContext } from './requestContext'
+export type { ServerLogger, ServerLoggerCtx } from './serverLogger'
+export { createServerLogger } from './serverLogger'
+export type { StackResolver, StackResolverCtx } from './sourceMapResolver'
+export { createStackResolver } from './sourceMapResolver'
+export {
+  createStructuredJsonLogger,
+  createStructuredJsonLoggerFactory,
+  structuredJsonLoggerFactory,
+} from './structuredJsonLogger'
+export type { ErrorSource, SerializedError, WideEvent, WideEventFactory } from './wideEvent'
+export { createWideEvent, serializeErrorForWideEvent, wideEventFactory } from './wideEvent'

package/src/serverLogger.ts

@@ -0,0 +1,70 @@
+/**
+ * Server Logger Factory
+ *
+ * createServerLogger(ctx) → ServerLogger
+ *
+ * The app boundary provides platform deps (ALS, write function).
+ * Returns a wired instance with .create(), .getRequestLogger(), .runWithContext().
+ */
+
+import type { RequestContext, RequestStore } from './asyncContext'
+import type { RequestScopedContext } from './requestContext'
+import { createStructuredJsonLoggerFactory } from './structuredJsonLogger'
+import type { Logger, LoggerFactory, LogLevel } from './types'
+
+export interface ServerLoggerCtx {
+  /** The AsyncLocalStorage instance — created by the app */
+  requestStore: RequestStore
+  /** Map-based fallback context (import { requestContext } from '@l.x/logger') */
+  requestContext: { get(traceId: string): RequestScopedContext | undefined }
+  /** Minimum log level (defaults to 'info') */
+  minLevel?: LogLevel
+  /** Service name for the fallback logger (defaults to 'unknown') */
+  serviceName?: string
+}
+
+export interface ServerLogger {
+  /** Create a named logger: logger.create('dev-portal') */
+  create: (service: string) => Logger
+  /** Get the request-scoped logger (ALS → Map fallback → fallback logger) */
+  getRequestLogger: (request: Request) => Logger
+  /** Get the current request context from the ALS (if inside runWithContext) */
+  getRequestContext: () => RequestContext | undefined
+  /** Wrap a request in context scope */
+  runWithContext: <R>(ctx: RequestContext, fn: () => R) => R
+  /** The underlying factory (for passing to code that expects LoggerFactory) */
+  loggerFactory: LoggerFactory
+}
+
+export function createServerLogger(ctx: ServerLoggerCtx): ServerLogger {
+  const factory = createStructuredJsonLoggerFactory(ctx.minLevel ?? 'info')
+  const fallbackLogger = factory.createLogger(ctx.serviceName ?? 'unknown')
+
+  function getRequestLogger(request: Request): Logger {
+    // Primary: ALS context
+    const asyncCtx = ctx.requestStore.getStore()
+    if (asyncCtx) {
+      return asyncCtx.logger
+    }
+
+    // Secondary: Map-based context via trace ID header
+    const traceId = request.headers.get('x-trace-id')
+    if (traceId) {
+      const mapCtx = ctx.requestContext.get(traceId)
+      if (mapCtx) {
+        return mapCtx.logger
+      }
+    }
+
+    fallbackLogger.warn('request_logger.fallback', { reason: 'missing_trace_id' })
+    return fallbackLogger
+  }
+
+  return {
+    create: (service: string) => factory.createLogger(service),
+    getRequestLogger,
+    getRequestContext: () => ctx.requestStore.getStore(),
+    runWithContext: <R>(reqCtx: RequestContext, fn: () => R): R => ctx.requestStore.run(reqCtx, fn),
+    loggerFactory: factory,
+  }
+}

package/src/sourceMapResolver.ts

@@ -0,0 +1,99 @@
+import type { RawSourceMap } from 'source-map-js'
+import { SourceMapConsumer } from 'source-map-js'
+
+export interface StackResolver {
+  resolve(stack: string): string
+}
+
+export interface StackResolverCtx {
+  sourceMapDir: string
+  fallbackDirs?: string[]
+  fs: {
+    readdirSync: (path: string) => string[]
+    readFileSync: (path: string, encoding: BufferEncoding) => string
+  }
+  path: {
+    basename: (path: string) => string
+    join: (...paths: string[]) => string
+  }
+}
+
+export function createStackResolver(ctx: StackResolverCtx): StackResolver {
+  const { sourceMapDir, fallbackDirs = [], fs, path } = ctx
+  // Lazy-load: parse source maps on first use, not at startup
+  let consumers: Map<string, SourceMapConsumer> | undefined
+
+  function loadFromDir(dir: string, target: Map<string, SourceMapConsumer>): void {
+    try {
+      const files = fs.readdirSync(dir).filter((f) => f.endsWith('.map'))
+      for (const file of files) {
+        const jsFile = file.replace(/\.map$/, '')
+        if (target.has(jsFile)) {
+          continue
+        } // first dir wins
+        const mapContent = fs.readFileSync(path.join(dir, file), 'utf-8')
+        const rawMap = JSON.parse(mapContent) as RawSourceMap
+        target.set(jsFile, new SourceMapConsumer(rawMap))
+      }
+    } catch {
+      // Dir doesn't exist or isn't readable — skip
+    }
+  }
+
+  function getConsumers(): Map<string, SourceMapConsumer> {
+    if (consumers) {
+      return consumers
+    }
+    consumers = new Map()
+    loadFromDir(sourceMapDir, consumers)
+    for (const dir of fallbackDirs) {
+      loadFromDir(dir, consumers)
+    }
+    return consumers
+  }
+
+  // Parse stack frames like:
+  // "    at functionName (https://host/assets/index-abc123.js:10:42)"
+  // "    at https://host/assets/index-abc123.js:10:42"
+  // eslint-disable-next-line security/detect-unsafe-regex -- regex is applied to individual stack frame lines, not unbounded input
+  const FRAME_RE = /^(\s+at\s+(?:.*?\s+\()?)(.+?):(\d+):(\d+)(\)?\s*)$/
+
+  return {
+    resolve(stack: string): string {
+      const maps = getConsumers()
+      if (maps.size === 0) {
+        return stack
+      }
+
+      return stack
+        .split('\n')
+        .map((line) => {
+          const match = FRAME_RE.exec(line)
+          if (!match) {
+            return line
+          }
+
+          const [, prefix, filePath, lineStr, colStr, suffix] = match
+          if (!prefix || !filePath || !lineStr || !colStr || !suffix) {
+            return line
+          }
+          const fileName = path.basename(filePath)
+          const consumer = maps.get(fileName)
+          if (!consumer) {
+            return line
+          }
+
+          const pos = consumer.originalPositionFor({
+            line: parseInt(lineStr, 10),
+            column: parseInt(colStr, 10),
+          })
+
+          if (pos.source) {
+            return `${prefix}${pos.source}:${pos.line}:${pos.column}${suffix}`
+          }
+          return line
+        })
+        .join('\n')
+    },
+  }
+}

package/src/structuredJsonLogger.ts

@@ -0,0 +1,141 @@
+/**
+ * Structured JSON Logger Implementation
+ *
+ * Writes single JSON lines to stdout for Datadog Agent sidecar ingestion.
+ * NOT console.log — raw process.stdout.write to avoid formatting overhead.
+ *
+ * Integrates PII scrubbing as the last step before serialization (single enforcement point).
+ * Adds Datadog correlation fields for trace/log correlation.
+ */
+
+import type { Scrubber } from '@l.x/privacy'
+import { createScrubber } from '@l.x/privacy'
+import type { LogContext, Logger, LoggerFactory, LogLevel } from './types'
+import { LOG_LEVEL_ORDER } from './types'
+import { serializeErrorForWideEvent } from './wideEvent'
+
+function shouldLog(level: LogLevel, minLevel: LogLevel): boolean {
+  return LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[minLevel]
+}
+
+/** DD correlation defaults — trace/span IDs are empty until overridden by request-scoped .child() context. */
+function getDDCorrelation(service: string | undefined): Record<string, string> {
+  return {
+    'dd.trace_id': '',
+    'dd.span_id': '',
+    'dd.service': process.env['DD_SERVICE'] || service || '',
+    'dd.version': process.env['DD_VERSION'] || '',
+    'dd.env': process.env['DD_ENV'] || '',
+  }
+}
+
+function writeLine(
+  level: LogLevel,
+  service: string | undefined,
+  message: string,
+  scrub: Scrubber,
+  context?: LogContext,
+  error?: unknown,
+): void {
+  const line: Record<string, unknown> = {
+    timestamp: new Date().toISOString(),
+    level,
+    ...(service ? { service } : {}),
+    message,
+    ...getDDCorrelation(service),
+    ...context,
+  }
+  if (error != null) {
+    line['error'] = serializeErrorForWideEvent(error)
+  }
+
+  // Scrub is the LAST step before serialization — single enforcement point
+  const scrubbed = scrub(line)
+  process.stdout.write(`${JSON.stringify(scrubbed)}\n`)
+}
+
+/**
+ * Create a structured JSON logger that writes newline-delimited JSON to stdout.
+ * Scrubber is injected explicitly — not imported as a side effect.
+ */
+export function createStructuredJsonLogger(
+  service?: string,
+  parentContext?: LogContext,
+  minLevel: LogLevel = 'info',
+  scrub?: Scrubber,
+): Logger {
+  const scrubFn = scrub ?? createScrubber()
+
+  function mergeContext(context?: LogContext): LogContext | undefined {
+    if (!parentContext) {
+      return context
+    }
+    if (!context) {
+      return parentContext
+    }
+    return { ...parentContext, ...context }
+  }
+
+  return {
+    trace(message: string, context?: LogContext): void {
+      if (!shouldLog('trace', minLevel)) {
+        return
+      }
+      writeLine('trace', service, message, scrubFn, mergeContext(context))
+    },
+
+    debug(message: string, context?: LogContext): void {
+      if (!shouldLog('debug', minLevel)) {
+        return
+      }
+      writeLine('debug', service, message, scrubFn, mergeContext(context))
+    },
+
+    info(message: string, context?: LogContext): void {
+      if (!shouldLog('info', minLevel)) {
+        return
+      }
+      writeLine('info', service, message, scrubFn, mergeContext(context))
+    },
+
+    warn(message: string, context?: LogContext): void {
+      if (!shouldLog('warn', minLevel)) {
+        return
+      }
+      writeLine('warn', service, message, scrubFn, mergeContext(context))
+    },
+
+    error(message: string, error?: unknown, context?: LogContext): void {
+      if (!shouldLog('error', minLevel)) {
+        return
+      }
+      writeLine('error', service, message, scrubFn, mergeContext(context), error)
+    },
+
+    fatal(message: string, error?: unknown, context?: LogContext): void {
+      if (!shouldLog('fatal', minLevel)) {
+        return
+      }
+      writeLine('fatal', service, message, scrubFn, mergeContext(context), error)
+    },
+
+    child(context: LogContext): Logger {
+      const merged = parentContext ? { ...parentContext, ...context } : context
+      return createStructuredJsonLogger(service, merged, minLevel, scrubFn)
+    },
+  }
+}
+
+/**
+ * Structured JSON logger factory — use in production (ECS + Datadog)
+ */
+export function createStructuredJsonLoggerFactory(minLevel: LogLevel = 'info'): LoggerFactory {
+  const scrub = createScrubber()
+  return {
+    createLogger(service: string): Logger {
+      return createStructuredJsonLogger(service, undefined, minLevel, scrub)
+    },
+  }
+}
+
+export const structuredJsonLoggerFactory: LoggerFactory = createStructuredJsonLoggerFactory('info')

package/src/transports/buffered.ts

@@ -0,0 +1,64 @@
+/**
+ * BufferedTransport
+ *
+ * Wraps any LogTransport with batching. Flushes when the buffer
+ * hits maxSize, the timer expires, or the page becomes hidden.
+ */
+
+import type { LogEntry, LogTransport } from '../types'
+
+export interface BufferedTransportOptions {
+  maxSize?: number
+  flushIntervalMs?: number
+}
+
+const DEFAULT_MAX_SIZE = 10
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000
+
+export function createBufferedTransport(inner: LogTransport, options?: BufferedTransportOptions): LogTransport {
+  const maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE
+  const flushIntervalMs = options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS
+
+  let buffer: LogEntry[] = []
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  function flush(): void {
+    if (timer !== null) {
+      clearTimeout(timer)
+      timer = null
+    }
+    if (buffer.length === 0) {
+      return
+    }
+    const batch = buffer
+    buffer = []
+    inner.send(batch)
+  }
+
+  function scheduleFlush(): void {
+    if (timer !== null) {
+      return
+    }
+    timer = setTimeout(flush, flushIntervalMs)
+  }
+
+  // Flush on page hide (tab switch, navigation, close)
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'hidden') {
+        flush()
+      }
+    })
+  }
+
+  return {
+    send(entries): void {
+      buffer.push(...entries)
+      if (buffer.length >= maxSize) {
+        flush()
+      } else {
+        scheduleFlush()
+      }
+    },
+  }
+}

package/src/transports/console.ts

@@ -0,0 +1,39 @@
+/**
+ * ConsoleLogTransport
+ *
+ * Writes log entries to the browser console. Dev only.
+ */
+
+import type { LogEntry, LogTransport } from '../types'
+
+function formatEntry(entry: LogEntry): string {
+  const service = entry.service ? `[${entry.service}] ` : ''
+  return `${entry.timestamp} ${entry.level.toUpperCase()} ${service}${entry.message}`
+}
+
+export function createConsoleTransport(): LogTransport {
+  return {
+    send(entries): void {
+      for (const entry of entries) {
+        const formatted = formatEntry(entry)
+        const extra = entry.context ?? {}
+
+        switch (entry.level) {
+          case 'error':
+          case 'fatal':
+            // biome-ignore lint/suspicious/noConsole: Logger transport implementation
+            console.error(formatted, entry.error ?? '', extra)
+            break
+          case 'warn':
+            // biome-ignore lint/suspicious/noConsole: Logger transport implementation
+            console.warn(formatted, extra)
+            break
+          default:
+            // biome-ignore lint/suspicious/noConsole: Logger transport implementation
+            console.debug(formatted, extra)
+            break
+        }
+      }
+    },
+  }
+}

package/src/transports/pending.ts

@@ -0,0 +1,42 @@
+/**
+ * PendingTransport
+ *
+ * Buffers log entries until a real transport is connected.
+ * Used as the initial transport so client code can log before
+ * the tRPC client (or any real transport) is available.
+ */
+
+import type { LogTransport } from '../types'
+
+export interface PendingTransport extends LogTransport {
+  connect(transport: LogTransport): void
+}
+
+const DEFAULT_MAX_BUFFER = 100
+
+export function createPendingTransport(maxBuffer: number = DEFAULT_MAX_BUFFER): PendingTransport {
+  let buffer: Parameters<LogTransport['send']>[0] = []
+  let delegate: LogTransport | null = null
+
+  return {
+    send(entries): void {
+      if (delegate) {
+        delegate.send(entries)
+        return
+      }
+      buffer.push(...entries)
+      // Drop oldest entries if buffer exceeds max
+      if (buffer.length > maxBuffer) {
+        buffer = buffer.slice(buffer.length - maxBuffer)
+      }
+    },
+
+    connect(transport): void {
+      delegate = transport
+      if (buffer.length > 0) {
+        transport.send(buffer)
+        buffer = []
+      }
+    },
+  }
+}

package/src/transports/trpc.ts

@@ -0,0 +1,20 @@
+/**
+ * TrpcLogTransport
+ *
+ * Sends log entries to the server via a tRPC mutation.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+
+import type { LogEntry, LogTransport } from '../types'
+
+export interface LogIngestionClient {
+  logs: { ingest: { mutate: (input: { entries: LogEntry[] }) => Promise<unknown> } }
+}
+
+export function createTrpcLogTransport(client: LogIngestionClient): LogTransport {
+  return {
+    send(entries): void {
+      client.logs.ingest.mutate({ entries }).catch(() => {})
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Logger Interface
+ *
+ * Simple logger contract for services and repositories.
+ * Allows swapping between console logging (dev) and production logging.
+ */
+
+/**
+ * Log context for structured logging
+ */
+export interface LogContext {
+  /** Service or component name */
+  service?: string
+  /** Operation being performed */
+  operation?: string
+  /** User ID if available */
+  userId?: string
+  /** Additional metadata */
+  [key: string]: unknown
+}
+
+/**
+ * Logger interface for dependency injection
+ */
+export interface Logger {
+  /** Trace level logging - finest granularity, usually off */
+  trace(message: string, context?: LogContext): void
+
+  /** Debug level logging - development only */
+  debug(message: string, context?: LogContext): void
+
+  /** Info level logging - general information */
+  info(message: string, context?: LogContext): void
+
+  /** Warning level logging - potential issues */
+  warn(message: string, context?: LogContext): void
+
+  /** Error level logging - errors and exceptions */
+  error(message: string, error?: unknown, context?: LogContext): void
+
+  /** Fatal level logging - unrecoverable errors, process should exit */
+  fatal(message: string, error?: unknown, context?: LogContext): void
+
+  /** Create a child logger with preset context fields merged into every log call */
+  child(context: LogContext): Logger
+}
+
+/**
+ * Log levels in order of severity.
+ * Loggers should only emit messages at or above their configured level.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  trace: 0,
+  debug: 1,
+  info: 2,
+  warn: 3,
+  error: 4,
+  fatal: 5,
+}
+
+/**
+ * Factory to create a child logger with preset context
+ */
+export interface LoggerFactory {
+  /** Create a logger with preset service context */
+  createLogger(service: string): Logger
+}
+
+/** A single log entry ready for transport */
+export interface LogEntry {
+  timestamp: string
+  level: LogLevel
+  service?: string
+  message: string
+  context?: LogContext
+  error?: { message: string; stack?: string }
+}
+
+/** Moves log entries from point A to point B */
+export interface LogTransport {
+  send(entries: LogEntry[]): void
+}

package/src/wideEvent.ts

@@ -0,0 +1,128 @@
+/**
+ * Wide Event
+ *
+ * Canonical log line pattern: accumulate fields throughout a request lifecycle,
+ * then emit one structured log line at completion.
+ *
+ * Goal: one log line per request with enough context to diagnose any error
+ * without cross-referencing other logs.
+ */
+
+import type { Logger } from './types'
+
+/** Where the error originated — for Datadog faceting/alerting */
+export type ErrorSource = 'trpc_procedure' | 'loader' | 'upstream_5xx' | 'unhandled'
+
+/** Recursive error shape that preserves cause chains */
+export interface SerializedError {
+  class: string
+  message: string
+  stack?: string
+  code?: string
+  cause?: SerializedError
+}
+
+/**
+ * Recursively serialize an error, walking the .cause chain.
+ * Pure function — no side effects, no implicit deps.
+ */
+export function serializeErrorForWideEvent(err: unknown, depth = 0): SerializedError {
+  // Guard against infinite/absurd cause chains
+  if (depth > 5) {
+    return { class: 'TruncatedCauseChain', message: '(cause chain exceeded 5 levels)' }
+  }
+
+  if (err instanceof Error) {
+    return {
+      class: err.constructor.name,
+      message: err.message,
+      stack: err.stack,
+      ...('code' in err && err.code ? { code: String(err.code) } : {}),
+      ...(err.cause ? { cause: serializeErrorForWideEvent(err.cause, depth + 1) } : {}),
+    }
+  }
+
+  if (err !== undefined && err !== null) {
+    return { class: typeof err, message: String(err) }
+  }
+
+  return { class: 'Unknown', message: '(no error value)' }
+}
+
+export interface WideEvent {
+  /** Add fields that accumulate through the request lifecycle */
+  add(fields: Record<string, unknown>): void
+  /** Record a procedure span (name, duration, outcome) */
+  addProcedure(span: { name: string; duration_ms: number; outcome: 'success' | 'error'; error_code?: string }): void
+  /** Capture a fully serialized error with cause chain + source classification */
+  addError(error: unknown, source?: ErrorSource): void
+  /** Flush the canonical log line at request completion */
+  flush(logger: Logger, outcome: 'success' | 'error'): void
+}
+
+export interface WideEventFactory {
+  create(req: Request): WideEvent
+}
+
+/**
+ * Create a wide event for a request.
+ * Does NOT generate its own trace_id — relies on the logger's child context
+ * for trace correlation (single source of truth for trace_id).
+ */
+export function createWideEvent(req: Request): WideEvent {
+  const url = new URL(req.url)
+  const method = req.method
+  const path = url.pathname
+  const start_time = Date.now()
+
+  const fields: Record<string, unknown> = {}
+  const procedures: Array<{ name: string; duration_ms: number; outcome: 'success' | 'error'; error_code?: string }> = []
+  let capturedError: SerializedError | undefined
+  let errorSource: ErrorSource | undefined
+
+  return {
+    add(newFields: Record<string, unknown>): void {
+      Object.assign(fields, newFields)
+    },
+
+    addProcedure(span): void {
+      procedures.push(span)
+    },
+
+    addError(error: unknown, source?: ErrorSource): void {
+      capturedError = serializeErrorForWideEvent(error)
+      if (source) {
+        errorSource = source
+      }
+    },
+
+    flush(logger: Logger, outcome: 'success' | 'error'): void {
+      const duration_ms = Date.now() - start_time
+      const payload = {
+        method,
+        path,
+        outcome,
+        duration_ms,
+        ...(procedures.length > 0 ? { procedures } : {}),
+        ...(capturedError && outcome === 'error' ? { error: capturedError } : {}),
+        ...(errorSource && outcome === 'error' ? { error_source: errorSource } : {}),
+        ...fields,
+      }
+
+      // Flush at the right log level so Datadog can index/alert on severity.
+      // Error details are already in payload.error (pre-serialized) — don't pass
+      // as the error param to avoid double-serialization by the structured logger.
+      if (outcome === 'error') {
+        logger.error('request.complete', undefined, payload)
+      } else {
+        logger.info('request.complete', payload)
+      }
+    },
+  }
+}
+
+export const wideEventFactory: WideEventFactory = {
+  create(req: Request): WideEvent {
+    return createWideEvent(req)
+  },
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../config/tsconfig/app.json",
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.json",
+    "src/global.d.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx"
+  ],
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "types": ["node"],
+    "paths": {}
+  },
+  "references": [
+    {
+      "path": "../privacy"
+    },
+    {
+      "path": "../eslint-config"
+    }
+  ]
+}

package/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "preserveSymlinks": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", "**/*.json"],
+  "exclude": ["node_modules"]
+}