@friggframework/core 2.0.0--canary.654.3cd4278.0 → 2.0.0--canary.651.dadf4d6.0

package/.eslintrc.json

@@ -1,20 +1,3 @@
 {
-    "extends": "@friggframework/eslint-config",
-    "rules": {
-        "no-restricted-syntax": [
-            "warn",
-            {
-                "selector": "CallExpression[callee.object.object.name='process'][callee.object.property.name=/^(stdout|stderr)$/][callee.property.name='write']",
-                "message": "Write through the logger; only logs/sinks.js writes to fd 1 (ADR-048 §14)"
-            }
-        ]
-    },
-    "overrides": [
-        {
-            "files": ["*.test.js", "database/utils/prisma-runner.js"],
-            "rules": {
-                "no-restricted-syntax": "off"
-            }
-        }
-    ]
+    "extends": "@friggframework/eslint-config"
 }

package/CLAUDE.md

@@ -211,7 +211,56 @@ packages/core/
 - `integration-repository-factory.js` - Creates database-specific repositories
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
-- `integration-mapping-repository-*.js` - Mapping data persistence
+- `integration-mapping-repository-*.js` - Mapping data persistence.
+  `queryMappings(integrationId, { where, orderBy, skip, take, omit })`
+  returns `{ mappings, total }`: one filtered, ordered page of an
+  integration's mappings, for callers that cannot load every row through
+  `findMappingsByIntegration`. `where` is an array of ANDed conditions
+  (at most 20); an entry may be `{ anyOf: [...] }`, ORed, one level deep.
+  Conditions are `{ path: 'mapping.<segment>...', op: 'exists' | 'notExists' }`
+  (JSON null counts as absent), `{ path: 'mapping.…', op: 'in', value: string[] }`
+  (1–500 strings) and `{ path: 'sourceId', op: 'notStartsWith', value }`
+  (a NULL sourceId matches). `orderBy` is `{ path: 'mapping.…', direction:
+  'asc' | 'desc' }`, nulls last, ties broken by id in the same direction;
+  without it rows come in id order. `take` is 1–500. `omit` lists top-level
+  mapping keys to leave out of the rows; never write such rows back. Path
+  segments must match `^[A-Za-z_][A-Za-z0-9_]*$`. The PostgreSQL, MongoDB and
+  DocumentDB adapters give the same pages and totals;
+  `integration-mapping-repository-query-parity.test.js` checks that against
+  real databases when `QUERY_MAPPINGS_PARITY_MONGO_URL` /
+  `QUERY_MAPPINGS_PARITY_POSTGRES_URL` are set. Two orderings still differ:
+  strings compare by the database collation on PostgreSQL and by code point
+  on MongoDB and DocumentDB, and arrays or objects at the sort path order
+  among themselves only on PostgreSQL (the other adapters fall back to id).
+  The legacy `IntegrationMappingRepository` inherits the port's
+  "not supported by this database adapter yet" error. Every adapter refuses
+  to run while field-level encryption still encrypts
+  `IntegrationMapping.mapping` on write (see `database/encryption/README.md`),
+  and returns rows decrypted like `findMappingsByIntegration`. PostgreSQL and
+  MongoDB decrypt through `decryptQueriedMappings`
+  (`database/encryption/integration-mapping-encryption.js`), a no-op while
+  encryption is off or lists no `IntegrationMapping` field besides `mapping`.
+  Validation lives in `integration-mapping-query.js`; a new operator is one
+  entry in its `OPERATORS` table, one in the Postgres adapter's
+  `CONDITION_SQL` and one in `CONDITION_EXPRESSIONS` in
+  `integration-mapping-query-pipeline.js`, the aggregation stages both
+  MongoDB-protocol adapters share. Those stages may only use what Amazon
+  DocumentDB 4.0 and 5.0 support (no `$facet`, `$getField`, `$set` or
+  `$unset`).
+  **Cost**: PostgreSQL answers in one SQL statement, which reads every row
+  of the integration and evaluates the JSON paths per row, because no JSON
+  index exists. With ~4 KB mappings on PostgreSQL 16 that is about 0.3 s per
+  call at 10⁴ rows per integration and 2.5–3 s at 10⁵. MongoDB answers in one
+  aggregate: the `integrationId` index narrows `$match` to the integration,
+  the `$expr` is then evaluated per document, and `$facet` returns the page
+  with its `$count`, so a page (after `omit`) must fit the 16 MB document
+  limit. DocumentDB has no `$facet`: the page and the count are two
+  concurrent aggregates, so the total does not come from the same snapshot
+  as the page. Both sort in memory on a computed key (`allowDiskUse`). With
+  ~4 KB mappings on MongoDB 7 that is about 0.05–0.1 s per call at 10⁴ rows
+  per integration and 0.5–0.7 s at 10⁵ (the DocumentDB pipeline, run on
+  MongoDB, 0.6–0.8 s). On every adapter a deep offset or an empty page past
+  the end costs about the same as the first page.
 - `process-repository-*.js` - Process (long-running job) persistence.
   Implements `applyProcessUpdate(processId, ops)` — a race-safe alternative
   to `update(id, patch)` that routes increments, sets, and bounded-array
