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

package/CLAUDE.md

@@ -414,43 +414,6 @@ const decrypted = await cryptor.decrypt(encrypted);
 - `integration-event-dispatcher.js` - Routes events to integration handlers
 - Supports lifecycle events and user actions
 
-**Queue handler delivery**: a handler dispatched from the integration queue
-(any `this.events` entry reached through SQS, including `ON_WEBHOOK` and
-scheduled jobs) receives `{ data, context, delivery }`. HTTP-dispatched
-handlers (`{ req, res, next }`) and `this.on` events do not.
-
-| Field | Type | Value |
-|---|---|---|
-| `delivery.receiveCount` | `number \| undefined` | SQS `ApproximateReceiveCount` of this delivery |
-| `delivery.maxReceiveCount` | `number \| undefined` | Receives allowed before SQS moves the message to the DLQ (`FRIGG_QUEUE_MAX_RECEIVE_COUNT`) |
-| `delivery.isLastAttempt` | `boolean` | `true` only when both counts are known and `receiveCount >= maxReceiveCount` |
-
-`isLastAttempt` is `false` when either count is unknown: a local or non-SQS
-invocation, or a queue whose redrive policy the stack does not own
-(`ownership.queue: 'external'`). The value is information only: core still
-rethrows retryable errors and discards halt errors (4xx except 408/429).
-
-Use it to end a run or count lost work on the final try: when a retryable
-error (429, 5xx, network) is about to be rethrown and `isLastAttempt` is
-`true`, the message goes to the DLQ next, so mark the run failed or count the
-message's records as failed before rethrowing.
-
-```javascript
-async processBatch({ data, delivery }) {
-    try {
-        await this.syncPage(data);
-    } catch (error) {
-        if (delivery?.isLastAttempt) await this.failRun(data.processId, error);
-        throw error;
-    }
-}
-```
-
-The single source of the max receive count is
-`INTEGRATION_QUEUE_MAX_RECEIVE_COUNT` in `queues/queue-delivery.js`. The
-devtools integration builder uses it for the queue's `RedrivePolicy` and sets
-it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
-
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.
@@ -474,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`)
@@ -697,9 +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_QUEUE_MAX_RECEIVE_COUNT` - Set by devtools on integration queue workers whose queue the stack owns; feeds `delivery.maxReceiveCount`
+- `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
@@ -52,10 +52,9 @@ const handler = createHandler({
 **Usage Pattern**:
 ```javascript
 class MyWorker extends Worker {
-    async _run(params, context = {}, delivery) {
+    async _run(params, context = {}) {
         // Your job processing logic here
         // params are already JSON.parsed from SQS message body
-        // delivery is { receiveCount, maxReceiveCount, isLastAttempt }
     }
     
     _validateParams(params) {
@@ -130,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
@@ -150,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
@@ -206,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
 
@@ -215,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
 
@@ -647,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,7 +2,7 @@ const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
-const { readQueueDelivery } = require('../queues/queue-delivery');
+const { runMessageScope } = require('./invocation-scope');
 
 const sqs = new SQSClient({ region: process.env.AWS_REGION });
 
@@ -26,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, readQueueDelivery(record));
-                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) {