@friggframework/core 2.0.0-next.80 → 2.0.0-next.82

package/generated/prisma-postgresql/schema.prisma

@@ -6,7 +6,13 @@ generator client {
   provider      = "prisma-client-js"
   output        = "../generated/prisma-postgresql"
   binaryTargets = ["native", "rhel-openssl-3.0.x"] // native for local dev, rhel for Lambda deployment
-  engineType    = "binary" // Use binary engines (smaller size)
+  // Library engine (default since Prisma 3.x): Rust query engine loads as a
+  // Node-API addon inside the same process. The binary engine forks a child
+  // query-engine subprocess and communicates over a local HTTP/IPC pipe with
+  // NO client-side timeout — a zombied child wedges the Node process until
+  // Lambda's 900s cap. Switching to library eliminates that entire class of
+  // silent hangs. See friggframework/frigg#580 for the investigation.
+  engineType    = "library"
 }
 
 datasource db {

package/generated/prisma-postgresql/wasm.js

@@ -293,7 +293,7 @@ const config = {
       "fromEnvVar": null
     },
     "config": {
-      "engineType": "binary"
+      "engineType": "library"
     },
     "binaryTargets": [
       {
@@ -330,8 +330,8 @@ const config = {
       }
     }
   },
-  "inlineSchema": "// Frigg Framework - Prisma Schema (PostgreSQL)\n// PostgreSQL database schema for enterprise integration platform\n// Converted from MongoDB schema for relational database support\n\ngenerator client {\n  provider      = \"prisma-client-js\"\n  output        = \"../generated/prisma-postgresql\"\n  binaryTargets = [\"native\", \"rhel-openssl-3.0.x\"] // native for local dev, rhel for Lambda deployment\n  engineType    = \"binary\" // Use binary engines (smaller size)\n}\n\ndatasource db {\n  provider = \"postgresql\"\n  url      = env(\"DATABASE_URL\")\n}\n\n// ============================================================================\n// USER MODELS\n// ============================================================================\n\n/// User model with discriminator pattern support\n/// Replaces Mongoose discriminators (IndividualUser, OrganizationUser)\nmodel User {\n  id   Int      @id @default(autoincrement())\n  type UserType\n\n  // Timestamps\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // IndividualUser fields (nullable for organizations)\n  email          String?\n  username       String?\n  hashword       String? // Bcrypt hashed password (handled in application layer)\n  appUserId      String?\n  organizationId Int?\n\n  // Self-referential relation for organization membership\n  organization User?  @relation(\"OrgMembers\", fields: [organizationId], references: [id], onDelete: NoAction, onUpdate: NoAction)\n  members      User[] @relation(\"OrgMembers\")\n\n  // OrganizationUser fields (nullable for individuals)\n  appOrgId String?\n  name     String?\n\n  // Relations\n  tokens       Token[]\n  credentials  Credential[]\n  entities     Entity[]\n  integrations Integration[]\n  processes    Process[]\n\n  @@unique([username, appUserId])\n  @@index([type])\n  @@index([appUserId])\n}\n\nenum UserType {\n  INDIVIDUAL\n  ORGANIZATION\n}\n\n// ============================================================================\n// AUTHENTICATION MODELS\n// ============================================================================\n\n/// Authentication tokens with expiration\n/// Bcrypt hashed tokens stored (handled in application layer)\nmodel Token {\n  id      Int       @id @default(autoincrement())\n  token   String // Bcrypt hashed\n  created DateTime  @default(now())\n  expires DateTime?\n  userId  Int\n  user    User      @relation(fields: [userId], references: [id], onDelete: Cascade)\n\n  @@index([userId])\n  @@index([expires])\n}\n\n// ============================================================================\n// CREDENTIAL & ENTITY MODELS\n// ============================================================================\n\n/// OAuth credentials and API tokens\n/// All sensitive data encrypted with KMS at rest\nmodel Credential {\n  id          Int      @id @default(autoincrement())\n  userId      Int?\n  user        User?    @relation(fields: [userId], references: [id], onDelete: Cascade)\n  authIsValid Boolean?\n  externalId  String?\n\n  // Dynamic OAuth fields stored as JSON (encrypted via Prisma middleware)\n  // Contains: access_token, refresh_token, domain, expires_in, token_type, etc.\n  data Json @default(\"{}\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations\n  entities Entity[]\n\n  @@index([userId])\n  @@index([externalId])\n}\n\n/// External service entities (API connections)\nmodel Entity {\n  id           Int         @id @default(autoincrement())\n  credentialId Int?\n  credential   Credential? @relation(fields: [credentialId], references: [id], onDelete: SetNull)\n  userId       Int?\n  user         User?       @relation(fields: [userId], references: [id], onDelete: Cascade)\n  name         String?\n  moduleName   String?\n  externalId   String?\n\n  data Json @default(\"{}\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations - many-to-many with implicit join tables\n  integrations Integration[]\n  syncs        Sync[]\n\n  dataIdentifiers    DataIdentifier[]\n  associationObjects AssociationObject[]\n\n  @@index([userId])\n  @@index([externalId])\n  @@index([moduleName])\n  @@index([credentialId])\n}\n\n// ============================================================================\n// INTEGRATION MODELS\n// ============================================================================\n\n/// Main integration configuration and state\nmodel Integration {\n  id     Int               @id @default(autoincrement())\n  userId Int?\n  user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)\n  status IntegrationStatus @default(ENABLED)\n\n  // Configuration and version\n  config  Json? // Integration configuration object\n  version String?\n\n  // Entity references (many-to-many via implicit join table)\n  entities Entity[]\n\n  // Message arrays (stored as JSON)\n  errors   Json @default(\"[]\")\n  warnings Json @default(\"[]\")\n  info     Json @default(\"[]\")\n  logs     Json @default(\"[]\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations\n  associations Association[]\n  syncs        Sync[]\n  mappings     IntegrationMapping[]\n  processes    Process[]\n\n  @@index([userId])\n  @@index([status])\n}\n\nenum IntegrationStatus {\n  ENABLED\n  NEEDS_CONFIG\n  PROCESSING\n  DISABLED\n  ERROR\n}\n\n/// Integration-specific data mappings\n/// All mapping data encrypted with KMS\nmodel IntegrationMapping {\n  id            Int         @id @default(autoincrement())\n  integrationId Int\n  integration   Integration @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n  sourceId      String?\n\n  // Encrypted mapping data (handled via Prisma middleware)\n  mapping Json?\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  @@unique([integrationId, sourceId])\n  @@index([integrationId])\n  @@index([sourceId])\n}\n\n// ============================================================================\n// SYNC MODELS\n// ============================================================================\n\n/// Bidirectional data synchronization tracking\nmodel Sync {\n  id            Int          @id @default(autoincrement())\n  integrationId Int?\n  integration   Integration? @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n\n  // Entity references (many-to-many via implicit join table)\n  entities Entity[]\n\n  hash String\n  name String\n\n  // Data identifiers (extracted to separate model)\n  dataIdentifiers DataIdentifier[]\n\n  @@index([integrationId])\n  @@index([hash])\n  @@index([name])\n}\n\n/// Data identifier for sync operations\n/// Replaces nested array structure in Mongoose\nmodel DataIdentifier {\n  id       Int    @id @default(autoincrement())\n  syncId   Int?\n  sync     Sync?  @relation(fields: [syncId], references: [id], onDelete: Cascade)\n  entityId Int\n  entity   Entity @relation(fields: [entityId], references: [id], onDelete: Cascade)\n\n  // Identifier data (can be any structure)\n  idData Json\n\n  hash String\n\n  @@index([syncId])\n  @@index([entityId])\n  @@index([hash])\n}\n\n// ============================================================================\n// ASSOCIATION MODELS\n// ============================================================================\n\n/// Entity associations with cardinality tracking\nmodel Association {\n  id            Int             @id @default(autoincrement())\n  integrationId Int\n  integration   Integration     @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n  name          String\n  type          AssociationType\n  primaryObject String\n\n  // Associated objects (extracted to separate model)\n  objects AssociationObject[]\n\n  @@index([integrationId])\n  @@index([name])\n}\n\n/// Association object entry\n/// Replaces nested array structure in Mongoose\nmodel AssociationObject {\n  id            Int         @id @default(autoincrement())\n  associationId Int\n  association   Association @relation(fields: [associationId], references: [id], onDelete: Cascade)\n  entityId      Int\n  entity        Entity      @relation(fields: [entityId], references: [id], onDelete: Cascade)\n  objectType    String\n  objId         String\n  metadata      Json? // Optional metadata\n\n  @@index([associationId])\n  @@index([entityId])\n}\n\nenum AssociationType {\n  ONE_TO_MANY\n  ONE_TO_ONE\n  MANY_TO_ONE\n}\n\n// ============================================================================\n// PROCESS MODELS\n// ============================================================================\n\n/// Generic Process Model - tracks any long-running operation\n/// Used for: CRM syncs, data migrations, bulk operations, etc.\nmodel Process {\n  id Int @id @default(autoincrement())\n\n  // Core references\n  userId        Int\n  user          User        @relation(fields: [userId], references: [id], onDelete: Cascade)\n  integrationId Int\n  integration   Integration @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n\n  // Process identification\n  name String // e.g., \"zoho-crm-contact-sync\", \"pipedrive-lead-sync\"\n  type String // e.g., \"CRM_SYNC\", \"DATA_MIGRATION\", \"BULK_OPERATION\"\n\n  // State machine\n  state String // Current state (integration-defined states)\n\n  // Flexible storage\n  context Json @default(\"{}\") // Process-specific data (pagination, metadata, etc.)\n  results Json @default(\"{}\") // Process results and metrics\n\n  // Hierarchy support - self-referential relation\n  parentProcessId Int?\n  parentProcess   Process?  @relation(\"ProcessHierarchy\", fields: [parentProcessId], references: [id], onDelete: SetNull)\n  childProcesses  Process[] @relation(\"ProcessHierarchy\")\n\n  // Timestamps\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  @@index([userId])\n  @@index([integrationId])\n  @@index([type])\n  @@index([state])\n  @@index([name])\n  @@index([parentProcessId])\n}\n\n// ============================================================================\n// UTILITY MODELS\n// ============================================================================\n\n/// Generic state storage\nmodel State {\n  id    Int   @id @default(autoincrement())\n  state Json?\n}\n\n/// AWS API Gateway WebSocket connection tracking\nmodel WebsocketConnection {\n  id           Int     @id @default(autoincrement())\n  connectionId String?\n\n  @@index([connectionId])\n}\n",
-  "inlineSchemaHash": "a53140906632700b021910998a3bbd7b9743a1e27ef2f8459dedccffdb8a0035",
+  "inlineSchema": "// Frigg Framework - Prisma Schema (PostgreSQL)\n// PostgreSQL database schema for enterprise integration platform\n// Converted from MongoDB schema for relational database support\n\ngenerator client {\n  provider      = \"prisma-client-js\"\n  output        = \"../generated/prisma-postgresql\"\n  binaryTargets = [\"native\", \"rhel-openssl-3.0.x\"] // native for local dev, rhel for Lambda deployment\n  // Library engine (default since Prisma 3.x): Rust query engine loads as a\n  // Node-API addon inside the same process. The binary engine forks a child\n  // query-engine subprocess and communicates over a local HTTP/IPC pipe with\n  // NO client-side timeout — a zombied child wedges the Node process until\n  // Lambda's 900s cap. Switching to library eliminates that entire class of\n  // silent hangs. See friggframework/frigg#580 for the investigation.\n  engineType    = \"library\"\n}\n\ndatasource db {\n  provider = \"postgresql\"\n  url      = env(\"DATABASE_URL\")\n}\n\n// ============================================================================\n// USER MODELS\n// ============================================================================\n\n/// User model with discriminator pattern support\n/// Replaces Mongoose discriminators (IndividualUser, OrganizationUser)\nmodel User {\n  id   Int      @id @default(autoincrement())\n  type UserType\n\n  // Timestamps\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // IndividualUser fields (nullable for organizations)\n  email          String?\n  username       String?\n  hashword       String? // Bcrypt hashed password (handled in application layer)\n  appUserId      String?\n  organizationId Int?\n\n  // Self-referential relation for organization membership\n  organization User?  @relation(\"OrgMembers\", fields: [organizationId], references: [id], onDelete: NoAction, onUpdate: NoAction)\n  members      User[] @relation(\"OrgMembers\")\n\n  // OrganizationUser fields (nullable for individuals)\n  appOrgId String?\n  name     String?\n\n  // Relations\n  tokens       Token[]\n  credentials  Credential[]\n  entities     Entity[]\n  integrations Integration[]\n  processes    Process[]\n\n  @@unique([username, appUserId])\n  @@index([type])\n  @@index([appUserId])\n}\n\nenum UserType {\n  INDIVIDUAL\n  ORGANIZATION\n}\n\n// ============================================================================\n// AUTHENTICATION MODELS\n// ============================================================================\n\n/// Authentication tokens with expiration\n/// Bcrypt hashed tokens stored (handled in application layer)\nmodel Token {\n  id      Int       @id @default(autoincrement())\n  token   String // Bcrypt hashed\n  created DateTime  @default(now())\n  expires DateTime?\n  userId  Int\n  user    User      @relation(fields: [userId], references: [id], onDelete: Cascade)\n\n  @@index([userId])\n  @@index([expires])\n}\n\n// ============================================================================\n// CREDENTIAL & ENTITY MODELS\n// ============================================================================\n\n/// OAuth credentials and API tokens\n/// All sensitive data encrypted with KMS at rest\nmodel Credential {\n  id          Int      @id @default(autoincrement())\n  userId      Int?\n  user        User?    @relation(fields: [userId], references: [id], onDelete: Cascade)\n  authIsValid Boolean?\n  externalId  String?\n\n  // Dynamic OAuth fields stored as JSON (encrypted via Prisma middleware)\n  // Contains: access_token, refresh_token, domain, expires_in, token_type, etc.\n  data Json @default(\"{}\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations\n  entities Entity[]\n\n  @@index([userId])\n  @@index([externalId])\n}\n\n/// External service entities (API connections)\nmodel Entity {\n  id           Int         @id @default(autoincrement())\n  credentialId Int?\n  credential   Credential? @relation(fields: [credentialId], references: [id], onDelete: SetNull)\n  userId       Int?\n  user         User?       @relation(fields: [userId], references: [id], onDelete: Cascade)\n  name         String?\n  moduleName   String?\n  externalId   String?\n\n  data Json @default(\"{}\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations - many-to-many with implicit join tables\n  integrations Integration[]\n  syncs        Sync[]\n\n  dataIdentifiers    DataIdentifier[]\n  associationObjects AssociationObject[]\n\n  @@index([userId])\n  @@index([externalId])\n  @@index([moduleName])\n  @@index([credentialId])\n}\n\n// ============================================================================\n// INTEGRATION MODELS\n// ============================================================================\n\n/// Main integration configuration and state\nmodel Integration {\n  id     Int               @id @default(autoincrement())\n  userId Int?\n  user   User?             @relation(fields: [userId], references: [id], onDelete: Cascade)\n  status IntegrationStatus @default(ENABLED)\n\n  // Configuration and version\n  config  Json? // Integration configuration object\n  version String?\n\n  // Entity references (many-to-many via implicit join table)\n  entities Entity[]\n\n  // Message arrays (stored as JSON)\n  errors   Json @default(\"[]\")\n  warnings Json @default(\"[]\")\n  info     Json @default(\"[]\")\n  logs     Json @default(\"[]\")\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  // Relations\n  associations Association[]\n  syncs        Sync[]\n  mappings     IntegrationMapping[]\n  processes    Process[]\n\n  @@index([userId])\n  @@index([status])\n}\n\nenum IntegrationStatus {\n  ENABLED\n  NEEDS_CONFIG\n  PROCESSING\n  DISABLED\n  ERROR\n}\n\n/// Integration-specific data mappings\n/// All mapping data encrypted with KMS\nmodel IntegrationMapping {\n  id            Int         @id @default(autoincrement())\n  integrationId Int\n  integration   Integration @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n  sourceId      String?\n\n  // Encrypted mapping data (handled via Prisma middleware)\n  mapping Json?\n\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  @@unique([integrationId, sourceId])\n  @@index([integrationId])\n  @@index([sourceId])\n}\n\n// ============================================================================\n// SYNC MODELS\n// ============================================================================\n\n/// Bidirectional data synchronization tracking\nmodel Sync {\n  id            Int          @id @default(autoincrement())\n  integrationId Int?\n  integration   Integration? @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n\n  // Entity references (many-to-many via implicit join table)\n  entities Entity[]\n\n  hash String\n  name String\n\n  // Data identifiers (extracted to separate model)\n  dataIdentifiers DataIdentifier[]\n\n  @@index([integrationId])\n  @@index([hash])\n  @@index([name])\n}\n\n/// Data identifier for sync operations\n/// Replaces nested array structure in Mongoose\nmodel DataIdentifier {\n  id       Int    @id @default(autoincrement())\n  syncId   Int?\n  sync     Sync?  @relation(fields: [syncId], references: [id], onDelete: Cascade)\n  entityId Int\n  entity   Entity @relation(fields: [entityId], references: [id], onDelete: Cascade)\n\n  // Identifier data (can be any structure)\n  idData Json\n\n  hash String\n\n  @@index([syncId])\n  @@index([entityId])\n  @@index([hash])\n}\n\n// ============================================================================\n// ASSOCIATION MODELS\n// ============================================================================\n\n/// Entity associations with cardinality tracking\nmodel Association {\n  id            Int             @id @default(autoincrement())\n  integrationId Int\n  integration   Integration     @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n  name          String\n  type          AssociationType\n  primaryObject String\n\n  // Associated objects (extracted to separate model)\n  objects AssociationObject[]\n\n  @@index([integrationId])\n  @@index([name])\n}\n\n/// Association object entry\n/// Replaces nested array structure in Mongoose\nmodel AssociationObject {\n  id            Int         @id @default(autoincrement())\n  associationId Int\n  association   Association @relation(fields: [associationId], references: [id], onDelete: Cascade)\n  entityId      Int\n  entity        Entity      @relation(fields: [entityId], references: [id], onDelete: Cascade)\n  objectType    String\n  objId         String\n  metadata      Json? // Optional metadata\n\n  @@index([associationId])\n  @@index([entityId])\n}\n\nenum AssociationType {\n  ONE_TO_MANY\n  ONE_TO_ONE\n  MANY_TO_ONE\n}\n\n// ============================================================================\n// PROCESS MODELS\n// ============================================================================\n\n/// Generic Process Model - tracks any long-running operation\n/// Used for: CRM syncs, data migrations, bulk operations, etc.\nmodel Process {\n  id Int @id @default(autoincrement())\n\n  // Core references\n  userId        Int\n  user          User        @relation(fields: [userId], references: [id], onDelete: Cascade)\n  integrationId Int\n  integration   Integration @relation(fields: [integrationId], references: [id], onDelete: Cascade)\n\n  // Process identification\n  name String // e.g., \"zoho-crm-contact-sync\", \"pipedrive-lead-sync\"\n  type String // e.g., \"CRM_SYNC\", \"DATA_MIGRATION\", \"BULK_OPERATION\"\n\n  // State machine\n  state String // Current state (integration-defined states)\n\n  // Flexible storage\n  context Json @default(\"{}\") // Process-specific data (pagination, metadata, etc.)\n  results Json @default(\"{}\") // Process results and metrics\n\n  // Hierarchy support - self-referential relation\n  parentProcessId Int?\n  parentProcess   Process?  @relation(\"ProcessHierarchy\", fields: [parentProcessId], references: [id], onDelete: SetNull)\n  childProcesses  Process[] @relation(\"ProcessHierarchy\")\n\n  // Timestamps\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  @@index([userId])\n  @@index([integrationId])\n  @@index([type])\n  @@index([state])\n  @@index([name])\n  @@index([parentProcessId])\n}\n\n// ============================================================================\n// UTILITY MODELS\n// ============================================================================\n\n/// Generic state storage\nmodel State {\n  id    Int   @id @default(autoincrement())\n  state Json?\n}\n\n/// AWS API Gateway WebSocket connection tracking\nmodel WebsocketConnection {\n  id           Int     @id @default(autoincrement())\n  connectionId String?\n\n  @@index([connectionId])\n}\n",
+  "inlineSchemaHash": "f3edba5bb5e72088ff5a6505548bd90aa528e5e99e6433c2eed6eed57dcd25ab",
   "copyEngine": true
 }
 config.dirname = '/'

