@friggframework/core 2.0.0--canary.654.70623e2.0 → 2.0.0--canary.654.6d3a665.0

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
@@ -414,6 +463,43 @@ 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.
@@ -663,6 +749,7 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
 - `FRIGG_LOG_LEVEL` - Minimum log level (`TRACE` … `FATAL`, default `INFO`; `DEBUG` on local runs)
+- `FRIGG_QUEUE_MAX_RECEIVE_COUNT` - Set by devtools on integration queue workers whose queue the stack owns; feeds `delivery.maxReceiveCount`
 
 ## Version Information
 

package/core/CLAUDE.md

@@ -52,9 +52,10 @@ const handler = createHandler({
 **Usage Pattern**:
 ```javascript
 class MyWorker extends Worker {
-    async _run(params, context = {}) {
+    async _run(params, context = {}, delivery) {
         // Your job processing logic here
         // params are already JSON.parsed from SQS message body
+        // delivery is { receiveCount, maxReceiveCount, isLastAttempt }
     }
     
     _validateParams(params) {

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 { readQueueDelivery } = require('../queues/queue-delivery');
 const { runMessageScope } = require('./invocation-scope');
 const { getLogger } = require('../logs');
 
@@ -35,7 +36,7 @@ class Worker {
                 try {
                     const runParams = JSON.parse(record.body);
                     this._validateParams(runParams);
-                    await this._run(runParams, context);
+                    await this._run(runParams, context, readQueueDelivery(record));
                     log.debug('Record succeeded', { eventName: 'frigg.worker.record_succeeded' });
                 } catch (error) {
                     if (error.isHaltError) {

package/database/documentdb-encryption-service.js

@@ -1,5 +1,9 @@
 const { Cryptor } = require('../encrypt/Cryptor');
-const { getEncryptedFields, loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
+const {
+    getEncryptedFields,
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('./encryption/encryption-schema-registry');
 
 /**
  * Encryption service specifically for DocumentDB repositories
@@ -107,7 +111,7 @@ class DocumentDBEncryptionService {
         }
 
         // Get encrypted fields from registry
-        const encryptedFieldsConfig = getEncryptedFields(modelName);
+        const encryptedFieldsConfig = getFieldsToEncryptOnWrite(modelName);
         if (!encryptedFieldsConfig || encryptedFieldsConfig.length === 0) {
             return document;
         }

package/database/documentdb-utils.js

@@ -166,11 +166,12 @@ async function findManyDrained(client, collection, filter = {}, options = {}) {
     return drainCursor(client, collection, first);
 }
 
-async function aggregateDrained(client, collection, pipeline) {
+async function aggregateDrained(client, collection, pipeline, options = {}) {
     const first = await client.$runCommandRaw({
         aggregate: collection,
         pipeline,
         cursor: { batchSize: DRAIN_BATCH_SIZE },
+        ...options,
     });
     return drainCursor(client, collection, first);
 }

package/database/encryption/README.md

@@ -818,6 +818,26 @@ export AES_KEY=$(openssl rand -hex 16)  # Generate 32-char key
 ❌ Query on encrypted fields (not supported)
 ❌ Manually decrypt data (use extension)
 
+The integration mapping repositories' `queryMappings()` (PostgreSQL, MongoDB
+and DocumentDB) filters and sorts inside the `mapping` JSON, so it refuses to
+run while field-level encryption still encrypts `IntegrationMapping.mapping` on
+write. Opt the field out in the app definition, together with any nested
+`mapping.*` path that `encryption.schema` encrypts; the Prisma extension and
+`DocumentDBEncryptionService` both honor the opt-out:
+
+```javascript
+encryption: {
+    disable: { IntegrationMapping: ['mapping'] },
+}
+```
+
+The opt-out applies to writes only. Rows written encrypted before it stay
+readable, but `queryMappings()` does not match them until they are written
+again. It returns the rows it matches decrypted, like
+`findMappingsByIntegration()`: a nested `mapping.*` path written encrypted
+before its opt-out reads plain, though conditions and ordering on that path
+still see the ciphertext until the row is written again.
+
 ## Future Enhancements
 
 ### Planned

package/database/encryption/integration-mapping-encryption.js

@@ -0,0 +1,97 @@
+const { getEncryptionConfig } = require('../prisma');
+const { Cryptor } = require('../../encrypt/Cryptor');
+const {
+    getFieldsToDecryptOnRead,
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('./encryption-schema-registry');
+const {
+    createFieldEncryptionService,
+} = require('./prisma-encryption-extension');
+
+let plainMappingEncryption = null;
+
+/**
+ * The `IntegrationMapping` fields, `mapping` itself or a nested `mapping.*`
+ * path, that field-level encryption encrypts on write. An empty result is
+ * kept for the life of the process.
+ *
+ * @returns {string[]} Empty when every mapping path is written as plain JSON
+ */
+function getMappingFieldsEncryptedOnWrite() {
+    return mappingEncryption().encryptedOnWrite;
+}
+
+/**
+ * @throws {Error} When field-level encryption still encrypts `mapping`, or a
+ *   nested `mapping.*` path, on write, naming the opt-out that lifts it
+ */
+function assertMappingWrittenUnencrypted() {
+    const fields = getMappingFieldsEncryptedOnWrite();
+    if (fields.length === 0) return;
+
+    const encrypted = fields
+        .map((field) => `IntegrationMapping.${field}`)
+        .join(', ');
+    const optOut = fields.map((field) => `'${field}'`).join(', ');
+    throw new Error(
+        `queryMappings: field-level encryption still encrypts ${encrypted} on write, so it cannot be queried. Opt out by adding ${optOut} to appDefinition.encryption.disable.IntegrationMapping.`
+    );
+}
+
+/**
+ * Decrypts rows that `queryMappings` read around the Prisma encryption
+ * extension, the way reads through the extension do: every
+ * `IntegrationMapping` field the schema lists, opted-out paths included, so a
+ * path written encrypted before its opt-out comes back plain.
+ *
+ * @param {Object[]} rows - Rows whose `mapping` is a JSON object
+ * @returns {Promise<Object[]>} `rows` itself when encryption is off or the
+ *   schema lists no field besides `mapping`
+ */
+async function decryptQueriedMappings(rows) {
+    const { decryptor } = mappingEncryption();
+    if (!decryptor) return rows;
+    return decryptor.decryptFieldsInBulk('IntegrationMapping', rows);
+}
+
+function mappingEncryption() {
+    if (plainMappingEncryption) return plainMappingEncryption;
+
+    const encryption = currentMappingEncryption();
+    if (encryption.encryptedOnWrite.length === 0) {
+        plainMappingEncryption = encryption;
+    }
+    return encryption;
+}
+
+function currentMappingEncryption() {
+    const config = getEncryptionConfig();
+    if (!config.enabled) return { encryptedOnWrite: [], decryptor: null };
+
+    loadCustomEncryptionSchema();
+    const encryptedOnWrite = getFieldsToEncryptOnWrite(
+        'IntegrationMapping'
+    ).filter((field) => field === 'mapping' || field.startsWith('mapping.'));
+    const decryptsBesidesMapping = getFieldsToDecryptOnRead(
+        'IntegrationMapping'
+    ).some((field) => field !== 'mapping');
+    const decryptor = decryptsBesidesMapping
+        ? createFieldEncryptionService(
+              new Cryptor({ shouldUseAws: config.method === 'kms' })
+          )
+        : null;
+    return { encryptedOnWrite, decryptor };
+}
+
+/** Test helper: forget a kept result. */
+function resetMappingEncryptionCheck() {
+    plainMappingEncryption = null;
+}
+
+module.exports = {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+    getMappingFieldsEncryptedOnWrite,
+    resetMappingEncryptionCheck,
+};

package/database/encryption/prisma-encryption-extension.js

@@ -10,6 +10,24 @@ const {
 } = require('./encryption-schema-registry');
 const { FieldEncryptionService } = require('./field-encryption-service');
 
+/**
+ * The FieldEncryptionService the extension runs, with field paths from the
+ * encryption schema registry.
+ *
+ * @param {import('../../encrypt/Cryptor').Cryptor} cryptor
+ * @returns {FieldEncryptionService}
+ */
+function createFieldEncryptionService(cryptor) {
+    return new FieldEncryptionService({
+        cryptor,
+        schema: {
+            getEncryptedFields,
+            getFieldsToEncryptOnWrite,
+            getFieldsToDecryptOnRead,
+        },
+    });
+}
+
 function createEncryptionExtension({ cryptor, enabled = true }) {
     if (!enabled) {
         return (client) => client;
@@ -21,14 +39,7 @@ function createEncryptionExtension({ cryptor, enabled = true }) {
         );
     }
 
-    const encryptionService = new FieldEncryptionService({
-        cryptor,
-        schema: {
-            getEncryptedFields,
-            getFieldsToEncryptOnWrite,
-            getFieldsToDecryptOnRead,
-        },
-    });
+    const encryptionService = createFieldEncryptionService(cryptor);
 
     return {
         name: 'frigg-field-encryption',
@@ -227,4 +238,4 @@ function createEncryptionExtension({ cryptor, enabled = true }) {
     };
 }
 
-module.exports = { createEncryptionExtension };
+module.exports = { createEncryptionExtension, createFieldEncryptionService };

package/handlers/backend-utils.js

@@ -165,7 +165,7 @@ const createQueueWorker = (integrationClass) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
-        async _run(params, context) {
+        async _run(params, context, delivery) {
             const logCtx = {
                 integration: integrationName,
                 event: params.event,
@@ -255,6 +255,7 @@ const createQueueWorker = (integrationClass) => {
                     event: params.event,
                     data: params.data,
                     context: context,
+                    delivery,
                 });
                 console.log(
                     `[QueueWorker] ${params.event} dispatched ok`,

package/handlers/integration-event-dispatcher.js

@@ -18,9 +18,9 @@ class IntegrationEventDispatcher {
         );
     }
 
-    async dispatchJob({ event, data, context }) {
+    async dispatchJob({ event, data, context, delivery }) {
         return this._dispatch(event, (instance, handler) =>
-            handler.call(instance, { data, context })
+            handler.call(instance, { data, context, delivery })
         );
     }
 

package/integrations/repositories/integration-mapping-query-pipeline.js

@@ -0,0 +1,152 @@
+const SORT_KEY = '__sortKey';
+const MONGO_DIRECTIONS = { asc: 1, desc: -1 };
+const SORT_TYPE_RANKS = [
+    ['string'],
+    ['int', 'long', 'double', 'decimal'],
+    ['bool'],
+    ['array'],
+    ['object'],
+];
+const SCALAR_TYPES = SORT_TYPE_RANKS.slice(0, 3).flat();
+
+const isType = (expression, type) => ({ $eq: [{ $type: expression }, type] });
+const isAbsent = (expression) => ({
+    $eq: [{ $ifNull: [expression, null] }, null],
+});
+const mappingField = (segments) => `$mapping.${segments.join('.')}`;
+
+const CONDITION_EXPRESSIONS = {
+    exists: (operand) => ({ $ne: [{ $ifNull: [operand, null] }, null] }),
+    notExists: (operand) => isAbsent(operand),
+    in: (operand, values) => ({
+        $and: [
+            isType(operand, 'string'),
+            { $in: [operand, { $literal: values }] },
+        ],
+    }),
+    notStartsWith: (operand, prefix) => ({
+        $cond: [
+            isType(operand, 'string'),
+            {
+                $ne: [
+                    { $substrCP: [operand, 0, [...prefix].length] },
+                    { $literal: prefix },
+                ],
+            },
+            true,
+        ],
+    }),
+};
+
+/**
+ * Aggregation stages that answer a validated queryMappings query on the
+ * MongoDB wire protocol.
+ *
+ * @param {*} integrationId - The value IntegrationMapping.integrationId is stored as
+ * @param {ReturnType<import('./integration-mapping-query').validateMappingQuery>} query
+ * @returns {{match: Object, page: Object[], sort: Object}} `match` selects
+ *   the matching documents; `page` sorts, skips and limits them; `sort` is
+ *   the $sort stage inside `page`
+ */
+function buildMappingQueryStages(
+    integrationId,
+    { where, orderBy, skip, take, omit }
+) {
+    const match = {
+        $match: {
+            integrationId,
+            $expr: {
+                $and: [
+                    isType('$mapping', 'object'),
+                    ...where.map(entryExpression),
+                ],
+            },
+        },
+    };
+    const sort = { $sort: sortSpec(orderBy) };
+    const page = [
+        ...(orderBy
+            ? [{ $addFields: { [SORT_KEY]: sortKey(orderBy.path) } }]
+            : []),
+        ...(omit.length > 0 ? [{ $project: omitProjection(omit) }] : []),
+        sort,
+        ...(skip > 0 ? [{ $skip: skip }] : []),
+        { $limit: take },
+    ];
+    return { match, page, sort };
+}
+
+function entryExpression(entry) {
+    if (!entry.anyOf) return conditionExpression(entry);
+    return { $or: entry.anyOf.map(conditionExpression) };
+}
+
+function conditionExpression({ field, path, op, value }) {
+    const operand = field === 'sourceId' ? '$sourceId' : resolvePath(path);
+    return CONDITION_EXPRESSIONS[op](operand, value);
+}
+
+/**
+ * The value at a mapping path; null when an enclosing value is not an object.
+ */
+function resolvePath(segments) {
+    const enclosing = segments
+        .slice(0, -1)
+        .map((_, i) =>
+            isType(mappingField(segments.slice(0, i + 1)), 'object')
+        );
+    if (enclosing.length === 0) return mappingField(segments);
+    return {
+        $cond: [
+            enclosing.length === 1 ? enclosing[0] : { $and: enclosing },
+            mappingField(segments),
+            null,
+        ],
+    };
+}
+
+/**
+ * Orders values like jsonb: strings < numbers < booleans < arrays < objects,
+ * scalars by value within their type. Null and absent values sort last in
+ * both directions.
+ */
+function sortKey(path) {
+    const type = { $type: '$$value' };
+    return {
+        $let: {
+            vars: { value: resolvePath(path) },
+            in: {
+                missing: isAbsent('$$value'),
+                rank: {
+                    $switch: {
+                        branches: SORT_TYPE_RANKS.map((types, i) => ({
+                            case: { $in: [type, types] },
+                            then: i + 1,
+                        })),
+                        default: 0,
+                    },
+                },
+                value: {
+                    $cond: [{ $in: [type, SCALAR_TYPES] }, '$$value', null],
+                },
+            },
+        },
+    };
+}
+
+function sortSpec(orderBy) {
+    if (!orderBy) return { _id: 1 };
+    const direction = MONGO_DIRECTIONS[orderBy.direction];
+    return {
+        [`${SORT_KEY}.missing`]: 1,
+        [`${SORT_KEY}.rank`]: direction,
+        [`${SORT_KEY}.value`]: direction,
+        _id: direction,
+    };
+}
+
+function omitProjection(omit) {
+    return Object.fromEntries(omit.map((key) => [`mapping.${key}`, 0]));
+}
+
+module.exports = { buildMappingQueryStages };

package/integrations/repositories/integration-mapping-query.js

@@ -0,0 +1,193 @@
+const SEGMENT_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_TAKE = 500;
+const MAX_IN_VALUES = 500;
+const MAX_CONDITIONS = 20;
+const DIRECTIONS = ['asc', 'desc'];
+
+const OPERATORS = {
+    exists: { fields: ['mapping'] },
+    notExists: { fields: ['mapping'] },
+    in: { fields: ['mapping'], value: toStringList },
+    notStartsWith: { fields: ['sourceId'], value: toPrefix },
+};
+
+/**
+ * Checks a queryMappings query and normalizes it for an adapter.
+ *
+ * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+ * @returns {{where: Array<Object>, orderBy: ({path: string[], direction: 'asc'|'desc'}|null), skip: number, take: number, omit: string[]}}
+ * @throws {Error} When the query does not fit that shape
+ */
+function validateMappingQuery(query) {
+    if (!isPlainObject(query)) {
+        throw new Error('queryMappings: query must be an object');
+    }
+    const { where = [], orderBy, skip = 0, take, omit = [] } = query;
+    if (!Array.isArray(where)) {
+        throw new Error('queryMappings: where must be an array');
+    }
+    if (!Number.isInteger(take) || take < 1 || take > MAX_TAKE) {
+        throw new Error(
+            `queryMappings: take must be an integer between 1 and ${MAX_TAKE}`
+        );
+    }
+    if (!Number.isSafeInteger(skip) || skip < 0) {
+        throw new Error('queryMappings: skip must be a non-negative integer');
+    }
+    if (
+        !Array.isArray(omit) ||
+        !omit.every((key) => typeof key === 'string' && SEGMENT_REGEX.test(key))
+    ) {
+        throw new Error(
+            `queryMappings: omit must be an array of top-level mapping keys matching ${SEGMENT_REGEX}`
+        );
+    }
+
+    const whereEntries = where.map(toWhereEntry);
+    const conditionCount = whereEntries.reduce(
+        (count, entry) => count + (entry.anyOf ? entry.anyOf.length : 1),
+        0
+    );
+    if (conditionCount > MAX_CONDITIONS) {
+        throw new Error(
+            `queryMappings: where must have at most ${MAX_CONDITIONS} conditions, anyOf members included`
+        );
+    }
+
+    return {
+        where: whereEntries,
+        orderBy: orderBy === undefined ? null : toOrderBy(orderBy),
+        skip,
+        take,
+        omit,
+    };
+}
+
+function toOrderBy(orderBy) {
+    if (!isPlainObject(orderBy)) {
+        throw new Error('queryMappings: orderBy must be an object');
+    }
+    const { field, segments } = parsePath(orderBy.path);
+    if (field !== 'mapping') {
+        throw new Error(
+            "queryMappings: orderBy.path must be a mapping path ('mapping.<segment>...')"
+        );
+    }
+    if (!DIRECTIONS.includes(orderBy.direction)) {
+        throw new Error(
+            "queryMappings: orderBy.direction must be 'asc' or 'desc'"
+        );
+    }
+    return { path: segments, direction: orderBy.direction };
+}
+
+function toWhereEntry(entry) {
+    assertWhereEntryShape(entry);
+    if (!('anyOf' in entry)) return toCondition(entry);
+
+    const { anyOf } = entry;
+    if (!Array.isArray(anyOf) || anyOf.length === 0) {
+        throw new Error('queryMappings: anyOf must be a non-empty array');
+    }
+    return {
+        anyOf: anyOf.map((condition) => {
+            assertWhereEntryShape(condition);
+            if ('anyOf' in condition) {
+                throw new Error('queryMappings: nested anyOf is not supported');
+            }
+            return toCondition(condition);
+        }),
+    };
+}
+
+function assertWhereEntryShape(entry) {
+    if (!isPlainObject(entry)) {
+        throw new Error('queryMappings: each where entry must be an object');
+    }
+}
+
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * `{ path: 'mapping.outbound.status', op: 'in', value: ['failed'] }` →
+ * `{ field: 'mapping', path: ['outbound', 'status'], op: 'in', value: ['failed'] }`.
+ * A `sourceId` condition has no `path`; an op without a value has no `value`.
+ */
+function toCondition({ path, op, value }) {
+    const { field, segments } = parsePath(path);
+    const operator = Object.hasOwn(OPERATORS, op) ? OPERATORS[op] : null;
+    if (!operator?.fields.includes(field)) {
+        throw new Error(
+            `queryMappings: op ${JSON.stringify(
+                op
+            )} is not allowed on '${path}' (allowed: ${operatorsOn(field).join(
+                ', '
+            )})`
+        );
+    }
+    return {
+        field,
+        ...(segments.length > 0 && { path: segments }),
+        op,
+        ...(operator.value && { value: operator.value(value, path) }),
+    };
+}
+
+function operatorsOn(field) {
+    return Object.keys(OPERATORS).filter((op) =>
+        OPERATORS[op].fields.includes(field)
+    );
+}
+
+function toStringList(value, path) {
+    if (
+        !Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((v) => typeof v === 'string')
+    ) {
+        throw new Error(
+            `queryMappings: 'in' value must be a non-empty array of strings on '${path}'`
+        );
+    }
+    if (value.length > MAX_IN_VALUES) {
+        throw new Error(
+            `queryMappings: 'in' value must have at most ${MAX_IN_VALUES} strings on '${path}'`
+        );
+    }
+    return value;
+}
+
+function toPrefix(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(
+            `queryMappings: 'notStartsWith' value must be a non-empty string on '${path}'`
+        );
+    }
+    return value;
+}
+
+/**
+ * `'mapping.outbound.status'` → `{ field: 'mapping', segments: ['outbound', 'status'] }`,
+ * `'sourceId'` → `{ field: 'sourceId', segments: [] }`.
+ */
+function parsePath(path) {
+    const [field, ...segments] =
+        typeof path === 'string' ? path.split('.') : [];
+    const valid =
+        (field === 'sourceId' && segments.length === 0) ||
+        (field === 'mapping' &&
+            segments.length > 0 &&
+            segments.every((segment) => SEGMENT_REGEX.test(segment)));
+    if (!valid) {
+        throw new Error(
+            `queryMappings: invalid path ${JSON.stringify(
+                path
+            )} (must be 'sourceId' or 'mapping.<segment>...' with segments matching ${SEGMENT_REGEX})`
+        );
+    }
+    return { field, segments };
+}
+
+module.exports = { validateMappingQuery };

package/integrations/repositories/integration-mapping-repository-documentdb.js

@@ -8,6 +8,7 @@ const {
     updateOne,
     deleteOne,
     deleteMany,
+    aggregate,
     aggregateDrained,
 } = require('../../database/documentdb-utils');
 const {
@@ -16,6 +17,20 @@ const {
 const {
     DocumentDBEncryptionService,
 } = require('../../database/documentdb-encryption-service');
+const {
+    assertMappingWrittenUnencrypted,
+} = require('../../database/encryption/integration-mapping-encryption');
+const { validateMappingQuery } = require('./integration-mapping-query');
+const {
+    buildMappingQueryStages,
+} = require('./integration-mapping-query-pipeline');
+
+function storedIntegrationId(id) {
+    if (!['string', 'number'].includes(typeof id) || id === '') {
+        throw new TypeError(`Invalid ID: ${id}`);
+    }
+    return String(id);
+}
 
 class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositoryInterface {
     constructor() {
@@ -179,6 +194,44 @@ class IntegrationMappingRepositoryDocumentDB extends IntegrationMappingRepositor
         return decryptedDocs.map((doc) => this._mapMapping(doc));
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const validated = validateMappingQuery(query);
+        const stored = storedIntegrationId(integrationId);
+        assertMappingWrittenUnencrypted();
+        const { match, page, sort } = buildMappingQueryStages(
+            stored,
+            validated
+        );
+
+        const [docs, counts] = await Promise.all([
+            aggregateDrained(
+                this.prisma,
+                'IntegrationMapping',
+                [match, ...page, sort],
+                { allowDiskUse: true }
+            ),
+            aggregate(this.prisma, 'IntegrationMapping', [
+                match,
+                { $count: 'total' },
+            ]),
+        ]);
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('IntegrationMapping', doc)
+            )
+        );
+
+        return {
+            mappings: decryptedDocs.map((doc) => this._mapMapping(doc)),
+            total: counts[0]?.total ?? 0,
+        };
+    }
+
     async deleteMapping(integrationId, sourceId) {
         const filter = this._compositeFilter(integrationId, sourceId);
         const result = await deleteOne(

package/integrations/repositories/integration-mapping-repository-interface.js

@@ -52,6 +52,54 @@ class IntegrationMappingRepositoryInterface {
         );
     }
 
+    /**
+     * Query one filtered, ordered page of an integration's mappings without
+     * loading every row. Rows have the same shape as findMappingsByIntegration
+     * and are decrypted the same way.
+     *
+     * Paths address the `mapping` JSON by identifier-only segments
+     * (`'mapping.outbound.status'`), or the `sourceId` column. Conditions:
+     * - `{ path: 'mapping.…', op: 'exists' | 'notExists' }` — JSON null counts
+     *   as absent; notExists is the exact negation of exists.
+     * - `{ path: 'mapping.…', op: 'in', value: string[] }` — matches JSON
+     *   strings; 1–500 values.
+     * - `{ path: 'sourceId', op: 'notStartsWith', value: string }` — a NULL
+     *   sourceId matches.
+     *
+     * Only rows whose `mapping` is a JSON object can match, so rows whose
+     * whole `mapping` is still ciphertext from before an encryption opt-out
+     * never do. A nested path still encrypted from before its opt-out comes
+     * back plain, but conditions and orderBy on it see the ciphertext.
+     * Adapters refuse to run while field-level encryption is enabled
+     * and still encrypts `mapping`, or a path inside it, on write; opt out with
+     * `appDefinition.encryption.disable = { IntegrationMapping: ['mapping'] }`
+     * plus any nested `mapping.…` path a custom schema encrypts.
+     *
+     * @param {string|number} integrationId - The integration ID
+     * @param {Object} query
+     * @param {Array<Object>} [query.where=[]] - Conditions ANDed together; an
+     *   entry may be `{ anyOf: Condition[] }` (one level, ORed). At most 20
+     *   conditions, anyOf members included.
+     * @param {{path: string, direction: 'asc'|'desc'}} [query.orderBy] - A
+     *   mapping path; nulls last, ties broken by id in the same direction.
+     *   Values order string < number < boolean < array < object. Strings
+     *   compare by the database collation on PostgreSQL and by code point on
+     *   MongoDB and DocumentDB; arrays and objects order among themselves
+     *   only on PostgreSQL. Without it rows are ordered by id ascending.
+     * @param {number} [query.skip=0] - Rows to skip (integer ≥ 0)
+     * @param {number} query.take - Page size (integer 1–500)
+     * @param {string[]} [query.omit=[]] - Top-level mapping keys to leave out of
+     *   the returned rows; such projected rows must not be written back
+     * @returns {Promise<{mappings: Array<Object>, total: number}>} The page, and
+     *   the number of rows matching `where` (counted by a separate command on
+     *   DocumentDB, so not from the page's snapshot)
+     */
+    async queryMappings(integrationId, query) {
+        throw new Error(
+            'queryMappings is not supported by this database adapter yet'
+        );
+    }
+
     /**
      * Delete a specific mapping
      *

package/integrations/repositories/integration-mapping-repository-mongo.js

@@ -1,7 +1,26 @@
 const { prisma } = require('../../database/prisma');
+const {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+} = require('../../database/encryption/integration-mapping-encryption');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
+const { validateMappingQuery } = require('./integration-mapping-query');
+const {
+    buildMappingQueryStages,
+} = require('./integration-mapping-query-pipeline');
+
+const OBJECT_ID_REGEX = /^[0-9a-fA-F]{24}$/;
+
+const fromRawDate = (raw) => new Date(raw.$date);
+
+function strictObjectId(id) {
+    if (typeof id !== 'string' || !OBJECT_ID_REGEX.test(id)) {
+        throw new TypeError(`Invalid ID: ${id} is not an ObjectId`);
+    }
+    return id;
+}
 
 /**
  * MongoDB Integration Mapping Repository Adapter
@@ -155,6 +174,59 @@ class IntegrationMappingRepositoryMongo extends IntegrationMappingRepositoryInte
         return counts;
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const validated = validateMappingQuery(query);
+        const objectId = strictObjectId(integrationId);
+        assertMappingWrittenUnencrypted();
+        const { match, page } = buildMappingQueryStages(
+            { $oid: objectId },
+            validated
+        );
+
+        const result = await this.prisma.$runCommandRaw({
+            aggregate: 'IntegrationMapping',
+            pipeline: [
+                match,
+                {
+                    $facet: {
+                        mappings: page,
+                        total: [{ $count: 'total' }],
+                    },
+                },
+            ],
+            cursor: {},
+            allowDiskUse: true,
+        });
+        const [{ mappings, total }] = result.cursor.firstBatch;
+
+        return {
+            mappings: await decryptQueriedMappings(
+                mappings.map((doc) => this._fromRawMapping(doc))
+            ),
+            total: total[0]?.total ?? 0,
+        };
+    }
+
+    /**
+     * A raw aggregate document, in the shape findMappingsByIntegration returns.
+     * @private
+     */
+    _fromRawMapping(doc) {
+        return {
+            id: doc._id.$oid,
+            integrationId: doc.integrationId.$oid,
+            sourceId: doc.sourceId ?? null,
+            mapping: doc.mapping ?? null,
+            createdAt: fromRawDate(doc.createdAt),
+            updatedAt: fromRawDate(doc.updatedAt),
+        };
+    }
+
     /**
      * Find mapping by ID
      * @param {string} id - Mapping ID

package/integrations/repositories/integration-mapping-repository-postgres.js

@@ -1,8 +1,31 @@
 const { prisma } = require('../../database/prisma');
+const {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+} = require('../../database/encryption/integration-mapping-encryption');
 const {
     IntegrationMappingRepositoryInterface,
 } = require('./integration-mapping-repository-interface');
 const { strictIntId } = require('./report-id');
+const { validateMappingQuery } = require('./integration-mapping-query');
+
+const COLUMNS = { mapping: '"mapping"', sourceId: '"sourceId"' };
+const SQL_DIRECTIONS = { asc: 'ASC', desc: 'DESC' };
+
+const jsonPathOperand = (column, path) => ({
+    json: `${column} #> ${path}::text[]`,
+    text: `${column} #>> ${path}::text[]`,
+});
+const jsonType = (json) => `COALESCE(jsonb_typeof(${json}), 'null')`;
+
+const CONDITION_SQL = {
+    exists: ({ json }) => `${jsonType(json)} <> 'null'`,
+    notExists: ({ json }) => `${jsonType(json)} = 'null'`,
+    in: ({ json, text, value }) =>
+        `(jsonb_typeof(${json}) = 'string' AND ${text} = ANY(${value}::text[]))`,
+    notStartsWith: ({ text, value }) =>
+        `(${text} IS NULL OR NOT starts_with(${text}, ${value}::text))`,
+};
 
 /**
  * PostgreSQL Integration Mapping Repository Adapter
@@ -216,6 +239,101 @@ class IntegrationMappingRepositoryPostgres extends IntegrationMappingRepositoryI
         return counts;
     }
 
+    /**
+     * @param {string} integrationId
+     * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+     * @returns {Promise<{mappings: Array<Object>, total: number}>}
+     */
+    async queryMappings(integrationId, query) {
+        const { where, orderBy, skip, take, omit } =
+            validateMappingQuery(query);
+        const intIntegrationId = strictIntId(integrationId);
+        assertMappingWrittenUnencrypted();
+
+        const params = [];
+        const bind = (v) => {
+            params.push(v);
+            return `$${params.length}`;
+        };
+
+        const whereSql = [
+            `"integrationId" = ${bind(intIntegrationId)}::int`,
+            `jsonb_typeof("mapping") = 'object'`,
+            ...where.map((entry) => this._whereEntrySql(entry, bind)),
+        ].join(' AND ');
+        const orderSql = orderBy ? this._orderSql(orderBy, bind) : `"id" ASC`;
+        const mappingSql =
+            omit.length > 0
+                ? `"mapping" - ${bind(omit)}::text[] AS "mapping"`
+                : `"mapping"`;
+
+        const sql = `
+            WITH "matched" AS (
+                SELECT "id", "integrationId", "sourceId", "mapping", "createdAt", "updatedAt"
+                FROM "IntegrationMapping"
+                WHERE ${whereSql}
+            ),
+            "page" AS (
+                SELECT * FROM "matched"
+                ORDER BY ${orderSql}
+                OFFSET ${bind(skip)}::bigint
+                LIMIT ${bind(take)}::int
+            )
+            SELECT "id", "integrationId", "sourceId", ${mappingSql}, "createdAt", "updatedAt",
+                (SELECT COUNT(*)::int FROM "matched") AS "__total"
+            FROM (VALUES (1)) AS "one"
+            LEFT JOIN "page" ON true
+            ORDER BY ${orderSql}
+        `;
+        const rows = await this.prisma.$queryRawUnsafe(sql, ...params);
+        const mappings = await decryptQueriedMappings(
+            rows
+                .filter((row) => row.id !== null)
+                .map(({ __total, ...row }) => this._convertMappingIds(row))
+        );
+
+        return { mappings, total: rows[0].__total };
+    }
+
+    /**
+     * One where entry: a condition, or an anyOf group as a parenthesized OR.
+     * @private
+     */
+    _whereEntrySql(entry, bind) {
+        if (!entry.anyOf) return this._conditionSql(entry, bind);
+        const alternatives = entry.anyOf.map((condition) =>
+            this._conditionSql(condition, bind)
+        );
+        return `(${alternatives.join(' OR ')})`;
+    }
+
+    /**
+     * SQL predicate for one validated queryMappings condition. `exists`
+     * treats JSON null as absent, and `notExists` is its exact negation.
+     * @private
+     */
+    _conditionSql({ field, path, op, value }, bind) {
+        const column = COLUMNS[field];
+        const operand = path
+            ? jsonPathOperand(column, bind(path))
+            : { text: column };
+        return CONDITION_SQL[op]({
+            ...operand,
+            value: value === undefined ? undefined : bind(value),
+        });
+    }
+
+    /**
+     * NULLIF folds JSON null into SQL NULL, so both sort after every value.
+     * @private
+     */
+    _orderSql({ path, direction }, bind) {
+        const { json } = jsonPathOperand(COLUMNS.mapping, bind(path));
+        const value = `NULLIF(${json}, 'null'::jsonb)`;
+        const sqlDirection = SQL_DIRECTIONS[direction];
+        return `${value} ${sqlDirection} NULLS LAST, "id" ${sqlDirection}`;
+    }
+
     /**
      * Find mapping by ID
      * @param {string} id - Mapping ID (string from application layer)

package/logs/record.js

@@ -181,6 +181,8 @@ function buildRecord({
 
     const dropped = new Set();
     const callSiteKeys = [];
+    // Call-site keys merged into the scope invocation; the size cap must reach them too.
+    const invocationDetailKeys = [];
     const place = ({ entries, dropped: droppedHere }, isCallSite) => {
         for (const key of droppedHere) dropped.add(key);
         for (const [key, value] of entries) {
@@ -190,7 +192,13 @@ function buildRecord({
                     isPlainObject(record[key]) &&
                     isPlainObject(value)
                 ) {
-                    record[key] = extendInvocation(record[key], value);
+                    const merged = extendInvocation(record[key], value);
+                    if (isCallSite) {
+                        for (const detailKey of Object.keys(value)) {
+                            if (!(detailKey in record[key])) invocationDetailKeys.push(detailKey);
+                        }
+                    }
+                    record[key] = merged;
                 } else if (!sameValue(record[key], value)) {
                     // A repeat of the winning value is no conflict.
                     dropped.add(key);
@@ -213,13 +221,30 @@ function buildRecord({
     let size = byteLength(record);
 
     if (size > MAX_RECORD_BYTES) {
-        const bySize = callSiteKeys
-            .filter((key) => key !== 'error')
-            .map((key) => [key, Buffer.byteLength(JSON.stringify(record[key]))])
+        const candidates = [
+            ...callSiteKeys
+                .filter((key) => key !== 'error')
+                .map((key) => ({
+                    name: key,
+                    value: record[key],
+                    remove: () => delete record[key],
+                })),
+            ...invocationDetailKeys.map((key) => ({
+                name: `${INVOCATION_KEY}.${key}`,
+                value: record[INVOCATION_KEY][key],
+                remove: () => {
+                    const rest = { ...record[INVOCATION_KEY] };
+                    delete rest[key];
+                    record[INVOCATION_KEY] = rest;
+                },
+            })),
+        ];
+        const bySize = candidates
+            .map((candidate) => [candidate, Buffer.byteLength(JSON.stringify(candidate.value))])
             .sort((a, b) => b[1] - a[1]);
-        for (const [key] of bySize) {
-            delete record[key];
-            dropped.add(key);
+        for (const [candidate] of bySize) {
+            candidate.remove();
+            dropped.add(candidate.name);
             setDroppedKeys();
             size = byteLength(record);
             if (size <= MAX_RECORD_BYTES) break;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.654.70623e2.0",
+    "version": "2.0.0--canary.654.6d3a665.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.654.70623e2.0",
-        "@friggframework/prettier-config": "2.0.0--canary.654.70623e2.0",
-        "@friggframework/test": "2.0.0--canary.654.70623e2.0",
+        "@friggframework/eslint-config": "2.0.0--canary.654.6d3a665.0",
+        "@friggframework/prettier-config": "2.0.0--canary.654.6d3a665.0",
+        "@friggframework/test": "2.0.0--canary.654.6d3a665.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "70623e2fbe9d93afb370528085ea543c784775c4"
+    "gitHead": "6d3a6653a3227177ec6f96b5e2657ee67a0a6841"
 }

package/queues/queue-delivery.js

@@ -0,0 +1,41 @@
+const INTEGRATION_QUEUE_MAX_RECEIVE_COUNT = 3;
+const QUEUE_MAX_RECEIVE_COUNT_ENV = 'FRIGG_QUEUE_MAX_RECEIVE_COUNT';
+
+const toPositiveInteger = (value) => {
+    const number = Number(value);
+    return Number.isInteger(number) && number > 0 ? number : undefined;
+};
+
+/**
+ * @typedef {Object} QueueDelivery
+ * @property {number|undefined} receiveCount SQS ApproximateReceiveCount of this delivery.
+ * @property {number|undefined} maxReceiveCount Receives allowed before the queue dead-letters the message.
+ * @property {boolean} isLastAttempt True only when both counts are known and receiveCount >= maxReceiveCount.
+ */
+
+/**
+ * @param {Object} record SQS event record
+ * @param {Object} [env=process.env]
+ * @returns {QueueDelivery}
+ */
+const readQueueDelivery = (record, env = process.env) => {
+    const receiveCount = toPositiveInteger(
+        record?.attributes?.ApproximateReceiveCount
+    );
+    const maxReceiveCount = toPositiveInteger(env[QUEUE_MAX_RECEIVE_COUNT_ENV]);
+
+    return {
+        receiveCount,
+        maxReceiveCount,
+        isLastAttempt:
+            receiveCount !== undefined &&
+            maxReceiveCount !== undefined &&
+            receiveCount >= maxReceiveCount,
+    };
+};
+
+module.exports = {
+    INTEGRATION_QUEUE_MAX_RECEIVE_COUNT,
+    QUEUE_MAX_RECEIVE_COUNT_ENV,
+    readQueueDelivery,
+};