@friggframework/core 2.0.0--canary.580.4487187.0 → 2.0.0--canary.580.235db2b.0

package/CLAUDE.md

@@ -212,6 +212,14 @@ packages/core/
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
 - `integration-mapping-repository-*.js` - Mapping data persistence
+- `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
+  pushes through each backend's native atomic primitive (PostgreSQL
+  `jsonb_set` / MongoDB `$inc`/`$set`/`$push`). Use this method any time
+  multiple queue workers may concurrently mutate the same Process row
+  (counters, flags, error history). The legacy `update(id, patch)`
+  remains available but is clobber-prone under concurrency.
 
 **Integration developers extend IntegrationBase**:
 

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,
+};

package/integrations/use-cases/update-process-metrics.js

@@ -1,37 +1,28 @@
-/** 
- TODO:
- This implementation contains a race condition in the `execute` method. When multiple concurrent processes call this method on the same process record, they'll each read the current state, modify it independently, and then save - potentially overwriting each other's changes.
-
-For example:
-```
-Thread 1: reads process with totalSynced=100
-Thread 2: reads process with totalSynced=100
-Thread 1: adds 50 → writes totalSynced=150
-Thread 2: adds 30 → writes totalSynced=130 (overwrites Thread 1's update!)
-```
-
-Consider implementing one of these patterns:
-1. Database transactions with row locking
-2. Optimistic concurrency control with version numbers
-3. Atomic update operations (e.g., `$inc` in MongoDB)
-4. A FIFO queue for process updates (as described in the PROCESS_MANAGEMENT_QUEUE_SPEC.md)
-
-The current approach will lead to lost updates and inconsistent metrics during concurrent processing.
-
- */
-
 /**
  * UpdateProcessMetrics Use Case
  *
- * Updates process metrics, calculates aggregates, and computes estimated completion time.
- * Optionally broadcasts progress via WebSocket service if provided.
+ * Updates process metrics atomically via
+ * `processRepository.applyProcessUpdate`. This is the race-safe
+ * replacement for the original read-modify-write implementation — the
+ * long-standing TODO about lost updates under concurrent writers is
+ * now resolved.
+ *
+ * Split into two phases:
  *
- * Design Philosophy:
- * - Metrics are cumulative (add to existing counts)
- * - Performance metrics calculated automatically (duration, records/sec)
- * - ETA computed based on current progress
- * - Error history limited to last 100 entries
- * - WebSocket broadcasting is optional (DI pattern)
+ *   1. Atomic phase — counters and bounded error history. Uses
+ *      $inc / $push+$slice (Mongo/DocumentDB) or jsonb_set with
+ *      arithmetic expressions (Postgres) in a single UPDATE ... RETURNING
+ *      so concurrent callers serialize at the DB layer.
+ *
+ *   2. Derived-fields phase — duration, recordsPerSecond,
+ *      estimatedCompletion. Computed from the post-atomic snapshot and
+ *      written via the legacy (non-atomic) `update()` method.
+ *      Intentionally best-effort: under concurrent writers they reflect
+ *      "whichever handler wrote last" — the same semantics they had
+ *      before and all they've ever guaranteed. Preserved for backward
+ *      compatibility with consumers (UI, WebSocket listeners).
+ *
+ * Optionally broadcasts progress via WebSocket service if provided.
  *
  * @example
  * const updateMetrics = new UpdateProcessMetrics({ processRepository, websocketService });
@@ -60,15 +51,14 @@ class UpdateProcessMetrics {
      * Execute the use case to update process metrics
      * @param {string} processId - Process ID to update
      * @param {Object} metricsUpdate - Metrics to add/update
-     * @param {number} [metricsUpdate.processed=0] - Number of records processed in this batch
-     * @param {number} [metricsUpdate.success=0] - Number of successful records
-     * @param {number} [metricsUpdate.errors=0] - Number of failed records
+     * @param {number} [metricsUpdate.processed=0] - Records processed in this batch
+     * @param {number} [metricsUpdate.success=0] - Successful records
+     * @param {number} [metricsUpdate.errors=0] - Failed records
      * @param {Array} [metricsUpdate.errorDetails=[]] - Error details array
      * @returns {Promise<Object>} Updated process record
      * @throws {Error} If process not found or update fails
      */
     async execute(processId, metricsUpdate) {
-        // Validate inputs
         if (!processId || typeof processId !== 'string') {
             throw new Error('processId must be a non-empty string');
         }
@@ -76,87 +66,103 @@ class UpdateProcessMetrics {
             throw new Error('metricsUpdate must be an object');
         }
 
-        // Retrieve current process
-        const process = await this.processRepository.findById(processId);
-        if (!process) {
-            throw new Error(`Process not found: ${processId}`);
-        }
-
-        // Get current context and results
-        const context = process.context || {};
-        const results = process.results || { aggregateData: {} };
-
-        // Initialize nested objects if not present
-        if (!results.aggregateData) {
-            results.aggregateData = {};
-        }
-
-        // Update context counters (cumulative)
-        context.processedRecords =
-            (context.processedRecords || 0) + (metricsUpdate.processed || 0);
+        // Phase 1: atomic increments + bounded error history.
+        const increment = {};
+        const processed = metricsUpdate.processed || 0;
+        const success = metricsUpdate.success || 0;
+        const errors = metricsUpdate.errors || 0;
+        if (processed) increment['context.processedRecords'] = processed;
+        if (success) increment['results.aggregateData.totalSynced'] = success;
+        if (errors) increment['results.aggregateData.totalFailed'] = errors;
 
-        // Update results aggregates (cumulative)
-        results.aggregateData.totalSynced =
-            (results.aggregateData.totalSynced || 0) +
-            (metricsUpdate.success || 0);
-        results.aggregateData.totalFailed =
-            (results.aggregateData.totalFailed || 0) +
-            (metricsUpdate.errors || 0);
-
-        // Append error details (limited to last 100)
+        const pushSlice = {};
         if (
-            metricsUpdate.errorDetails &&
+            Array.isArray(metricsUpdate.errorDetails) &&
             metricsUpdate.errorDetails.length > 0
         ) {
-            results.aggregateData.errors = [
-                ...(results.aggregateData.errors || []),
-                ...metricsUpdate.errorDetails,
-            ].slice(-100); // Keep only last 100 errors
+            pushSlice['results.aggregateData.errors'] = {
+                values: metricsUpdate.errorDetails,
+                keepLast: 100,
+            };
         }
 
-        // Calculate performance metrics
-        const startTime = new Date(context.startTime || process.createdAt);
-        const elapsed = Date.now() - startTime.getTime();
-        results.aggregateData.duration = elapsed;
-
-        if (elapsed > 0 && context.processedRecords > 0) {
-            results.aggregateData.recordsPerSecond =
-                context.processedRecords / (elapsed / 1000);
-        } else {
-            results.aggregateData.recordsPerSecond = 0;
-        }
+        const hasAtomicWork =
+            Object.keys(increment).length > 0 ||
+            Object.keys(pushSlice).length > 0;
 
-        // Calculate ETA if we know total
-        if (context.totalRecords > 0 && context.processedRecords > 0) {
-            const remaining = context.totalRecords - context.processedRecords;
-            if (results.aggregateData.recordsPerSecond > 0) {
-                const etaMs =
-                    (remaining / results.aggregateData.recordsPerSecond) * 1000;
-                const eta = new Date(Date.now() + etaMs);
-                context.estimatedCompletion = eta.toISOString();
-            }
-        }
-
-        // Prepare updates
-        const updates = {
-            context,
-            results,
-        };
-
-        // Persist updates
         let updatedProcess;
         try {
-            updatedProcess = await this.processRepository.update(
-                processId,
-                updates
-            );
+            if (hasAtomicWork) {
+                updatedProcess = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { increment, pushSlice }
+                );
+            } else {
+                // All-zero update (e.g., empty batch) — nothing to persist;
+                // just read current state for the derived-fields pass.
+                updatedProcess = await this.processRepository.findById(
+                    processId
+                );
+            }
         } catch (error) {
             throw new Error(
                 `Failed to update process metrics: ${error.message}`
             );
         }
 
-        // Broadcast progress via WebSocket (if service provided)
+        if (!updatedProcess) {
+            throw new Error(`Process not found: ${processId}`);
+        }
+
+        // Phase 2: derived metrics (non-atomic, best-effort). Preserved
+        // for backward compatibility — these were always stale under
+        // concurrent writers even before this refactor.
+        const context = updatedProcess.context || {};
+        const results = updatedProcess.results || { aggregateData: {} };
+        if (!results.aggregateData) results.aggregateData = {};
+
+        if (context.processedRecords > 0 || context.totalRecords > 0) {
+            const startTime = new Date(
+                context.startTime || updatedProcess.createdAt
+            );
+            const elapsed = Date.now() - startTime.getTime();
+            results.aggregateData.duration = elapsed;
+
+            if (elapsed > 0 && context.processedRecords > 0) {
+                results.aggregateData.recordsPerSecond =
+                    context.processedRecords / (elapsed / 1000);
+            } else {
+                results.aggregateData.recordsPerSecond = 0;
+            }
+
+            if (context.totalRecords > 0 && context.processedRecords > 0) {
+                const remaining =
+                    context.totalRecords - context.processedRecords;
+                if (results.aggregateData.recordsPerSecond > 0) {
+                    const etaMs =
+                        (remaining / results.aggregateData.recordsPerSecond) *
+                        1000;
+                    const eta = new Date(Date.now() + etaMs);
+                    context.estimatedCompletion = eta.toISOString();
+                }
+            }
+
+            try {
+                updatedProcess = await this.processRepository.update(
+                    processId,
+                    { context, results }
+                );
+            } catch (error) {
+                // Derived-field write failures are NON-FATAL — atomic
+                // counters from phase 1 already landed. Log and return the
+                // post-atomic snapshot.
+                console.error(
+                    '[UpdateProcessMetrics] derived-fields write failed (non-fatal):',
+                    error.message
+                );
+            }
+        }
+
         if (this.websocketService) {
             await this._broadcastProgress(updatedProcess);
         }
@@ -167,7 +173,6 @@ class UpdateProcessMetrics {
     /**
      * Broadcast progress update via WebSocket
      * @private
-     * @param {Object} process - Updated process record
      */
     async _broadcastProgress(process) {
         try {
@@ -192,7 +197,6 @@ class UpdateProcessMetrics {
                 },
             });
         } catch (error) {
-            // Log but don't fail the update if WebSocket broadcast fails
             console.error('Failed to broadcast process progress:', error);
         }
     }

package/integrations/use-cases/update-process-state.js

@@ -54,30 +54,69 @@ class UpdateProcessState {
             throw new Error('contextUpdates must be an object');
         }
 
-        // Retrieve current process
-        const process = await this.processRepository.findById(processId);
-        if (!process) {
-            throw new Error(`Process not found: ${processId}`);
-        }
+        // Route through the atomic path when the repo supports it AND we
+        // have context keys to set. The atomic path writes the state
+        // column + the context field-sets in one DB round trip without
+        // read-modify-write, so a concurrent counter bump from
+        // UpdateProcessMetrics can't clobber our flags (e.g. `fetchDone`)
+        // or vice versa.
+        //
+        // Each context update key becomes a `set` at path
+        // `context.<key>` — matching the prior semantics of a shallow
+        // top-level merge (sub-objects were and still are replaced
+        // whole, not deep-merged).
+        const hasContextKeys =
+            contextUpdates && Object.keys(contextUpdates).length > 0;
 
-        // Prepare updates
-        const updates = {
-            state: newState,
-        };
-
-        // Merge context updates if provided
-        if (contextUpdates && Object.keys(contextUpdates).length > 0) {
-            updates.context = {
-                ...process.context,
-                ...contextUpdates,
-            };
+        if (
+            hasContextKeys &&
+            typeof this.processRepository.applyProcessUpdate === 'function'
+        ) {
+            const set = {};
+            for (const [key, value] of Object.entries(contextUpdates)) {
+                set[`context.${key}`] = value;
+            }
+            try {
+                const updated = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { set, newState }
+                );
+                if (!updated) {
+                    throw new Error(`Process not found: ${processId}`);
+                }
+                return updated;
+            } catch (error) {
+                throw new Error(
+                    `Failed to update process state: ${error.message}`
+                );
+            }
         }
 
-        // Persist updates
+        // Legacy path (no contextUpdates or repo lacks applyProcessUpdate):
+        // preserve the original read-merge-write semantics for backward
+        // compatibility with any custom repos. Wrap the full read+write
+        // in try/catch so a findById error surfaces under the same
+        // "Failed to update process state" message as a write failure.
         try {
-            const updatedProcess = await this.processRepository.update(processId, updates);
-            return updatedProcess;
+            const process = await this.processRepository.findById(processId);
+            if (!process) {
+                throw new Error(`Process not found: ${processId}`);
+            }
+
+            const updates = { state: newState };
+            if (hasContextKeys) {
+                updates.context = {
+                    ...process.context,
+                    ...contextUpdates,
+                };
+            }
+
+            return await this.processRepository.update(processId, updates);
         } catch (error) {
+            // Re-throw "Process not found" as-is; wrap other errors.
+            if (error.message && error.message.startsWith('Process not found')) {
+                throw error;
+            }
             throw new Error(`Failed to update process state: ${error.message}`);
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.580.4487187.0",
+    "version": "2.0.0--canary.580.235db2b.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.580.4487187.0",
-        "@friggframework/prettier-config": "2.0.0--canary.580.4487187.0",
-        "@friggframework/test": "2.0.0--canary.580.4487187.0",
+        "@friggframework/eslint-config": "2.0.0--canary.580.235db2b.0",
+        "@friggframework/prettier-config": "2.0.0--canary.580.235db2b.0",
+        "@friggframework/test": "2.0.0--canary.580.235db2b.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "44871876975b9e507ed635e9df4075b2215685d1"
+    "gitHead": "235db2bdc62c375401507fe546c3b77d8cbc5bc7"
 }