package/integrations/integration-router.js

@@ -507,7 +507,8 @@ function setEntityRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.query, ['entityType']);
             const module = await getModuleInstanceFromType.execute(
                 userId,
-                params.entityType
+                params.entityType,
+                { state: req.query.state }
             );
             const areRequirementsValid =
                 module.validateAuthorizationRequirements();
@@ -530,13 +531,33 @@ function setEntityRoutes(router, authenticateUser, useCases) {
                 'data',
             ]);
 
-            const entityDetails = await processAuthorizationCallback.execute(
-                userId,
-                params.entityType,
-                params.data
+            const dataKeys =
+                params.data && typeof params.data === 'object'
+                    ? Object.keys(params.data)
+                    : [];
+            console.log(
+                `[Frigg] POST /api/authorize userId=${userId} entityType=${params.entityType} dataKeys=${JSON.stringify(dataKeys)}`
             );
 
-            res.json(entityDetails);
+            try {
+                const entityDetails =
+                    await processAuthorizationCallback.execute(
+                        userId,
+                        params.entityType,
+                        params.data
+                    );
+
+                console.log(
+                    `[Frigg] POST /api/authorize success userId=${userId} entityType=${params.entityType} credentialId=${entityDetails?.credential_id} entityId=${entityDetails?.entity_id}`
+                );
+
+                res.json(entityDetails);
+            } catch (err) {
+                console.error(
+                    `[Frigg] POST /api/authorize failed userId=${userId} entityType=${params.entityType} error=${err?.message || err}`
+                );
+                throw err;
+            }
         })
     );
 

