@friggframework/core 2.0.0-next.112 → 2.0.0-next.113

package/queues/queuer-util.js

@@ -1,5 +1,6 @@
 const { v4: uuid } = require('uuid');
 const { SQSClient, SendMessageCommand, SendMessageBatchCommand } = require('@aws-sdk/client-sqs');
+const { summarizeMessageBody } = require('../logs/summarize-event');
 
 const awsConfigOptions = () => {
     const config = {};
@@ -18,21 +19,6 @@ const awsConfigOptions = () => {
 
 const sqs = new SQSClient(awsConfigOptions());
 
-// Best-effort extraction of the logical event/processId/integrationId from a
-// JSON message body. Used only for log correlation — never throws.
-const summarizeMessageBody = (bodyStr) => {
-    try {
-        const parsed = JSON.parse(bodyStr);
-        return {
-            event: parsed?.event,
-            processId: parsed?.data?.processId,
-            integrationId: parsed?.data?.integrationId,
-        };
-    } catch {
-        return {};
-    }
-};
-
 // Inspect SendMessageBatchResult for partial failures and log them.
 // AWS SendMessageBatch can succeed at the HTTP level while individual entries
 // are rejected (KMS errors, per-entry throttling, service errors). Callers that

package/telemetry/bind-telemetry-context.js

@@ -67,6 +67,10 @@ function bindTelemetryContext(base, getContext) {
                 ? base.shutdown(...args)
                 : undefined,
         isEnabled: (...args) => base.isEnabled(...args),
+        getActiveSpanContext: () =>
+            typeof base.getActiveSpanContext === 'function'
+                ? base.getActiveSpanContext()
+                : null,
     };
 }
 

package/telemetry/instrument-handler.js

@@ -1,3 +1,5 @@
+const { getLoggerScope, runInContext } = require('../logs/context');
+
 /**
  * Wraps a single integration handler invocation with a span + the
  * `frigg.handler.invocations` counter. Shared by the two
@@ -16,6 +18,15 @@
  * @param {{event: string, eventType: string}} descriptor Event name + bounded type.
  * @param {Function} fn The handler invocation.
  */
+// The trace link to the logs (ADR-048 §7): span attributes only, never labels.
+function scopeIdAttributes() {
+    const { requestId, messageId } = getLoggerScope();
+    const attributes = {};
+    if (requestId !== undefined && requestId !== null) attributes.requestId = requestId;
+    if (messageId !== undefined && messageId !== null) attributes.messageId = messageId;
+    return attributes;
+}
+
 async function instrumentHandler(telemetry, descriptor = {}, fn) {
     if (!telemetry || typeof telemetry.span !== 'function') {
         return fn();
@@ -36,6 +47,7 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
                     integration_type: integrationType,
                     event: eventType,
                     event_name: eventName,
+                    ...scopeIdAttributes(),
                 });
             }
             // `event_name` (potentially high-cardinality action id) rides the
@@ -70,6 +82,11 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
             }
         });
 
+    // The logger scope goes straight into the one store, so a custom
+    // telemetry service never sees the logger sub-object.
+    const runInLoggerScope = () =>
+        runInContext({ log: { integrationEvent: eventName } }, runInstrumented);
+
     if (typeof telemetry.withContext === 'function') {
         return telemetry.withContext(
             {
@@ -78,10 +95,10 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
                 integrationType: context.integrationType,
                 version: context.version,
             },
-            runInstrumented
+            runInLoggerScope
         );
     }
-    return runInstrumented();
+    return runInLoggerScope();
 }
 
 module.exports = { instrumentHandler };

package/telemetry/no-op-telemetry.js

@@ -62,6 +62,10 @@ class NoOpTelemetry {
     isEnabled() {
         return false;
     }
+
+    getActiveSpanContext() {
+        return null;
+    }
 }
 
 module.exports = { NoOpTelemetry };

package/telemetry/otel-telemetry.js

@@ -17,6 +17,11 @@ const {
     runWithTelemetryContext,
     mergeTelemetryContext,
 } = require('./telemetry-context');
+const { serializeError } = require('../logs/serialize');
+const { LOGGER_SCOPE_KEY } = require('../logs/context');
+
+const BAGGAGE_TYPES = new Set(['string', 'number', 'boolean', 'bigint']);
+const isBaggageValue = (value) => BAGGAGE_TYPES.has(typeof value);
 
 const TRACER_NAME = 'frigg';
 const METRIC_EXPORT_INTERVAL_MS =