@@ -437,24 +486,22 @@ if (!userId) {
 
 ### 9. Logging System (`/logs`)
 
-**Purpose**: One redacted JSON record per line to stdout (ADR-048). See `docs/guides/LOGGING.md`.
+**Purpose**: Structured logging with debug capabilities.
 
-**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.
+**Functions**:
+- `debug(message, data)` - Debug logging
+- `initDebugLog(eventName, event)` - Initialize debug context
+- `flushDebugLog(error)` - Flush logs on error
 
 **Usage**:
 
 ```javascript
-const { getLogger } = require('../logs');
-const log = getLogger('frigg.core.sync');
+const { debug, initDebugLog, flushDebugLog } = require('@friggframework/core');
 
-log.warn('Sync skipped', { eventName: 'frigg.core.sync.skipped', processId });
+initDebugLog('MyIntegration', event);
+debug('Processing request', { userId, action });
+// ... your code ...
+flushDebugLog(); // On error
 ```
 
 ### 10. Lambda Utilities (`/lambda`)
@@ -662,7 +709,8 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 ### Optional
 
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
-- `FRIGG_LOG_LEVEL` - Minimum log level (`TRACE` … `FATAL`, default `INFO`; `DEBUG` on local runs)
+- `DEBUG` - Debug logging pattern
+- `LOG_LEVEL` - Logging level (debug, info, warn, error)
 
 ## Version Information
 

package/README.md

@@ -107,6 +107,10 @@ 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
@@ -251,12 +255,10 @@ const {
 // Custom business logic error
 throw new RequiredPropertyError('userId is required');
 
-// 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,
+// API communication error
+throw new FetchError('Failed to fetch data from external API', {
+    statusCode: 404,
+    response: errorResponse
 });
 
 // Base error with custom properties
@@ -268,25 +270,25 @@ throw new BaseError('Integration failed', {
 
 ### 6. Logging (`/logs`)
 
-One redacted JSON record per line to stdout, with the correlation ids of
-ADR-011. See the [Logging guide](../../docs/guides/LOGGING.md).
+Structured logging with debug capabilities.
 
 **Usage:**
 ```javascript
-// In an integration or an API module
-this.logger.info('Contact batch started', {
-    eventName: 'integration.hubspot.batch_started',
-    batchSize: contacts.length,
+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 core code
-const { getLogger } = require('@friggframework/core');
-const log = getLogger('frigg.core.sync');
-log.warn('Sync skipped', { eventName: 'frigg.core.sync.skipped', processId });
+// Flush logs (useful in serverless environments)
+await flushDebugLog();
 ```
 
-`debug`, `initDebugLog` and `flushDebugLog` are deprecated shims.
-
 ### 7. User Management (`/user`)
 
 Comprehensive user authentication and authorization system supporting both individual and organizational users.
@@ -1011,7 +1013,8 @@ const {
 | `MONGO_URI` | Yes | MongoDB connection string |
 | `FRIGG_ENCRYPTION_KEY` | Yes | 256-bit encryption key |
 | `AWS_REGION` | No | AWS region for services |
-| `FRIGG_LOG_LEVEL` | No | Minimum log level: `TRACE`, `DEBUG`, `INFO` (default), `WARN`, `ERROR`, `FATAL`. Local runs default to `DEBUG` |
+| `DEBUG` | No | Debug logging pattern |
+| `LOG_LEVEL` | No | Logging level (debug, info, warn, error) |
 
 ## 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
-- **Invocation Scope**: `runInvocationScope` puts `requestId`, `route` and the redacted event summary on every record, then flushes usage, telemetry and sinks
+- **Debug Logging**: Request/response logging with structured debug info
 - **Connection Optimization**: `context.callbackWaitsForEmptyEventLoop = false` for reuse
 
 **Handler Configuration Options**:
 ```javascript
 const handler = createHandler({
-    eventName: 'MyIntegration',           // Logged as handlerName
+    eventName: 'MyIntegration',           // For logging/debugging
     isUserFacingResponse: true,           // true = sanitize errors, false = pass through
     method: async (event, context) => {}, // Your Lambda function logic
     shouldUseDatabase: true               // false = skip MongoDB connection
@@ -129,8 +129,7 @@ class MyIntegration extends Delegate {
 ### Lambda Handler Lifecycle
 1. **Pre-Execution Setup**:
    ```javascript
-   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope for the invocation
-   log.info('Handler invoked', { eventName: 'frigg.handler.invoked' });
+   initDebugLog(eventName, event);           // Debug logging setup
    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,20 +149,12 @@ class MyIntegration extends Delegate {
 
 4. **Error Handling & Cleanup**:
    ```javascript
-   // 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).
+   flushDebugLog(error);                    // Debug info flush on error
+   // Sanitized error response for user-facing endpoints
    ```
 
 ### SQS Job Processing Lifecycle
-1. **Batch Processing**: Process all records in `event.Records` sequentially, each inside `runMessageScope` (adds `messageId`, `receiveCount`, `processId`, `integrationId`, `integrationEvent` to its records)
+1. **Batch Processing**: Process all records in `event.Records` sequentially
 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
@@ -214,9 +205,7 @@ const handler = createHandler({
    - Logs full error details internally
 
 2. **Server-to-Server Errors**: `isUserFacingResponse: false`
-   - 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
+   - Re-throws original error for AWS handling
    - Used for SQS, SNS, and internal API calls
    - Enables proper retry mechanisms
 
@@ -225,14 +214,12 @@ const handler = createHandler({
    - Prevents infinite retries for known issues
    - Used for graceful degradation scenarios
 
-### Logging Strategy
+### Debug Logging Strategy
 ```javascript
-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.
+initDebugLog(eventName, event);  // Start logging context
+// ... your code ...
+flushDebugLog(error);           // Flush on error (includes full context)
 ```
-See `docs/guides/LOGGING.md`.
 
 ## Integration Development Patterns
 
@@ -659,7 +646,7 @@ describe('Health Handler', () => {
 const { createHandler } = require('@friggframework/core/core');
 
 const testHandler = createHandler({
-    isUserFacingResponse: false, // Rethrows a sanitized surrogate (name, message, statusCode, code; not the original instance)
+    isUserFacingResponse: false, // Get full errors in tests
     shouldUseDatabase: false,    // Mock/skip DB in tests
     method: yourTestMethod
 });

package/core/Worker.js

@@ -2,11 +2,8 @@ const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
-const { runMessageScope } = require('./invocation-scope');
-const { getLogger } = require('../logs');
 
 const sqs = new SQSClient({ region: process.env.AWS_REGION });
-const log = getLogger('frigg.worker');
 
 class Worker {
     async getQueueURL(params) {
@@ -28,36 +25,45 @@ class Worker {
         );
 
         for (const record of records) {
-            await runMessageScope(record, async () => {
-                // messageId, receiveCount and the event come from the scope.
-                log.debug('Record started', { eventName: 'frigg.worker.record_started' });
-
-                try {
-                    const runParams = JSON.parse(record.body);
-                    this._validateParams(runParams);
-                    await this._run(runParams, context);
-                    log.debug('Record succeeded', { eventName: 'frigg.worker.record_succeeded' });
-                } 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.
-                        log.error('Record halted (discarded, no retry)', {
-                            eventName: 'frigg.worker.record_halted',
-                            statusCode: error.statusCode,
-                            error,
-                        });
-                        return;
-                    }
-                    // The message goes back to SQS, so WARN (ADR-048 §4).
-                    log.warn('Record failed, returned for retry', {
-                        eventName: 'frigg.worker.record_failed',
-                        error,
+            // 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`, {
+                    messageId: record.messageId,
+                    event: runParams?.event,
+                });
+            } 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,
                     });
-                    batchItemFailures.push({ itemIdentifier: record.messageId });
+                    continue;
                 }
-            });
+                console.error(`[Worker] Failed to process record ${record.messageId}:`, error);
+                batchItemFailures.push({ itemIdentifier: record.messageId });
+            }
         }
 
         if (batchItemFailures.length > 0) {