package/integrations/repositories/process-repository-documentdb.js

@@ -14,6 +14,7 @@ const {
 const {
     DocumentDBEncryptionService,
 } = require('../../database/documentdb-encryption-service');
+const { validateOps } = require('./process-update-ops-shared');
 
 class ProcessRepositoryDocumentDB extends ProcessRepositoryInterface {
     constructor() {
@@ -155,6 +156,73 @@ class ProcessRepositoryDocumentDB extends ProcessRepositoryInterface {
         return this._mapProcess(decryptedProcess);
     }
 
+    /**
+     * Atomic process update — race-safe counterpart to `update()`.
+     *
+     * Uses DocumentDB's native $inc / $set / $push operators (Mongo-wire
+     * compatible) via findAndModify so increments, sets, and pushes land
+     * in one server-side write. Contention on the same document
+     * serializes at the DB level.
+     *
+     * DocumentDB compatibility notes:
+     *  - $inc: supported since v3.6.
+     *  - $set with dot-path: supported.
+     *  - $push with $each + negative $slice: supported since v4.0.
+     *    Clusters still on v3.6 must upgrade before using pushSlice.
+     *
+     * Process documents have no encrypted fields today; if that changes,
+     * the set-by-path payload here MUST route through
+     * `encryptionService.encryptFields` for any affected paths.
+     *
+     * @param {string} processId
+     * @param {import('./process-repository-interface').ProcessUpdateOps} ops
+     * @returns {Promise<Object|null>}
+     */
+    async applyProcessUpdate(processId, ops) {
+        const normalized = validateOps(ops);
+        const objectId = toObjectId(processId);
+
+        const update = {};
+        const $set = {};
+
+        if (Object.keys(normalized.increment).length > 0) {
+            update.$inc = { ...normalized.increment };
+        }
+        for (const [path, value] of Object.entries(normalized.set)) {
+            $set[path] = value;
+        }
+        if (normalized.newState !== null) {
+            $set.state = normalized.newState;
+        }
+        $set.updatedAt = new Date();
+        update.$set = $set;
+
+        if (Object.keys(normalized.pushSlice).length > 0) {
+            update.$push = {};
+            for (const [path, spec] of Object.entries(normalized.pushSlice)) {
+                update.$push[path] = {
+                    $each: spec.values,
+                    $slice: -spec.keepLast,
+                };
+            }
+        }
+
+        const result = await this.prisma.$runCommandRaw({
+            findAndModify: 'Process',
+            query: { _id: objectId },
+            update,
+            new: true,
+        });
+
+        const doc = result && result.value;
+        if (!doc) return null;
+        const decrypted = await this.encryptionService.decryptFields(
+            'Process',
+            doc
+        );
+        return this._mapProcess(decrypted);
+    }
+
     async findByIntegrationAndType(integrationId, type) {
         const integrationObjectId = toObjectId(integrationId);
         const filter = {

package/integrations/repositories/process-repository-interface.js

@@ -47,6 +47,52 @@ class ProcessRepositoryInterface {
         throw new Error('Method update() must be implemented');
     }
 
+    /**
+     * Apply atomic mutations to a process record.
+     *
+     * Race-safe counterpart to `update()`. Where `update()` takes full
+     * JSON blobs and does read-modify-write at the ORM layer (clobber-
+     * prone under concurrent writers), `applyProcessUpdate()` describes
+     * the intent declaratively and each backend uses its native atomic
+     * primitive:
+     *   - PostgreSQL: `jsonb_set` chain inside a single UPDATE ... RETURNING
+     *   - MongoDB: `$inc` / `$set` / `$push` via findAndModify
+     *   - DocumentDB: same operator set as MongoDB (with version caveats)
+     *
+     * All paths are dot-delimited and rooted in `context` or `results`
+     * (e.g. `context.processedRecords`,
+     * `results.aggregateData.totalSynced`). Paths MUST match
+     * `^(context|results)(\\.[a-zA-Z_][a-zA-Z0-9_]*)+$` — validated by
+     * each adapter before any SQL/command generation.
+     *
+     * Intended primary callers: UpdateProcessMetrics and
+     * UpdateProcessState. Other callers can use this directly when they
+     * need race-free cumulative updates.
+     *
+     * @typedef {Object} ProcessUpdateOps
+     * @property {Object.<string, number>} [increment] - Atomic numeric
+     *   increments keyed by dot-path. e.g.
+     *   `{ 'context.processedRecords': 1, 'results.aggregateData.totalSynced': 1 }`
+     * @property {Object.<string, *>} [set] - Atomic whole-subtree set
+     *   keyed by dot-path. Replaces the value at the path (NOT deep
+     *   merge). e.g. `{ 'context.fetchDone': true }`
+     * @property {Object.<string, {values: Array, keepLast: number}>} [pushSlice]
+     *   Atomic array push with bounded retention (sliding window of the
+     *   last `keepLast` items). Keys are dot-paths pointing to arrays.
+     *   e.g. `{ 'results.aggregateData.errors': { values: [err], keepLast: 100 } }`
+     * @property {string} [newState] - Top-level `state` column update.
+     *   Written alongside the JSON mutations in the same UPDATE so state
+     *   + counters move together.
+     *
+     * @param {string} processId - Process ID to update
+     * @param {ProcessUpdateOps} ops - Atomic operations to apply
+     * @returns {Promise<Object|null>} Updated process record (post-
+     *   mutation) or null if the process does not exist.
+     */
+    async applyProcessUpdate(processId, ops) {
+        throw new Error('Method applyProcessUpdate() must be implemented');
+    }
+
     /**
      * Find processes by integration and type
      * @param {string} integrationId - Integration ID

package/integrations/repositories/process-repository-mongo.js

@@ -1,5 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { ProcessRepositoryInterface } = require('./process-repository-interface');
+const { validateOps } = require('./process-update-ops-shared');
 
 /**
  * MongoDB Process Repository Adapter
@@ -92,6 +93,77 @@ class ProcessRepositoryMongo extends ProcessRepositoryInterface {
         return this._toPlainObject(process);
     }
 
+    /**
+     * Atomic process update — race-safe counterpart to `update()`.
+     *
+     * Uses `findAndModify` via `$runCommandRaw` so increments, sets, and
+     * pushes land in one server-side write. Contention on the same
+     * document serializes at the MongoDB level; no Node-side read-
+     * modify-write. Returns the post-update document.
+     *
+     * @param {string} processId
+     * @param {import('./process-repository-interface').ProcessUpdateOps} ops
+     * @returns {Promise<Object|null>}
+     */
+    async applyProcessUpdate(processId, ops) {
+        const normalized = validateOps(ops);
+
+        const update = {};
+        const $set = {};
+
+        if (Object.keys(normalized.increment).length > 0) {
+            update.$inc = { ...normalized.increment };
+        }
+        for (const [path, value] of Object.entries(normalized.set)) {
+            $set[path] = value;
+        }
+        if (normalized.newState !== null) {
+            $set.state = normalized.newState;
+        }
+        $set.updatedAt = new Date();
+        update.$set = $set;
+
+        if (Object.keys(normalized.pushSlice).length > 0) {
+            update.$push = {};
+            for (const [path, spec] of Object.entries(normalized.pushSlice)) {
+                update.$push[path] = {
+                    $each: spec.values,
+                    $slice: -spec.keepLast,
+                };
+            }
+        }
+
+        const result = await this.prisma.$runCommandRaw({
+            findAndModify: 'Process',
+            query: { _id: { $oid: processId } },
+            update,
+            new: true,
+        });
+
+        const doc = result && result.value;
+        if (!doc) return null;
+        return this._toPlainObject(this._hydrateRawMongoDoc(doc));
+    }
+
+    /**
+     * Shape a raw Mongo document (as returned by $runCommandRaw) to match
+     * Prisma's `findUnique` output so the existing `_toPlainObject` works
+     * without modification. EJSON round-trips give us `{$oid, $date}` wrappers
+     * that need unwrapping.
+     * @private
+     */
+    _hydrateRawMongoDoc(doc) {
+        const hydrated = { ...doc };
+        if (doc._id) hydrated.id = doc._id.$oid ?? doc._id;
+        for (const field of ['createdAt', 'updatedAt']) {
+            const raw = doc[field];
+            if (raw && typeof raw === 'object' && raw.$date) {
+                hydrated[field] = new Date(raw.$date);
+            }
+        }
+        return hydrated;
+    }
+
     /**
      * Find processes by integration and type
      * @param {string} integrationId - Integration ID

package/integrations/repositories/process-repository-postgres.js

@@ -2,6 +2,7 @@ const { prisma } = require('../../database/prisma');
 const {
     ProcessRepositoryInterface,
 } = require('./process-repository-interface');
+const { validateOps, splitPath } = require('./process-update-ops-shared');
 
 /**
  * PostgreSQL Process Repository Adapter
@@ -108,6 +109,168 @@ class ProcessRepositoryPostgres extends ProcessRepositoryInterface {
         return this._toPlainObject(process);
     }
 
+    /**
+     * Atomic process update — race-safe counterpart to `update()`.
+     *
+     * Compiles the `ProcessUpdateOps` into ONE `UPDATE "Process" ...
+     * RETURNING *` statement with nested `jsonb_set` calls for every
+     * context/results mutation. Postgres applies row-level locking
+     * during UPDATE, so concurrent callers on the same row serialize at
+     * the DB without any read-modify-write in Node.
+     *
+     * Path segments have been regex-validated upstream (see
+     * process-update-ops-shared.js); they are embedded directly into
+     * the SQL string. All values go through positional parameters.
+     *
+     * @param {string} processId
+     * @param {ProcessUpdateOps} ops
+     * @returns {Promise<Object|null>}
+     */
+    async applyProcessUpdate(processId, ops) {
+        const normalized = validateOps(ops);
+        const id = this._convertId(processId);
+
+        // Build the SQL expression for each JSON column. We start each
+        // column's expression from the column itself and wrap it in
+        // jsonb_set(...) calls — one wrap per operation targeting that
+        // column. If no op targets a column, we omit that SET clause so
+        // we don't issue a pointless self-assignment.
+        const params = [];
+        /** @type {(v:unknown)=>string} positional placeholder, 1-indexed */
+        const bind = (v) => {
+            params.push(v);
+            return `$${params.length}`;
+        };
+
+        const columnExpressions = this._buildColumnExpressions(
+            normalized,
+            bind
+        );
+        const setClauses = [];
+        for (const [column, expr] of Object.entries(columnExpressions)) {
+            setClauses.push(`"${column}" = ${expr}`);
+        }
+        if (normalized.newState !== null) {
+            setClauses.push(`"state" = ${bind(normalized.newState)}`);
+        }
+        setClauses.push(`"updatedAt" = NOW()`);
+
+        const idPlaceholder = bind(id);
+        const sql = `
+            UPDATE "Process"
+            SET ${setClauses.join(', ')}
+            WHERE "id" = ${idPlaceholder}
+            RETURNING *
+        `;
+
+        const rows = await this.prisma.$queryRawUnsafe(sql, ...params);
+        if (!rows || rows.length === 0) return null;
+        return this._toPlainObject(rows[0]);
+    }
+
+    /**
+     * Returns a map of column → SQL expression with all jsonb_set wraps
+     * applied. Used only by applyProcessUpdate.
+     * @private
+     */
+    _buildColumnExpressions(ops, bind) {
+        const byColumn = { context: null, results: null };
+
+        // Seed with the column itself (wrapped with COALESCE so that
+        // a NULL column doesn't break jsonb_set).
+        const seed = (col) =>
+            byColumn[col] ??
+            (byColumn[col] = `COALESCE("${col}", '{}'::jsonb)`);
+
+        /**
+         * Postgres `jsonb_set(target, path, value, create_missing=true)`
+         * only creates the LEAF segment if missing — intermediate segments
+         * that don't exist as objects cause the call to return `target`
+         * unchanged (silent no-op). For a path like `context.a.b.c` on a
+         * doc where `context.a` is missing, we'd bail on the write.
+         *
+         * This helper wraps `prev` in a chain of `jsonb_set` calls that
+         * ensure each intermediate prefix path is an object, preserving
+         * its contents if it's already present:
+         *
+         *   ensureParents(prev, ['a','b','c'])
+         *     ⇒ jsonb_set(
+         *          jsonb_set(prev,  '{a}',   COALESCE(prev#>'{a}',   '{}'::jsonb), true),
+         *          '{a,b}', COALESCE(${that}#>'{a,b}', '{}'::jsonb), true)
+         *
+         * The caller then wraps this result with its own `jsonb_set` for
+         * the leaf segment. Depth-1 paths skip this entirely (no parents
+         * to synthesize).
+         */
+        const ensureParents = (prevExpr, segments) => {
+            let cur = prevExpr;
+            for (let i = 1; i < segments.length; i++) {
+                const parentPath = `'{${segments.slice(0, i).join(',')}}'`;
+                cur = `jsonb_set(${cur}, ${parentPath}, COALESCE(${cur} #> ${parentPath}, '{}'::jsonb), true)`;
+            }
+            return cur;
+        };
+
+        const wrapIncrement = (col, segments, delta) => {
+            const textPath = `'{${segments.join(',')}}'`;
+            const jsonbPath = `'{${segments.join(',')}}'`;
+            const prev = seed(col);
+            const guarded = ensureParents(prev, segments);
+            const nextValue = `to_jsonb(COALESCE((${guarded} #>> ${textPath})::numeric, 0) + ${bind(delta)})`;
+            byColumn[col] = `jsonb_set(${guarded}, ${jsonbPath}, ${nextValue}, true)`;
+        };
+
+        const wrapSet = (col, segments, value) => {
+            const jsonbPath = `'{${segments.join(',')}}'`;
+            const prev = seed(col);
+            const guarded = ensureParents(prev, segments);
+            // $n::jsonb — values are serialized to JSON by Prisma when
+            // passed as a parameter, then cast back into jsonb.
+            byColumn[col] = `jsonb_set(${guarded}, ${jsonbPath}, ${bind(JSON.stringify(value))}::jsonb, true)`;
+        };
+
+        const wrapPushSlice = (col, segments, spec) => {
+            const jsonbPath = `'{${segments.join(',')}}'`;
+            const prev = seed(col);
+            const guarded = ensureParents(prev, segments);
+            // Construct the sliced array in a CTE to evaluate `${newArr}`
+            // exactly ONCE (vs. the inline form that Postgres would still
+            // execute correctly but expand three times). Order is
+            // explicitly preserved by `jsonb_agg(... ORDER BY idx)`;
+            // without the ORDER BY, aggregate order is implementation-
+            // defined even with WITH ORDINALITY.
+            const sliced = `(
+                WITH combined AS (
+                    SELECT COALESCE((${guarded} #> ${jsonbPath}), '[]'::jsonb) || ${bind(JSON.stringify(spec.values))}::jsonb AS arr
+                )
+                SELECT COALESCE(jsonb_agg(elem ORDER BY idx), '[]'::jsonb)
+                FROM combined,
+                     jsonb_array_elements((SELECT arr FROM combined)) WITH ORDINALITY AS t(elem, idx)
+                WHERE idx > GREATEST(0, jsonb_array_length((SELECT arr FROM combined)) - ${bind(spec.keepLast)})
+            )`;
+            byColumn[col] = `jsonb_set(${guarded}, ${jsonbPath}, ${sliced}, true)`;
+        };
+
+        for (const [path, delta] of Object.entries(ops.increment)) {
+            const { column, segments } = splitPath(path);
+            wrapIncrement(column, segments, delta);
+        }
+        for (const [path, value] of Object.entries(ops.set)) {
+            const { column, segments } = splitPath(path);
+            wrapSet(column, segments, value);
+        }
+        for (const [path, spec] of Object.entries(ops.pushSlice)) {
+            const { column, segments } = splitPath(path);
+            wrapPushSlice(column, segments, spec);
+        }
+
+        const result = {};
+        for (const [col, expr] of Object.entries(byColumn)) {
+            if (expr !== null) result[col] = expr;
+        }
+        return result;
+    }
+
     /**
      * Find processes by integration and type
      * @param {string} integrationId - Integration ID

package/integrations/repositories/process-update-ops-shared.js

@@ -0,0 +1,112 @@
+/**
+ * Shared helpers for ProcessRepository.applyProcessUpdate() validation.
+ *
+ * These utilities are backend-agnostic: they enforce invariants on the
+ * `ProcessUpdateOps` shape BEFORE each adapter emits any SQL or database
+ * command. Keeping validation here means any bug we fix (e.g. tighter
+ * path regex, size cap) fixes all three adapters in one place.
+ *
+ * Imported by the Postgres, MongoDB, and DocumentDB adapters.
+ */
+
+/**
+ * Allowed dot-path shape. Root must be `context` or `results`, and each
+ * segment after the first must be a JS-identifier-style token. Numeric
+ * segments (array indices) and bracket syntax are intentionally
+ * disallowed — array element mutation is exclusively handled via
+ * `pushSlice`, which targets a whole array at a path.
+ */
+const PATH_REGEX = /^(context|results)(\.[a-zA-Z_][a-zA-Z0-9_]*)+$/;
+
+/**
+ * Normalizes and validates a `ProcessUpdateOps` object. Returns a frozen
+ * copy with defaults applied and every key pre-validated. Throws synchronously
+ * on any shape error so adapters can fail fast before touching the DB.
+ *
+ * @param {Object} ops
+ * @returns {{
+ *   increment: Record<string, number>,
+ *   set: Record<string, unknown>,
+ *   pushSlice: Record<string, { values: unknown[]; keepLast: number }>,
+ *   newState: string|null,
+ * }}
+ */
+function validateOps(ops) {
+    if (!ops || typeof ops !== 'object' || Array.isArray(ops)) {
+        throw new Error('applyProcessUpdate: ops must be an object');
+    }
+
+    const increment = ops.increment || {};
+    const set = ops.set || {};
+    const pushSlice = ops.pushSlice || {};
+    const newState = ops.newState ?? null;
+
+    for (const [path, delta] of Object.entries(increment)) {
+        assertPath(path, 'increment');
+        if (typeof delta !== 'number' || !Number.isFinite(delta)) {
+            throw new Error(
+                `applyProcessUpdate: increment['${path}'] must be a finite number, got ${typeof delta}`
+            );
+        }
+    }
+
+    for (const path of Object.keys(set)) {
+        assertPath(path, 'set');
+    }
+
+    for (const [path, spec] of Object.entries(pushSlice)) {
+        assertPath(path, 'pushSlice');
+        if (
+            !spec ||
+            typeof spec !== 'object' ||
+            !Array.isArray(spec.values) ||
+            typeof spec.keepLast !== 'number' ||
+            !Number.isInteger(spec.keepLast) ||
+            spec.keepLast <= 0
+        ) {
+            throw new Error(
+                `applyProcessUpdate: pushSlice['${path}'] must be { values: [], keepLast: positive integer }`
+            );
+        }
+    }
+
+    if (newState !== null && typeof newState !== 'string') {
+        throw new Error('applyProcessUpdate: newState must be a string');
+    }
+
+    const hasAnyOp =
+        Object.keys(increment).length > 0 ||
+        Object.keys(set).length > 0 ||
+        Object.keys(pushSlice).length > 0 ||
+        newState !== null;
+    if (!hasAnyOp) {
+        throw new Error(
+            'applyProcessUpdate: at least one of increment/set/pushSlice/newState must be provided'
+        );
+    }
+
+    return Object.freeze({ increment, set, pushSlice, newState });
+}
+
+function assertPath(path, opName) {
+    if (!PATH_REGEX.test(path)) {
+        throw new Error(
+            `applyProcessUpdate: invalid path '${path}' in ${opName} (must match ${PATH_REGEX})`
+        );
+    }
+}
+
+/**
+ * Splits a validated path into `{ column, segments }`.
+ * `'context.pagination.pageCount'` → `{ column: 'context', segments: ['pagination', 'pageCount'] }`.
+ */
+function splitPath(path) {
+    const [column, ...segments] = path.split('.');
+    return { column, segments };
+}
+
+module.exports = {
+    PATH_REGEX,
+    validateOps,
+    splitPath,
+};