@friggframework/core 2.0.0--canary.654.42e42b2.0 → 2.0.0--canary.654.3cd4278.0

package/.eslintrc.json

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

package/core/Worker.js

@@ -29,28 +29,14 @@ class Worker {
 
         for (const record of records) {
             await runMessageScope(record, async () => {
-                // Log record entry with SQS-provided attributes useful for tracing
-                // delivery history (ApproximateReceiveCount for retries, etc.).
-                let parsedEvent;
-                try {
-                    parsedEvent = JSON.parse(record.body)?.event;
-                } catch {
-                    parsedEvent = undefined;
-                }
-                console.log(`[Worker] record begin`, {
-                    messageId: record.messageId,
-                    event: parsedEvent,
-                    receiveCount: record.attributes?.ApproximateReceiveCount,
-                });
+                // messageId, receiveCount and the event come from the scope.
+                log.debug('Record started', { eventName: 'frigg.worker.record_started' });
 
                 try {
                     const runParams = JSON.parse(record.body);
                     this._validateParams(runParams);
                     await this._run(runParams, context);
-                    console.log(`[Worker] record success`, {
-                        messageId: record.messageId,
-                        event: runParams?.event,
-                    });
+                    log.debug('Record succeeded', { eventName: 'frigg.worker.record_succeeded' });
                 } catch (error) {
                     if (error.isHaltError) {
                         // HaltError means "discard this message, don't retry".

package/core/create-handler.js

@@ -6,7 +6,7 @@ const { getLogger, toSanitizedSurrogate } = require('../logs');
 const {
     summarizeLambdaEvent,
     toScopeInvocation,
-    toRequestDetails,
+    toRequestInvocation,
 } = require('../logs/summarize-event');
 const {
     runInvocationScope,
@@ -58,6 +58,8 @@ const createHandler = (optionByName = {}) => {
             routeKey: eventSummary.routeKey,
             invocation: toScopeInvocation(eventSummary),
         };
+        // The full redacted summary goes only on the entry and failure records.
+        const requestInvocation = toRequestInvocation(eventSummary);
 
         return runInvocationScope(
             scopeFields,
@@ -65,7 +67,7 @@ const createHandler = (optionByName = {}) => {
                 try {
                     log.info('Handler invoked', {
                         eventName: 'frigg.handler.invoked',
-                        ...toRequestDetails(eventSummary),
+                        invocation: requestInvocation,
                     });
 
                     // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
@@ -86,45 +88,28 @@ const createHandler = (optionByName = {}) => {
                     // Run the Lambda
                     return await method(event, context);
                 } catch (error) {
-                    // Don't leak implementation details to end users.
-                    if (isUserFacingResponse) {
-                        // Allow client-safe errors to pass through with their actual message
-                        if (error.isClientSafe === true) {
-                            const statusCode = error.statusCode || 400;
-                            log.warn('Request rejected', {
-                                eventName: 'frigg.handler.rejected',
-                                statusCode,
-                                error,
-                            });
-                            return {
-                                statusCode,
-                                body: JSON.stringify({
-                                    error: error.message,
-                                }),
-                            };
-                        }
-
-                        log.error('Handler failed', {
-                            eventName: 'frigg.handler.failed',
+                    // Allow client-safe errors to pass through with their actual message
+                    if (isUserFacingResponse && error.isClientSafe === true) {
+                        const statusCode = error.statusCode || 400;
+                        log.warn('Request rejected', {
+                            eventName: 'frigg.handler.rejected',
+                            statusCode,
                             error,
                         });
-
-                        // Hide other errors with generic message
                         return {
-                            statusCode: 500,
+                            statusCode,
                             body: JSON.stringify({
-                                error: 'An Internal Error Occurred',
+                                error: error.message,
                             }),
                         };
                     }
 
-                    // Handle server-to-server responses.
-
-                    // Halt errors succeed and won't be retried, so the halt
-                    // itself is the failure record.
-                    if (error.isHaltError === true) {
+                    // Server-to-server: halt errors succeed and won't be
+                    // retried, so the halt itself is the failure record.
+                    if (!isUserFacingResponse && error.isHaltError === true) {
                         log.error('Handler halted', {
                             eventName: 'frigg.handler.halted',
+                            invocation: requestInvocation,
                             error,
                         });
                         return;
@@ -132,8 +117,20 @@ const createHandler = (optionByName = {}) => {
 
                     log.error('Handler failed', {
                         eventName: 'frigg.handler.failed',
+                        invocation: requestInvocation,
                         error,
                     });
+
+                    // Don't leak implementation details to end users.
+                    if (isUserFacingResponse) {
+                        return {
+                            statusCode: 500,
+                            body: JSON.stringify({
+                                error: 'An Internal Error Occurred',
+                            }),
+                        };
+                    }
+
                     // The Lambda runtime writes a rethrown error itself, so
                     // rethrow a sanitized copy (ADR-048 §6 item 11).
                     throw toSanitizedSurrogate(error);

package/handlers/app-handler-helpers.js

@@ -1,5 +1,6 @@
 const { createHandler } = require('@friggframework/core');
 const { getLogger } = require('../logs');
+const { summarizeExpressRequest } = require('../logs/summarize-event');
 const express = require('express');
 const bodyParser = require('body-parser');
 const cors = require('cors');
@@ -35,6 +36,7 @@ const createApp = (applyMiddleware) => {
             log.error('Request failed', {
                 eventName: 'frigg.http.request_failed',
                 statusCode,
+                invocation: summarizeExpressRequest(req),
                 error: boomError,
             });
             res.status(statusCode).json({ error: 'Internal Server Error' });

package/handlers/backend-utils.js

@@ -273,11 +273,6 @@ const createQueueWorker = (integrationClass) => {
                     return;
                 }
 
-                console.error(
-                    `Error in ${params.event} for ${integrationName}:`,
-                    error
-                );
-
                 // 4xx HTTP errors are permanent — the requester already
                 // attempted token refresh (401) and backoff (429/5xx).
                 // By the time a 4xx reaches here, retrying won't help.

package/handlers/workers/dlq-processor.js

@@ -27,24 +27,22 @@ function extractQueueName(eventSourceARN) {
 // The body can hold credentials, so only its size and digest are logged.
 function describeBody(body) {
     const text = typeof body === 'string' ? body : String(body ?? '');
+    let parsed = true;
+    try {
+        JSON.parse(text);
+    } catch {
+        parsed = false;
+    }
     return {
+        parsed,
         bodyLength: Buffer.byteLength(text),
         bodySha256: crypto.createHash('sha256').update(text).digest('hex'),
     };
 }
 
-function isJson(body) {
-    try {
-        JSON.parse(body);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
 function logRecord(record) {
-    const body = describeBody(record.body);
-    if (!isJson(record.body)) {
+    const { parsed, ...body } = describeBody(record.body);
+    if (!parsed) {
         log.warn('DLQ message body is not JSON', {
             eventName: 'frigg.queue.dlq.body_unparsed',
             ...body,

package/integrations/integration-base.js

@@ -778,7 +778,7 @@ class IntegrationBase {
                 if (this.events[eventName]) {
                     if (typeof handlers[eventName] === 'string') {
                         this.logger.warn(
-                            `Binding handler "${handlers[eventName]}" for event "${eventName}" is ignored because this.events["${eventName}"] was already set`,
+                            'Binding handler is ignored: the event is already set',
                             {
                                 eventName: `${this.logger.name}.extension_handler_shadowed`,
                                 bindingName,

package/logs/__fixtures__/secrets.js

@@ -1,22 +1,59 @@
-// Fake values only. They avoid real provider prefixes so push protection stays quiet.
+// Fake values, generated at load time so secret scanners find no literal in
+// the source. A fixed seed per name keeps every run identical.
+const MIXED = 'BCDFGHJKLMNPQRSTVWXZbcdfghjkmnpqrstvwxz23456789';
+const HEX = '0123456789abcdef';
+
+function seededRandom(name) {
+    let seed = [...name].reduce(
+        (h, c) => Math.imul(h ^ c.charCodeAt(0), 16777619),
+        2166136261
+    );
+    return () => {
+        seed = (seed + 0x6d2b79f5) | 0;
+        let t = Math.imul(seed ^ (seed >>> 15), seed | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+function draw(name, alphabet, length) {
+    const next = seededRandom(name);
+    let out = '';
+    for (let i = 0; i < length; i += 1) {
+        out += alphabet[Math.floor(next() * alphabet.length)];
+    }
+    return out;
+}
+
+// The fixed 'Zq' + 'B7k' start puts upper case, lower case and a digit in every token.
+function fakeToken(name, length = 28) {
+    return `ZqB7k${draw(name, MIXED, length - 5)}`;
+}
+
+const base64url = (value) => Buffer.from(value).toString('base64url');
+
 const SECRETS = Object.freeze({
-    bearer: 'ZqvbLv8tZrQ8kNM5Jq4SRrvrMpRC',
-    apiKeyQuery: 'ZqGkGLq6NLF7vXc7cJTWV4BwX3Ld',
-    friggApiKey: 'Zq4kPQhzWCfJXwXxq7KKSMcpt5bk',
-    cookie: 'ZqKBfkjbBx63hpkzVMfQnw8S3wNS',
-    oauthCode: 'ZqMNW4x97kwsvhwk48BnsXD3JCCB',
-    codeVerifier: 'Zq64cfH4zmrmJmxHpNRG6z8QTdDh',
-    password: 'ZqtkDW2Cbh5kH7SnbK4FGQLRxJLT',
-    clientSecret: 'ZqVbQLw3kDGwxHgrBW32MKLHJgtr',
-    accessToken: 'Zqnw6cnh5ZXpQLB5njSxZKQDPhJc',
-    refreshToken: 'ZqhDdt92NR5cvMsvQ6DFmM2qfJFS',
-    idToken: 'ZqCGFMSgJDmq8NKJ6ZG4vSjVd6Gw',
-    hashword: 'ZqvVPT8cjhxtt9cddR2NqrHSzP66',
-    dbPassword: 'ZqZkGTVwpk38sVnHhKZzWFg9djPW',
-    signature: 'Zq7b634PtgG9Ft4BJ9cjrMTZXjNX',
-    jwt: 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYWtlLXVzZXItMTIzNDUifQ.ZmFrZVNpZ25hdHVyZUZvclRlc3RzT25seQ',
-    hexToken: '9f2c4e7a1b3d5f8e0a6c2b4d7e9f1a3c5b7d9e2f',
-    base64Run: 'QmFzZTY0RmFrZVNlY3JldFZhbHVlRm9yVGVzdHNPbmx5MTIzNDU2Nzg5MA==',
+    bearer: fakeToken('bearer'),
+    apiKeyQuery: fakeToken('apiKeyQuery'),
+    friggApiKey: fakeToken('friggApiKey'),
+    cookie: fakeToken('cookie'),
+    oauthCode: fakeToken('oauthCode'),
+    codeVerifier: fakeToken('codeVerifier'),
+    password: fakeToken('password'),
+    clientSecret: fakeToken('clientSecret'),
+    accessToken: fakeToken('accessToken'),
+    refreshToken: fakeToken('refreshToken'),
+    idToken: fakeToken('idToken'),
+    hashword: fakeToken('hashword'),
+    dbPassword: fakeToken('dbPassword'),
+    signature: fakeToken('signature'),
+    jwt: [
+        base64url(JSON.stringify({ alg: 'HS256' })),
+        base64url(JSON.stringify({ sub: `fake-${draw('jwtSub', MIXED, 8)}` })),
+        base64url(draw('jwtSig', MIXED, 24)),
+    ].join('.'),
+    hexToken: draw('hexToken', HEX, 40),
+    base64Run: Buffer.from(draw('base64Run', MIXED, 42)).toString('base64'),
 });
 
-module.exports = { SECRETS };
+module.exports = { SECRETS, fakeToken };

package/logs/__fixtures__/vectors.js

@@ -1,14 +1,14 @@
 // ADR-048 §14 redaction vectors. Each vector is one log call that carries
 // secrets; the suite asserts that no 8-char window of them reaches a record.
-const { SECRETS: S } = require('./secrets');
+const { SECRETS: S, fakeToken } = require('./secrets');
 const { httpApiV2Event, restV1Event, sqsEvent } = require('./events');
 const { summarizeLambdaEvent } = require('../summarize-event');
 
 const secretUrl = `https://api.example.com/v1/items?api_key=${S.apiKeyQuery}`;
-const SIGNATURE_VALUE = 'fakeSgnValue2Gh9Tc5Wp7LmQx3';
+const SIGNATURE_VALUE = fakeToken('signatureValue', 27);
 
 // Built by concatenation so push protection does not match the prefixes.
-const TOKEN_TAIL = 'ZqPr3fixTail8Hn2Kd8Ws1Yc6';
+const TOKEN_TAIL = fakeToken('prefixTail', 25);
 const PREFIXED_TOKENS = [
     'sk_' + 'live_' + TOKEN_TAIL,
     'whsec' + '_' + TOKEN_TAIL,

package/logs/debug-shims.js

@@ -3,8 +3,7 @@ const { getLogger } = require('./logger');
 const { getContext } = require('./context');
 const {
     summarizeLambdaEvent,
-    toScopeInvocation,
-    toRequestDetails,
+    toRequestInvocation,
 } = require('./summarize-event');
 
 // Deprecated. Kept for one major version; use getLogger or this.logger.
@@ -32,10 +31,8 @@ function initDebugLog(...initMessages) {
     const log = legacy();
     if (!log.isLevelEnabled('DEBUG')) return;
     const event = initMessages.find((m) => m && typeof m === 'object');
-    const summary = summarizeLambdaEvent(event);
     log.debug('Debug log initialized', {
-        invocation: toScopeInvocation(summary),
-        ...toRequestDetails(summary),
+        invocation: toRequestInvocation(summarizeLambdaEvent(event)),
     });
 }
 

package/logs/record.js

@@ -78,6 +78,29 @@ function buildMessage(message, callSite) {
     return '[non-string message]';
 }
 
+const INVOCATION_KEY = 'invocation';
+
+function isPlainObject(value) {
+    return (
+        value !== null &&
+        typeof value === 'object' &&
+        Object.getPrototypeOf(value) === Object.prototype
+    );
+}
+
+// A boundary adds request detail to the scope's invocation; scope keys win.
+function extendInvocation(scoped, detail, dropped) {
+    const merged = { ...scoped };
+    for (const [key, value] of Object.entries(detail)) {
+        if (!Object.prototype.hasOwnProperty.call(scoped, key)) {
+            merged[key] = value;
+        } else if (JSON.stringify(scoped[key]) !== JSON.stringify(value)) {
+            dropped.add(`${INVOCATION_KEY}.${key}`);
+        }
+    }
+    return merged;
+}
+
 function traceFields(spanContext) {
     if (
         !spanContext ||
@@ -135,7 +158,8 @@ function buildRecord({
                 OWNED_KEYS.has(key) ||
                 RESERVED_KEYS.has(key) ||
                 (dropPayloads && PAYLOAD_KEYS.has(key)) ||
-                Object.prototype.hasOwnProperty.call(record, key)
+                (Object.prototype.hasOwnProperty.call(record, key) &&
+                    !canExtendInvocation(key, value))
             ) {
                 dropped.add(key);
                 continue;
@@ -149,10 +173,18 @@ function buildRecord({
             const value =
                 key === 'error' ? serializeError(accepted[key]) : safe?.[key];
             if (value === undefined || value === null) continue;
+            if (key === INVOCATION_KEY && isPlainObject(record[key])) {
+                record[key] = extendInvocation(record[key], value, dropped);
+                continue;
+            }
             record[key] = value;
             if (isCallSite) callSiteKeys.push(key);
         }
     };
+    const canExtendInvocation = (key, value) =>
+        key === INVOCATION_KEY &&
+        isPlainObject(record[key]) &&
+        isPlainObject(value);
     place(readFields(scope), false);
     place(readFields(bindings), false);
     place(callSite, true);

package/logs/redact.js

@@ -56,7 +56,9 @@ const MAX_SCRUB_INPUT = 65536;
 const URL_IN_TEXT = /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"'<>`]+/g;
 const URL_TRAILING_PUNCT = /[.,;:!?)\]}]+$/;
 const ABSOLUTE_URL = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
-const ROOT_SLASH = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*\//;
+const RAW_ABSOLUTE_PATH = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*([^?#]*)/;
+const RAW_RELATIVE_PATH = /^[^?#]*/;
+const PATH_TOKEN_SEGMENT = /^[A-Za-z0-9_.~-]{20,}$/;
 const PREFIXED_TOKEN =
     /(?<![A-Za-z0-9_-])(?:(?:sk|rk)_(?:live|test)_|whsec_|xox[abprs]-|gh[opsu]_|github_pat_|shp(?:at|ss)_|glpat-|npm_)[A-Za-z0-9_-]{16,}|\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
 const JWT = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g;
@@ -196,11 +198,18 @@ function redactHash(hash) {
     return scrubTokens(hash);
 }
 
+// A long segment mixing upper case, lower case and digits is an opaque
+// token (webhook secrets live in paths); hex ids and UUIDs lack one class.
+function redactPathSegment(segment) {
+    if (PATH_TOKEN_SEGMENT.test(segment) && hasMixedClasses(segment)) {
+        return redacted(segment);
+    }
+    return scrubTokens(segment, { segment: true });
+}
+
+// The raw path, not URL#pathname, which percent-encodes `{proxy+}`.
 function redactPath(pathname) {
-    return pathname
-        .split('/')
-        .map((segment) => scrubTokens(segment, { segment: true }))
-        .join('/');
+    return pathname.split('/').map(redactPathSegment).join('/');
 }
 
 function redactUrlFallback(raw) {
@@ -221,16 +230,15 @@ function redactUrl(url) {
     try {
         if (ABSOLUTE_URL.test(raw)) {
             const u = new URL(raw);
-            const path =
-                u.pathname === '/' && !ROOT_SLASH.test(raw) ? '' : u.pathname;
+            const path = raw.match(RAW_ABSOLUTE_PATH)[1];
             return `${u.protocol}//${u.host}${redactPath(path)}${redactParams(
                 u.search,
                 '?'
             )}${redactHash(u.hash)}`;
         }
         if (raw.startsWith('/')) {
-            const u = new URL(raw, 'http://relative.invalid');
-            return `${redactPath(u.pathname)}${redactParams(
+            const u = new URL(raw, 'https://relative.invalid');
+            return `${redactPath(raw.match(RAW_RELATIVE_PATH)[0])}${redactParams(
                 u.search,
                 '?'
             )}${redactHash(u.hash)}`;

package/logs/summarize-event.js

@@ -1,3 +1,5 @@
+const { redactUrl } = require('./redact');
+
 // Best-effort extraction of the logical event/processId/integrationId from a
 // JSON message body. Used only for log correlation. Never throws.
 function summarizeMessageBody(bodyStr) {
@@ -118,19 +120,43 @@ function toScopeInvocation(summary) {
     return { source: summary.source };
 }
 
-// Per-request detail for the one entry record, never for the scope.
+// Per-request detail for the entry and failure records, never for the
+// scope. A raw path can hold a token, so it goes through redactUrl.
 function toRequestDetails(summary) {
     if (!summary || summary.source !== 'http') return {};
     return {
-        path: summary.path,
+        path: redactUrl(summary.path ?? ''),
         queryKeys: summary.queryKeys ?? [],
         headerNames: summary.headerNames ?? [],
     };
 }
 
+// The full redacted request summary (ADR-048 §6: it goes under `invocation`).
+function toRequestInvocation(summary) {
+    return { ...toScopeInvocation(summary), ...toRequestDetails(summary) };
+}
+
+// The same shape from an express request, for the express error boundary.
+function summarizeExpressRequest(req) {
+    try {
+        if (!req || typeof req !== 'object') return { source: 'http' };
+        return {
+            source: 'http',
+            method: req.method,
+            path: redactUrl(req.path ?? ''),
+            queryKeys: objectKeys(req.query),
+            headerNames: unique(objectKeys(req.headers).map((name) => name.toLowerCase())),
+        };
+    } catch {
+        return { source: 'http' };
+    }
+}
+
 module.exports = {
     summarizeLambdaEvent,
     summarizeMessageBody,
     toScopeInvocation,
     toRequestDetails,
+    toRequestInvocation,
+    summarizeExpressRequest,
 };

package/modules/requester/oauth-2.js

@@ -357,7 +357,7 @@ class OAuth2Requester extends Requester {
                 eventName: `${this.logger.name}.token_refresh_failed`,
                 statusCode:
                     error?.statusCode ?? error?.status ?? error?.response?.status,
-                error,
+                reason: error?.message,
             });
 
             if (!this._isDefinitiveAuthRejection(error)) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.654.42e42b2.0",
+    "version": "2.0.0--canary.654.3cd4278.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.42e42b2.0",
-        "@friggframework/prettier-config": "2.0.0--canary.654.42e42b2.0",
-        "@friggframework/test": "2.0.0--canary.654.42e42b2.0",
+        "@friggframework/eslint-config": "2.0.0--canary.654.3cd4278.0",
+        "@friggframework/prettier-config": "2.0.0--canary.654.3cd4278.0",
+        "@friggframework/test": "2.0.0--canary.654.3cd4278.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": "42e42b2b48e90e9b46ffe6bcf009150a66a010cd"
+    "gitHead": "3cd42784313ae866c499d7c7549b7c28e39d3045"
 }

package/user/repositories/user-repository-documentdb.js

@@ -148,13 +148,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         // Defensive check: verify document was found after insert
         if (!created) {
-            log.error('User not found after insert', {
-                eventName: 'frigg.user.not_found_after_insert',
-                insertedId: fromObjectId(insertedId),
-                paramKeys: Object.keys(params),
-            });
             throw new Error(
-                'Failed to create individual user: Document not found after insert. ' +
+                `Failed to create individual user: Document not found after insert (insertedId ${fromObjectId(insertedId)}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -192,13 +187,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         // Defensive check: verify document was found after insert
         if (!created) {
-            log.error('Organization user not found after insert', {
-                eventName: 'frigg.user.organization_not_found_after_insert',
-                insertedId: fromObjectId(insertedId),
-                paramKeys: Object.keys(params),
-            });
             throw new Error(
-                'Failed to create organization user: Document not found after insert. ' +
+                `Failed to create organization user: Document not found after insert (insertedId ${fromObjectId(insertedId)}). ` +
                     'This indicates a database consistency issue.'
             );
         }
@@ -284,7 +274,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
         // Defensive check: verify document was found after update
         if (!updated) {
             throw new Error(
-                `Failed to update user ${userId}: not found after update`
+                'Failed to update individual user: Document not found after update. ' +
+                    'This indicates a database consistency issue.'
             );
         }
 
@@ -317,7 +308,8 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
 
         if (!updated) {
             throw new Error(
-                `Failed to update user ${userId}: not found after update`
+                'Failed to update organization user: Document not found after update. ' +
+                    'This indicates a database consistency issue.'
             );
         }