@friggframework/core 2.0.0--canary.652.b14f3b5.0 → 2.0.0--canary.654.be44e66.0

package/CLAUDE.md

@@ -437,22 +437,24 @@ if (!userId) {
 
 ### 9. Logging System (`/logs`)
 
-**Purpose**: Structured logging with debug capabilities.
+**Purpose**: One redacted JSON record per line to stdout (ADR-048). See `docs/guides/LOGGING.md`.
 
-**Functions**:
-- `debug(message, data)` - Debug logging
-- `initDebugLog(eventName, event)` - Initialize debug context
-- `flushDebugLog(error)` - Flush logs on error
+**Rules**:
+- `logs/` is a leaf: it requires only Node built-ins and sibling `logs/` files.
+- Integrations and API modules use `this.logger`; core uses one `getLogger('frigg.<area>')` per module.
+- Fixed message text; ids and counts go into fields. `frigg.*` records at WARN and above need an `eventName` (`<logger name>.<action>`); tests fail without it.
+- Log an error one time, at the boundary (`createHandler`, the express middleware, `Worker.run`, the DLQ processor). Inner code throws with `cause`.
+- Use `statusCode`, not `status` (reserved key). `body`, `payload`, `response` are dropped at INFO and above.
+- Tests assert on `createMemorySink()` records by `eventName`, not on console spies.
+- `debug`, `initDebugLog`, `flushDebugLog` are deprecated shims.
 
 **Usage**:
 
 ```javascript
-const { debug, initDebugLog, flushDebugLog } = require('@friggframework/core');
+const { getLogger } = require('../logs');
+const log = getLogger('frigg.core.sync');
 
-initDebugLog('MyIntegration', event);
-debug('Processing request', { userId, action });
-// ... your code ...
-flushDebugLog(); // On error
+log.warn('Sync skipped', { eventName: 'frigg.core.sync.skipped', processId });
 ```
 
 ### 10. Lambda Utilities (`/lambda`)
@@ -660,8 +662,7 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 ### Optional
 
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
-- `DEBUG` - Debug logging pattern
-- `LOG_LEVEL` - Logging level (debug, info, warn, error)
+- `FRIGG_LOG_LEVEL` - Minimum log level (`TRACE` … `FATAL`, default `INFO`; `DEBUG` on local runs)
 
 ## Version Information
 

package/README.md

@@ -107,10 +107,6 @@ FRIGG_ENCRYPTION_KEY=your-256-bit-encryption-key
 AWS_REGION=us-east-1
 AWS_ACCESS_KEY_ID=your-access-key
 AWS_SECRET_ACCESS_KEY=your-secret-key
-
-# Logging
-DEBUG=frigg:*
-LOG_LEVEL=info
 ```
 
 ## Core Components
@@ -255,10 +251,12 @@ const {
 // Custom business logic error
 throw new RequiredPropertyError('userId is required');
 
-// API communication error
-throw new FetchError('Failed to fetch data from external API', {
-    statusCode: 404,
-    response: errorResponse
+// API communication error. The message is built from the method, the
+// sanitized URL and the status; the response body stays off the message.
+throw await FetchError.create({
+    resource: 'https://api.example.com/contacts',
+    init: { method: 'GET' },
+    response,
 });
 
 // Base error with custom properties
@@ -270,25 +268,25 @@ throw new BaseError('Integration failed', {
 
 ### 6. Logging (`/logs`)
 
-Structured logging with debug capabilities.
+One redacted JSON record per line to stdout, with the correlation ids of
+ADR-011. See the [Logging guide](../../docs/guides/LOGGING.md).
 
 **Usage:**
 ```javascript
-const { debug, initDebugLog, flushDebugLog } = require('@friggframework/core');
-
-// Initialize debug logging
-initDebugLog('integration:slack');
-
-// Log debug information
-debug('Processing webhook payload', { 
-    eventType: 'contact.created',
-    payload: webhookData 
+// In an integration or an API module
+this.logger.info('Contact batch started', {
+    eventName: 'integration.hubspot.batch_started',
+    batchSize: contacts.length,
 });
 
-// Flush logs (useful in serverless environments)
-await flushDebugLog();
+// In core code
+const { getLogger } = require('@friggframework/core');
+const log = getLogger('frigg.core.sync');
+log.warn('Sync skipped', { eventName: 'frigg.core.sync.skipped', processId });
 ```
 
+`debug`, `initDebugLog` and `flushDebugLog` are deprecated shims.
+
 ### 7. User Management (`/user`)
 
 Comprehensive user authentication and authorization system supporting both individual and organizational users.
@@ -1013,8 +1011,7 @@ const {
 | `MONGO_URI` | Yes | MongoDB connection string |
 | `FRIGG_ENCRYPTION_KEY` | Yes | 256-bit encryption key |
 | `AWS_REGION` | No | AWS region for services |
-| `DEBUG` | No | Debug logging pattern |
-| `LOG_LEVEL` | No | Logging level (debug, info, warn, error) |
+| `FRIGG_LOG_LEVEL` | No | Minimum log level: `TRACE`, `DEBUG`, `INFO` (default), `WARN`, `ERROR`, `FATAL`. Local runs default to `DEBUG` |
 
 ## License
 

package/core/CLAUDE.md

@@ -21,13 +21,13 @@ This file provides guidance to Claude Code when working with the Frigg Framework
 - **Database Connection Management**: Automatic MongoDB connection with pooling
 - **Secrets Management**: AWS Secrets Manager integration via `SECRET_ARN` env var
 - **Error Sanitization**: Prevents internal details from leaking to end users
-- **Debug Logging**: Request/response logging with structured debug info
+- **Invocation Scope**: `runInvocationScope` puts `requestId`, `route` and the redacted event summary on every record, then flushes usage, telemetry and sinks
 - **Connection Optimization**: `context.callbackWaitsForEmptyEventLoop = false` for reuse
 
 **Handler Configuration Options**:
 ```javascript
 const handler = createHandler({
-    eventName: 'MyIntegration',           // For logging/debugging
+    eventName: 'MyIntegration',           // Logged as handlerName
     isUserFacingResponse: true,           // true = sanitize errors, false = pass through
     method: async (event, context) => {}, // Your Lambda function logic
     shouldUseDatabase: true               // false = skip MongoDB connection
@@ -129,7 +129,8 @@ class MyIntegration extends Delegate {
 ### Lambda Handler Lifecycle
 1. **Pre-Execution Setup**:
    ```javascript
-   initDebugLog(eventName, event);           // Debug logging setup
+   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope for the invocation
+   log.info('Handler invoked', { eventName: 'frigg.handler.invoked' });
    await secretsToEnv();                     // Secrets Manager injection
    await parametersToEnv();                  // SSM Parameter Store fetch (only when SSM_PARAMETER_PREFIX + FRIGG_SSM_OFFLOADED_KEYS are set)
    context.callbackWaitsForEmptyEventLoop = false; // Connection pooling
@@ -149,12 +150,20 @@ class MyIntegration extends Delegate {
 
 4. **Error Handling & Cleanup**:
    ```javascript
-   flushDebugLog(error);                    // Debug info flush on error
-   // Sanitized error response for user-facing endpoints
+   // One record at the boundary: WARN frigg.handler.rejected (client-safe),
+   // ERROR frigg.handler.failed, or ERROR frigg.handler.halted (halt, no retry).
+   // Sanitized error response for user-facing endpoints; server-to-server
+   // errors are rethrown as a sanitized surrogate (toSanitizedSurrogate).
+   ```
+
+5. **Flush** (in `runInvocationScope`'s `finally`):
+   ```javascript
+   // Usage rollup first (unbounded), then telemetry + log sinks in parallel
+   // under one deadline: min(flushTimeoutMs, remaining time - 50 ms).
    ```
 
 ### SQS Job Processing Lifecycle
-1. **Batch Processing**: Process all records in `event.Records` sequentially
+1. **Batch Processing**: Process all records in `event.Records` sequentially, each inside `runMessageScope` (adds `messageId`, `receiveCount`, `processId`, `integrationId`, `integrationEvent` to its records)
 2. **Message Parsing**: JSON.parse message body for parameters  
 3. **Validation**: Run custom validation on parsed parameters
 4. **Execution**: Call `_run()` method with validated parameters
@@ -205,7 +214,9 @@ const handler = createHandler({
    - Logs full error details internally
 
 2. **Server-to-Server Errors**: `isUserFacingResponse: false`
-   - Re-throws original error for AWS handling
+   - Logs one ERROR, then rethrows a sanitized surrogate for AWS handling:
+     a fresh `Error` with the sanitized `name`, `message`, `stack`, plus
+     `statusCode` and `code`. `instanceof` checks and custom properties are gone
    - Used for SQS, SNS, and internal API calls
    - Enables proper retry mechanisms
 
@@ -214,12 +225,14 @@ const handler = createHandler({
    - Prevents infinite retries for known issues
    - Used for graceful degradation scenarios
 
-### Debug Logging Strategy
+### Logging Strategy
 ```javascript
-initDebugLog(eventName, event);  // Start logging context
-// ... your code ...
-flushDebugLog(error);           // Flush on error (includes full context)
+const { getLogger } = require('../logs');
+const log = getLogger('frigg.core.sync');
+log.info('Sync started', { eventName: 'frigg.core.sync.started', processId });
+// Throw with cause; the boundary logs the error one time.
 ```
+See `docs/guides/LOGGING.md`.
 
 ## Integration Development Patterns
 
@@ -646,7 +659,7 @@ describe('Health Handler', () => {
 const { createHandler } = require('@friggframework/core/core');
 
 const testHandler = createHandler({
-    isUserFacingResponse: false, // Get full errors in tests
+    isUserFacingResponse: false, // Rethrows a sanitized surrogate (name, message, statusCode, code; not the original instance)
     shouldUseDatabase: false,    // Mock/skip DB in tests
     method: yourTestMethod
 });

package/core/Worker.js

@@ -2,6 +2,7 @@ const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
+const { runMessageScope } = require('./invocation-scope');
 
 const sqs = new SQSClient({ region: process.env.AWS_REGION });
 
@@ -25,45 +26,47 @@ class Worker {
         );
 
         for (const record of records) {
-            // Log record entry with SQS-provided attributes useful for tracing
-            // delivery history (ApproximateReceiveCount for retries, etc.).
-            let parsedEvent;
-            try {
-                parsedEvent = JSON.parse(record.body)?.event;
-            } catch {
-                parsedEvent = undefined;
-            }
-            console.log(`[Worker] record begin`, {
-                messageId: record.messageId,
-                event: parsedEvent,
-                receiveCount: record.attributes?.ApproximateReceiveCount,
-            });
-
-            try {
-                const runParams = JSON.parse(record.body);
-                this._validateParams(runParams);
-                await this._run(runParams, context);
-                console.log(`[Worker] record success`, {
+            await runMessageScope(record, async () => {
+                // Log record entry with SQS-provided attributes useful for tracing
+                // delivery history (ApproximateReceiveCount for retries, etc.).
+                let parsedEvent;
+                try {
+                    parsedEvent = JSON.parse(record.body)?.event;
+                } catch {
+                    parsedEvent = undefined;
+                }
+                console.log(`[Worker] record begin`, {
                     messageId: record.messageId,
-                    event: runParams?.event,
+                    event: parsedEvent,
+                    receiveCount: record.attributes?.ApproximateReceiveCount,
                 });
-            } catch (error) {
-                if (error.isHaltError) {
-                    // HaltError means "discard this message, don't retry".
-                    // Treat as success so SQS deletes it from the queue.
-                    // Logged explicitly — silent discards made prod debugging
-                    // extremely hard; keep this visible.
-                    console.warn(`[Worker] record halted (discarded, no retry)`, {
+
+                try {
+                    const runParams = JSON.parse(record.body);
+                    this._validateParams(runParams);
+                    await this._run(runParams, context);
+                    console.log(`[Worker] record success`, {
                         messageId: record.messageId,
-                        event: parsedEvent,
-                        reason: error.message,
-                        statusCode: error.statusCode,
+                        event: runParams?.event,
                     });
-                    continue;
+                } catch (error) {
+                    if (error.isHaltError) {
+                        // HaltError means "discard this message, don't retry".
+                        // Treat as success so SQS deletes it from the queue.
+                        // Logged explicitly — silent discards made prod debugging
+                        // extremely hard; keep this visible.
+                        console.warn(`[Worker] record halted (discarded, no retry)`, {
+                            messageId: record.messageId,
+                            event: parsedEvent,
+                            reason: error.message,
+                            statusCode: error.statusCode,
+                        });
+                        return;
+                    }
+                    console.error(`[Worker] Failed to process record ${record.messageId}:`, error);
+                    batchItemFailures.push({ itemIdentifier: record.messageId });
                 }
-                console.error(`[Worker] Failed to process record ${record.messageId}:`, error);
-                batchItemFailures.push({ itemIdentifier: record.messageId });
-            }
+            });
         }
 
         if (batchItemFailures.length > 0) {

package/core/create-handler.js

@@ -2,7 +2,15 @@
 // REMOVING FOR NOW UNTIL WE ADD WEBPACK BACK IN
 // require('source-map-support').install();
 
-const { initDebugLog, flushDebugLog } = require('../logs');
+const { getLogger, toSanitizedSurrogate } = require('../logs');
+const {
+    summarizeLambdaEvent,
+    toScopeInvocation,
+} = require('../logs/summarize-event');
+const {
+    runInvocationScope,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+} = require('./invocation-scope');
 const { secretsToEnv } = require('./secrets-to-env');
 const { parametersToEnv } = require('./parameters-to-env');
 const {
@@ -11,123 +19,7 @@ const {
     getPluginTelemetrySubscribers,
 } = require('../telemetry/telemetry-runtime');
 
-// Bounds the tail latency telemetry adds to every warm invocation. Kept low so
-// an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
-// most this, not multiple seconds. Override with OTEL_FLUSH_TIMEOUT_MS.
-const DEFAULT_FLUSH_TIMEOUT_MS =
-    Number(process.env.OTEL_FLUSH_TIMEOUT_MS) || 500;
-
-/**
- * Fold the invocation's buffered usage counters into the durable store, then
- * clear the buffer. On an SQS redelivery (ApproximateReceiveCount > 1) we
- * DISCARD rather than flush — the prior delivery already counted, and the usage
- * accuracy contract is "approximate, skip obvious redeliveries". Fully guarded.
- */
-async function flushUsageRollup(subscriber, eventSummary, shouldUseDatabase) {
-    if (!subscriber) return;
-    try {
-        // Persisting usage requires a DB connection. DB-free handlers (e.g. the
-        // webhook-receipt route) never called connectPrisma, so drop the buffer
-        // instead of issuing a connectionless Prisma write.
-        if (!shouldUseDatabase) {
-            subscriber.discard();
-            return;
-        }
-        // Discard only when EVERY record in the batch is a redelivery. The buffer
-        // is invocation-scoped (not per-message), so discarding on *any*
-        // redelivery would drop the fresh records' counts too (silent
-        // under-count). For a mixed batch we flush: preserving fresh counts and
-        // at worst re-counting the one redelivered record is strictly better than
-        // losing fresh data for an approximate store. (Integration queue workers
-        // are batchSize:1 today, so a batch is all-or-nothing; this keeps it
-        // correct if batchSize is ever raised.)
-        const records = Array.isArray(eventSummary?.records)
-            ? eventSummary.records
-            : [];
-        const allRedelivered =
-            records.length > 0 &&
-            records.every((r) => Number(r.receiveCount) > 1);
-        if (allRedelivered) {
-            subscriber.discard();
-        } else {
-            await subscriber.flush();
-        }
-    } catch (_) {
-        // Usage rollup must never break the handler.
-    }
-}
-
-/**
- * Flush telemetry before the Lambda container freezes. Because
- * `callbackWaitsForEmptyEventLoop=false` (below) stops the event loop the moment
- * the handler returns, OTel's timer-driven batch processors would never fire —
- * so spans/metrics must be flushed synchronously here. Bounded by a timeout so a
- * stalled exporter can never block the response, and fully guarded so a flush
- * failure never breaks the handler.
- */
-async function flushTelemetry(telemetry, timeoutMs) {
-    try {
-        if (
-            !telemetry ||
-            typeof telemetry.isEnabled !== 'function' ||
-            !telemetry.isEnabled()
-        ) {
-            return;
-        }
-        let timer;
-        const deadline = new Promise((resolve) => {
-            timer = setTimeout(resolve, timeoutMs);
-        });
-        try {
-            await Promise.race([
-                Promise.resolve(telemetry.forceFlush()),
-                deadline,
-            ]);
-        } finally {
-            clearTimeout(timer);
-        }
-    } catch (_) {
-        // Telemetry flush must never break the handler.
-    }
-}
-
-// Best-effort extraction of correlation identifiers from a Lambda event.
-// For SQS: pulls messageIds + parsed event/processId/integrationId from each
-// record body. For HTTP: pulls method+path. Never throws.
-const summarizeLambdaEvent = (event) => {
-    if (!event) return {};
-    if (Array.isArray(event.Records)) {
-        return {
-            source: 'sqs',
-            records: event.Records.map((r) => {
-                let parsed = {};
-                try {
-                    const body = JSON.parse(r.body);
-                    parsed = {
-                        event: body?.event,
-                        processId: body?.data?.processId,
-                        integrationId: body?.data?.integrationId,
-                    };
-                } catch {
-                    // ignore unparseable bodies
-                }
-                return {
-                    messageId: r.messageId,
-                    receiveCount: r.attributes?.ApproximateReceiveCount,
-                    ...parsed,
-                };
-            }),
-        };
-    }
-    if (event.httpMethod || event.requestContext?.http) {
-        return {
-            source: 'http',
-            method: event.httpMethod || event.requestContext?.http?.method,
-            path: event.path || event.rawPath,
-        };
-    }
-    return { source: 'other' };
-};
+const log = getLogger('frigg.handler');
 
 const createHandler = (optionByName = {}) => {
     const {
@@ -157,95 +49,103 @@ const createHandler = (optionByName = {}) => {
         // no-op after the first invocation.
         getPluginTelemetrySubscribers();
 
-        try {
-            console.info(`[createHandler] ${eventName}: handler entry`, {
-                eventName,
-                awsRequestId: context?.awsRequestId,
-                ...eventSummary,
-            });
-
-            initDebugLog(eventName, event);
+        const scopeFields = {
+            requestId: context?.awsRequestId,
+            handlerName: eventName,
+            method: eventSummary.method,
+            route: eventSummary.route,
+            routeKey: eventSummary.routeKey,
+            invocation: toScopeInvocation(eventSummary),
+        };
 
-            const requestMethod = event.httpMethod;
-            const requestPath = event.path;
-            if (requestMethod && requestPath) {
-                console.info(`${requestMethod} ${requestPath}`);
-            }
+        return runInvocationScope(
+            scopeFields,
+            async () => {
+                try {
+                    log.info('Handler invoked', {
+                        eventName: 'frigg.handler.invoked',
+                    });
 
-            // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
-            await secretsToEnv();
+                    // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
+                    await secretsToEnv();
 
-            // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
-            await parametersToEnv();
+                    // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
+                    await parametersToEnv();
 
-            // Lazy-required so DB-free handlers never load the Prisma client.
-            if (shouldUseDatabase) {
-                const { connectPrisma } = require('../database/prisma');
-                await connectPrisma();
-            }
+                    // Lazy-required so DB-free handlers never load the Prisma client.
+                    if (shouldUseDatabase) {
+                        const { connectPrisma } = require('../database/prisma');
+                        await connectPrisma();
+                    }
 
-            // Helps reuse the database connection.  Lowers response times.
-            context.callbackWaitsForEmptyEventLoop = false;
-
-            // Run the Lambda
-            return await method(event, context);
-        } catch (error) {
-            flushDebugLog(error);
-
-            // Don't leak implementation details to end users.
-            if (isUserFacingResponse) {
-                // Allow client-safe errors to pass through with their actual message
-                if (error.isClientSafe === true) {
-                    const statusCode = error.statusCode || 400;
-                    return {
-                        statusCode,
-                        body: JSON.stringify({
-                            error: error.message,
-                        }),
-                    };
-                }
+                    // Helps reuse the database connection.  Lowers response times.
+                    context.callbackWaitsForEmptyEventLoop = false;
+
+                    // Run the Lambda
+                    return await method(event, context);
+                } catch (error) {
+                    // Don't leak implementation details to end users.
+                    if (isUserFacingResponse) {
+                        // Allow client-safe errors to pass through with their actual message
+                        if (error.isClientSafe === true) {
+                            const statusCode = error.statusCode || 400;
+                            log.warn('Request rejected', {
+                                eventName: 'frigg.handler.rejected',
+                                statusCode,
+                                error,
+                            });
+                            return {
+                                statusCode,
+                                body: JSON.stringify({
+                                    error: error.message,
+                                }),
+                            };
+                        }
+
+                        log.error('Handler failed', {
+                            eventName: 'frigg.handler.failed',
+                            error,
+                        });
+
+                        // Hide other errors with generic message
+                        return {
+                            statusCode: 500,
+                            body: JSON.stringify({
+                                error: 'An Internal Error Occurred',
+                            }),
+                        };
+                    }
 
-                // Hide other errors with generic message
-                return {
-                    statusCode: 500,
-                    body: JSON.stringify({
-                        error: 'An Internal Error Occurred',
-                    }),
-                };
-            }
+                    // Handle server-to-server responses.
 
-            // Handle server-to-server responses.
-
-            // Halt errors are logged but suceed and won't be retried.
-            // Log explicitly — silent suppression here previously made stuck
-            // messages invisible to observability tooling. Include
-            // eventSummary so operators can correlate across concurrent
-            // invocations (processId / messageIds / HTTP path).
-            if (error.isHaltError === true) {
-                console.warn(
-                    `[createHandler] ${eventName}: halt error suppressed (no retry)`,
-                    {
-                        eventName,
-                        errorName: error.name,
-                        errorMessage: error.message,
-                        statusCode: error.statusCode,
-                        ...eventSummary,
+                    // Halt errors succeed and won't be retried, so the halt
+                    // itself is the failure record.
+                    if (error.isHaltError === true) {
+                        log.error('Handler halted', {
+                            eventName: 'frigg.handler.halted',
+                            error,
+                        });
+                        return;
                     }
-                );
-                return;
-            }
 
-            // Here we can just rethrow and let AWS build the response.
-            throw error;
-        } finally {
-            // Flush telemetry + usage before the container freezes.
-            await flushTelemetry(activeTelemetry, flushTimeoutMs);
-            await flushUsageRollup(
-                activeUsageRollup,
+                    log.error('Handler failed', {
+                        eventName: 'frigg.handler.failed',
+                        error,
+                    });
+                    // The Lambda runtime writes a rethrown error itself, so
+                    // rethrow a sanitized copy (ADR-048 §6 item 11).
+                    throw toSanitizedSurrogate(error);
+                }
+            },
+            {
+                telemetry: activeTelemetry,
+                usageRollup: activeUsageRollup,
                 eventSummary,
-                shouldUseDatabase
-            );
-        }
+                shouldUseDatabase,
+                flushTimeoutMs,
+                context,
+            }
+        );
     };
 };
 

package/core/index.js

@@ -2,5 +2,12 @@ const { Delegate } = require('./Delegate');
 const { Worker } = require('./Worker');
 const { loadInstalledModules } = require('./load-installed-modules');
 const { createHandler } = require('./create-handler');
+const { runInvocationScope } = require('./invocation-scope');
 
-module.exports = { Delegate, Worker, loadInstalledModules, createHandler };
+module.exports = {
+    Delegate,
+    Worker,
+    loadInstalledModules,
+    createHandler,
+    runInvocationScope,
+};