@@ -138,6 +143,15 @@ class OtelTelemetry {
         this._bus.emit('event', payload);
     }
 
+    getActiveSpanContext() {
+        const spanContext = otelApi.trace.getActiveSpan()?.spanContext();
+        if (!spanContext || !otelApi.isSpanContextValid(spanContext)) {
+            return null;
+        }
+        const { traceId, spanId, traceFlags } = spanContext;
+        return { traceId, spanId, traceFlags };
+    }
+
     startSpan(name, options) {
         return this._tracer.startSpan(name, options);
     }
@@ -150,10 +164,16 @@ class OtelTelemetry {
                 span.setStatus({ code: otelApi.SpanStatusCode.OK });
                 return result;
             } catch (err) {
-                span.recordException(err);
+                const serialized = serializeError(err);
+                span.recordException({
+                    name: serialized.type,
+                    message: serialized.message,
+                    stack: serialized.stack,
+                    code: serialized.code,
+                });
                 span.setStatus({
                     code: otelApi.SpanStatusCode.ERROR,
-                    message: err && err.message,
+                    message: serialized.message,
                 });
                 throw err;
             } finally {
@@ -170,10 +190,9 @@ class OtelTelemetry {
      */
     async withContext(attributes = {}, fn) {
         const entries = {};
-        for (const [key, value] of Object.entries(attributes)) {
-            if (value !== undefined && value !== null) {
-                entries[key] = { value: String(value) };
-            }
+        for (const [key, value] of Object.entries(attributes || {})) {
+            if (key === LOGGER_SCOPE_KEY || !isBaggageValue(value)) continue;
+            entries[key] = { value: String(value) };
         }
         const baggage = otelApi.propagation.createBaggage(entries);
         const ctx = otelApi.propagation.setBaggage(

package/telemetry/telemetry-context.js

@@ -1,8 +1,13 @@
-const { AsyncLocalStorage } = require('node:async_hooks');
+const {
+    runInContext,
+    getContext,
+    hasOnlyLoggerKeys,
+    LOGGER_SCOPE_KEY,
+} = require('../logs/context');
 
 /**
- * Ambient telemetry context. A single process-wide AsyncLocalStorage
- * holds the standard identifiers ({integrationId, integrationType, userId,
+ * Ambient telemetry context. The one process-wide AsyncLocalStorage
+ * (owned by logs/context.js, shared with the logger scope) holds the standard identifiers ({integrationId, integrationType, userId,
  * version, ...}) for the duration of a handler, set once at the handler seam via
  * `telemetry.withContext(...)`. Any emission during that async scope — including
  * deep calls like an API-module request — reads the ambient context, so the
@@ -11,24 +16,30 @@ const { AsyncLocalStorage } = require('node:async_hooks');
  * on the no-op path). This is the propagation mechanism the plan intended.
  *
  * Only bus-payload `context` is populated from here; high-cardinality ids never
- * touch OTel metric labels.
+ * touch OTel metric labels. A nested run merges: an undefined key keeps the
+ * outer value, an explicit null is stored as null.
  */
-const store = new AsyncLocalStorage();
+function withoutLoggerKeys(store) {
+    if (!store || hasOnlyLoggerKeys(store)) return null;
+    const { [LOGGER_SCOPE_KEY]: _logger, ...rest } = store;
+    return rest;
+}
 
 function runWithTelemetryContext(context, fn) {
-    return store.run(context || {}, fn);
+    return runInContext(context, fn);
 }
 
 function getTelemetryContextStore() {
-    return store.getStore() || null;
+    return withoutLoggerKeys(getContext());
 }
 
 /**
  * Merge the ambient context with an explicit per-call context (explicit keys
  * win, e.g. a request `url`). Returns undefined when there is nothing to attach.
+ * The logger sub-object never reaches the bus payload.
  */
 function mergeTelemetryContext(explicit) {
-    const ambient = store.getStore();
+    const ambient = withoutLoggerKeys(getContext());
     if (!ambient && !explicit) return undefined;
     return { ...(ambient || {}), ...(explicit || {}) };
 }

package/telemetry/telemetry-runtime.js

@@ -7,6 +7,7 @@
 
 const { createTelemetry } = require('./telemetry-service');
 const { NoOpTelemetry } = require('./no-op-telemetry');
+const loggerRuntime = require('../logs/logger-runtime');
 
 const UNSET = Symbol('unset');
 
@@ -21,12 +22,27 @@ function loadTelemetryConfig() {
     return loadAppDefinition();
 }
 
+function activeSpanContext() {
+    const telemetry = state.telemetry;
+    return telemetry && typeof telemetry.getActiveSpanContext === 'function'
+        ? telemetry.getActiveSpanContext()
+        : null;
+}
+
+// resetLoggerForTests clears the provider, so check on every call.
+function ensureSpanContextProvider() {
+    if (loggerRuntime.getSpanContextProvider() !== activeSpanContext) {
+        loggerRuntime.setSpanContextProvider(activeSpanContext);
+    }
+}
+
 /**
  * The process telemetry service. Created lazily on first use and reused for the
  * life of the Lambda container, so the OTel SDK initialises at most once per cold
  * start. Never throws — any failure falls back to the no-op.
  */
 function getTelemetry() {
+    ensureSpanContextProvider();
     if (state.telemetry) return state.telemetry;
     try {
         const { telemetry = {} } = loadTelemetryConfig();
@@ -136,6 +152,7 @@ function resetTelemetryRuntimeForTests() {
 function setTelemetryForTests(telemetry) {
     state = newState();
     state.telemetry = telemetry;
+    ensureSpanContextProvider();
 }
 
 module.exports = {

package/telemetry/telemetry-service.js

@@ -8,6 +8,7 @@ const { createTelemetryEventBus } = require('./telemetry-event-bus');
  *   count(name, value?, attributes?, context?) · event(name, attributes?, context?)
  *   span(name, fn) · startSpan(name?) · withContext(context, fn)
  *   on(eventType, cb) · forceFlush() · shutdown() · isEnabled()
+ *   getActiveSpanContext() → { traceId, spanId, traceFlags } | null
  */
 
 /**

package/types/errors/index.d.ts

@@ -6,11 +6,30 @@ declare module "@friggframework/errors" {
   export class FetchError extends BaseError {
     constructor(options?: FetchErrorConstructor);
 
+    statusCode?: number;
+    method: string;
+    /** Request URL without userinfo; each query value is `REDACTED`. */
+    url: string;
+    /** Non-enumerable. The raw response, or `null`. */
+    readonly response: FetchErrorResponse | null;
+    /** Non-enumerable. The raw response body; never part of `message`. */
+    readonly body: any;
+    isTimeout?: boolean;
+    timeoutMs?: number;
+
     static create(options?: CreateFetchErrorParams): Promise<FetchError>;
   }
 
+  type FetchErrorResponse = {
+    headers?: object;
+    status?: number;
+    statusText?: string;
+    bodyUsed?: boolean;
+    text?: () => Promise<string>;
+  };
+
   type FetchErrorConstructor = {
-    resource?: string;
+    resource?: string | URL | { url: string };
     init?: Partial<{
       method: string;
       credentials: string;
@@ -19,18 +38,13 @@ declare module "@friggframework/errors" {
       body: URLSearchParams | any;
       returnFullRes: false;
     }>;
-    response?: {
-      headers?: object;
-      status?: number;
-      statusText?: string;
-      text?: () => Promise<string>;
-    };
+    response?: FetchErrorResponse | null;
+    cause?: unknown;
     responseBody?: any;
+    body?: any;
   };
 
-  type CreateFetchErrorParams = Omit<FetchErrorConstructor, "responseBody"> & {
-    body: any;
-  };
+  type CreateFetchErrorParams = FetchErrorConstructor;
 
   export class HaltError extends BaseError {
     isHaltError: boolean;

package/types/logs/index.d.ts

@@ -1,5 +1,64 @@
-declare module "@friggframework/logs/logger" {
+declare module "@friggframework/core/logs" {
+  export type LogLevel = "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+
+  export type LogFields = Record<string, unknown>;
+
+  export interface LogRecord {
+    readonly timestamp: string;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly logger: string;
+    readonly [key: string]: unknown;
+  }
+
+  export interface Logger {
+    readonly name: string;
+    trace(message: unknown, fields?: LogFields): void;
+    debug(message: unknown, fields?: LogFields): void;
+    info(message: unknown, fields?: LogFields): void;
+    warn(message: unknown, fields?: LogFields): void;
+    error(message: unknown, fields?: LogFields): void;
+    fatal(message: unknown, fields?: LogFields): void;
+    child(bindings: LogFields | (() => LogFields)): Logger;
+    isLevelEnabled(level: string): boolean;
+  }
+
+  export interface LogSink {
+    name: string;
+    write(record: LogRecord): void;
+    flush?(options: { signal?: AbortSignal }): Promise<void> | void;
+  }
+
+  export interface MemorySink extends LogSink {
+    readonly records: LogRecord[];
+    clear(): void;
+  }
+
+  export interface SerializedError {
+    type: string;
+    message: string;
+    code?: string | number;
+    status?: number;
+    stack?: string;
+    cause?: SerializedError | string;
+  }
+
+  export function getLogger(name?: string): Logger;
+  export function createMemorySink(options?: { install?: boolean }): MemorySink;
+  export function resetLoggerForTests(options?: {
+    level?: LogLevel | Lowercase<LogLevel>;
+    sinks?: LogSink[];
+    /** Record frigg.* WARN+ records without eventName. Kept across resets that omit it. */
+    trackViolations?: boolean;
+  }): void;
+  export function serializeError(error: unknown): SerializedError;
+  export function redactValue(value: unknown): unknown;
+  export function toSanitizedSurrogate(error: unknown): Error;
+
+  /** @deprecated Use getLogger or this.logger. */
   export function debug(...messages: any[]): void;
+  /** @deprecated Use getLogger or this.logger. */
   export function initDebugLog(...initMessages: any[]): void;
-  export function flushDebugLog(error: any): void;
+  /** @deprecated Use getLogger or this.logger. */
+  export function flushDebugLog(error?: any): void;
 }

package/user/repositories/user-repository-documentdb.js

@@ -17,6 +17,9 @@ const { ClientSafeError } = require('../../errors');
 const {
     DocumentDBEncryptionService,
 } = require('../../database/documentdb-encryption-service');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.user');
 
 /**
  * User repository for DocumentDB.
@@ -145,19 +148,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         // Defensive check: verify document was found after insert
         if (!created) {
-            console.error(
-                '[UserRepositoryDocumentDB] User not found after insert',
-                {
-                    insertedId: fromObjectId(insertedId),
-                    params: {
-                        username: params.username,
-                        appUserId: params.appUserId,
-                        email: params.email,
-                    },
-                }
-            );
             throw new Error(
-                'Failed to create individual user: Document not found after insert. ' +
+                `Failed to create individual user: Document not found after insert (insertedId ${fromObjectId(insertedId)}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -195,18 +187,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         // Defensive check: verify document was found after insert
         if (!created) {
-            console.error(
-                '[UserRepositoryDocumentDB] Organization user not found after insert',
-                {
-                    insertedId: fromObjectId(insertedId),
-                    params: {
-                        appOrgId: params.appOrgId,
-                        name: params.name,
-                    },
-                }
-            );
             throw new Error(
-                'Failed to create organization user: Document not found after insert. ' +
+                `Failed to create organization user: Document not found after insert (insertedId ${fromObjectId(insertedId)}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -291,15 +273,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         // Defensive check: verify document was found after update
         if (!updated) {
-            console.error(
-                '[UserRepositoryDocumentDB] Individual user not found after update',
-                {
-                    userId: fromObjectId(objectId),
-                    updates,
-                }
-            );
             throw new Error(
-                'Failed to update individual user: Document not found after update. ' +
+                `Failed to update individual user: Document not found after update (userId ${userId}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -332,15 +307,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
         const updated = await findOne(this.prisma, 'User', { _id: objectId });
 
         if (!updated) {
-            console.error(
-                '[UserRepositoryDocumentDB] Organization user not found after update',
-                {
-                    userId: fromObjectId(objectId),
-                    updates,
-                }
-            );
             throw new Error(
-                'Failed to update organization user: Document not found after update. ' +
+                `Failed to update organization user: Document not found after update (userId ${userId}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -363,9 +331,9 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
     _mapUser(doc) {
         if (!doc) {
-            console.warn(
-                '[UserRepositoryDocumentDB] _mapUser received null/undefined document'
-            );
+            log.warn('_mapUser received a null document', {
+                eventName: 'frigg.user.map_user_null',
+            });
             return null;
         }