@open-mercato/core 0.6.7-develop.6677.1.beabb7ca12 → 0.6.7-develop.6685.1.77c0a5591b

package/src/modules/payment_gateways/lib/capture-ledger.ts

@@ -0,0 +1,260 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { UnifiedPaymentStatus } from '@open-mercato/shared/modules/payment_gateways/types'
+import { GatewayPaymentOperation, GatewayTransaction } from '../data/entities'
+
+type Scope = { organizationId: string; tenantId: string }
+
+const AMOUNT_SCALE = 4
+const AMOUNT_UNITS_PER_WHOLE = 10n ** BigInt(AMOUNT_SCALE)
+const DECIMAL_PATTERN = /^(-?)(\d*)(?:\.(\d*))?$/
+
+/**
+ * Money in this module lives in `numeric(18,4)` columns and is read back as strings. Every
+ * comparison and every sum runs on integer minor units (1 unit = 10^-4) so partial captures
+ * never accumulate floating-point drift. Extra precision beyond four decimals is rounded
+ * half-up, matching what Postgres would store in the column anyway.
+ */
+export function parseAmountUnits(value: string | number | null | undefined): bigint {
+  if (value === null || value === undefined) return 0n
+  const text = typeof value === 'number' ? value.toFixed(AMOUNT_SCALE) : value.trim()
+  const match = DECIMAL_PATTERN.exec(text)
+  const whole = match?.[2] ?? ''
+  const fraction = match?.[3] ?? ''
+  if (!match || (whole === '' && fraction === '')) {
+    throw new Error(`[internal] Unsupported gateway amount value: ${String(value)}`)
+  }
+  const keptFraction = fraction.slice(0, AMOUNT_SCALE).padEnd(AMOUNT_SCALE, '0')
+  const nextDigit = fraction.charAt(AMOUNT_SCALE)
+  let units = BigInt(whole === '' ? '0' : whole) * AMOUNT_UNITS_PER_WHOLE + BigInt(keptFraction)
+  if (nextDigit !== '' && Number(nextDigit) >= 5) units += 1n
+  return match[1] === '-' ? -units : units
+}
+
+export function formatAmountUnits(units: bigint): string {
+  const negative = units < 0n
+  const absolute = negative ? -units : units
+  const fraction = (absolute % AMOUNT_UNITS_PER_WHOLE).toString().padStart(AMOUNT_SCALE, '0')
+  return `${negative ? '-' : ''}${absolute / AMOUNT_UNITS_PER_WHOLE}.${fraction}`
+}
+
+function formatAmountLabel(units: bigint): string {
+  return formatAmountUnits(units).replace(/\.?0+$/, '')
+}
+
+function captureConflict(code: string, message: string): CrudHttpError {
+  return new CrudHttpError(409, { error: message, code })
+}
+
+export type CaptureAmounts = {
+  authorizedUnits: bigint
+  capturedUnits: bigint
+  remainingUnits: bigint
+  requestedUnits: bigint
+}
+
+/**
+ * Resolves what a capture request means for the transaction's running total. An omitted
+ * amount captures everything that is still authorized, not the original full amount.
+ */
+export function resolveCaptureAmounts(transaction: GatewayTransaction, amount: number | undefined): CaptureAmounts {
+  const authorizedUnits = parseAmountUnits(transaction.amount)
+  const capturedUnits = parseAmountUnits(transaction.capturedAmount)
+  const remainingUnits = authorizedUnits - capturedUnits
+  return {
+    authorizedUnits,
+    capturedUnits,
+    remainingUnits,
+    requestedUnits: amount === undefined ? remainingUnits : parseAmountUnits(amount),
+  }
+}
+
+/**
+ * Rejects a capture whose amount would push the captured-to-date total past the authorized
+ * amount. This is the cumulative ceiling: each individual request may look small, but the
+ * sum of all captures against one authorization can never exceed it (#4487).
+ */
+export function assertCaptureWithinRemaining(
+  transaction: GatewayTransaction,
+  amount: number | undefined,
+): CaptureAmounts {
+  const amounts = resolveCaptureAmounts(transaction, amount)
+  if (amounts.remainingUnits <= 0n) {
+    throw captureConflict(
+      'payment_capture_ceiling_exceeded',
+      `Transaction is already fully captured (${formatAmountLabel(amounts.capturedUnits)} of ${formatAmountLabel(amounts.authorizedUnits)})`,
+    )
+  }
+  if (amounts.requestedUnits <= 0n) {
+    throw captureConflict('payment_capture_amount_invalid', 'Capture amount must be greater than zero')
+  }
+  if (amounts.requestedUnits > amounts.remainingUnits) {
+    throw captureConflict(
+      'payment_capture_ceiling_exceeded',
+      `Capture amount ${formatAmountLabel(amounts.requestedUnits)} exceeds the ${formatAmountLabel(amounts.remainingUnits)} still capturable on authorized amount ${formatAmountLabel(amounts.authorizedUnits)} (already captured ${formatAmountLabel(amounts.capturedUnits)})`,
+    )
+  }
+  return amounts
+}
+
+/**
+ * Claims the requested slice of the authorized amount before the provider is called, so two
+ * concurrent captures can never both charge. The increment is a compare-and-swap on the
+ * previous captured-to-date value: whoever loses it never reaches the adapter. The reserved
+ * amount is stamped on the operation row in the same transaction, so a retry of the same
+ * operation id reuses its reservation instead of reserving twice.
+ */
+export async function reserveCaptureAmount(em: EntityManager, input: {
+  transaction: GatewayTransaction
+  operation: GatewayPaymentOperation
+  amount: number | undefined
+  scope: Scope
+}): Promise<bigint> {
+  if (input.operation.reservedAmount !== null && input.operation.reservedAmount !== undefined) {
+    return parseAmountUnits(input.operation.reservedAmount)
+  }
+  const amounts = assertCaptureWithinRemaining(input.transaction, input.amount)
+  const previousCapturedAmount = input.transaction.capturedAmount
+  const reservedAmount = formatAmountUnits(amounts.requestedUnits)
+  const nextCapturedAmount = formatAmountUnits(amounts.capturedUnits + amounts.requestedUnits)
+
+  await em.transactional(async (tx) => {
+    const reserved = await tx.nativeUpdate(
+      GatewayTransaction,
+      {
+        id: input.transaction.id,
+        organizationId: input.scope.organizationId,
+        tenantId: input.scope.tenantId,
+        deletedAt: null,
+        capturedAmount: previousCapturedAmount,
+      },
+      { capturedAmount: nextCapturedAmount, updatedAt: new Date() },
+    )
+    if (reserved !== 1) {
+      throw captureConflict(
+        'payment_capture_reservation_conflict',
+        'This transaction changed while the capture amount was being reserved; re-read it and retry with the remaining amount',
+      )
+    }
+    const stamped = await tx.nativeUpdate(
+      GatewayPaymentOperation,
+      {
+        id: input.operation.id,
+        organizationId: input.scope.organizationId,
+        tenantId: input.scope.tenantId,
+        reservedAmount: null,
+      },
+      { reservedAmount, updatedAt: new Date() },
+    )
+    if (stamped !== 1) {
+      throw captureConflict(
+        'payment_capture_reservation_conflict',
+        'Capture reservation could not be recorded for this operation',
+      )
+    }
+  })
+
+  Object.assign(input.operation, { reservedAmount })
+  return amounts.requestedUnits
+}
+
+/**
+ * Reconciles the reservation with what the provider actually captured. Runs on the transaction
+ * instance loaded inside the completion transaction, so the adjustment commits together with
+ * the operation result.
+ */
+export function settleCapturedAmount(
+  transaction: GatewayTransaction,
+  reservedUnits: bigint,
+  capturedAmount: number | undefined,
+): void {
+  const actualUnits = typeof capturedAmount === 'number' && Number.isFinite(capturedAmount) && capturedAmount >= 0
+    ? parseAmountUnits(capturedAmount)
+    : reservedUnits
+  if (actualUnits === reservedUnits) return
+  const settledUnits = parseAmountUnits(transaction.capturedAmount) - reservedUnits + actualUnits
+  transaction.capturedAmount = formatAmountUnits(settledUnits < 0n ? 0n : settledUnits)
+}
+
+/**
+ * Keeps the ledger honest for captures that happened outside the capture endpoint. A webhook or a
+ * status poll reports money that already moved but carries no captured amount, so only `captured`
+ * — the provider saying the whole authorization was taken — can be translated into a number: the
+ * full amount. The ledger is raised, never lowered, so an already recorded capture survives.
+ * `partially_captured` carries no recoverable amount, so it is left alone and the remainder stays
+ * capturable.
+ */
+export function alignCapturedAmountWithStatus(
+  transaction: GatewayTransaction,
+  status: UnifiedPaymentStatus,
+): void {
+  if (status !== 'captured') return
+  const authorizedUnits = parseAmountUnits(transaction.amount)
+  if (parseAmountUnits(transaction.capturedAmount) >= authorizedUnits) return
+  transaction.capturedAmount = formatAmountUnits(authorizedUnits)
+}
+
+/**
+ * Gives the reserved slice back after a failed provider call. Both writes share one
+ * transaction, so a partial release is impossible: either the amount becomes capturable again
+ * and the operation stops holding it, or the reservation stays outstanding. Returning `false`
+ * means the reservation is still held — the conservative outcome when it is unknown whether
+ * the provider took the money.
+ */
+export async function releaseCaptureAmount(em: EntityManager, input: {
+  transactionId: string
+  operation: GatewayPaymentOperation
+  reservedUnits: bigint
+  scope: Scope
+}): Promise<boolean> {
+  const reservedAmount = formatAmountUnits(input.reservedUnits)
+  try {
+    return await em.transactional(async (tx) => {
+      const current = await findOneWithDecryption(
+        tx,
+        GatewayTransaction,
+        {
+          id: input.transactionId,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId,
+        },
+        undefined,
+        input.scope,
+      )
+      if (!current) return false
+      const releasedUnits = parseAmountUnits(current.capturedAmount) - input.reservedUnits
+      const released = await tx.nativeUpdate(
+        GatewayTransaction,
+        {
+          id: input.transactionId,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId,
+          capturedAmount: current.capturedAmount,
+        },
+        { capturedAmount: formatAmountUnits(releasedUnits < 0n ? 0n : releasedUnits), updatedAt: new Date() },
+      )
+      if (released !== 1) return false
+      const cleared = await tx.nativeUpdate(
+        GatewayPaymentOperation,
+        {
+          id: input.operation.id,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId,
+          reservedAmount,
+        },
+        { reservedAmount: null, updatedAt: new Date() },
+      )
+      if (cleared !== 1) {
+        throw captureConflict(
+          'payment_capture_reservation_conflict',
+          'Capture reservation could not be released for this operation',
+        )
+      }
+      Object.assign(input.operation, { reservedAmount: null })
+      return true
+    })
+  } catch {
+    return false
+  }
+}

package/src/modules/payment_gateways/lib/gateway-service.ts

@@ -17,10 +17,19 @@ import type { CredentialsService } from '../../integrations/lib/credentials-serv
 import type { IntegrationStateService } from '../../integrations/lib/state-service'
 import type { IntegrationLogService } from '../../integrations/lib/log-service'
 import { conflict } from '@open-mercato/shared/lib/crud/errors'
-import { GatewaySessionInitialization, GatewayTransaction } from '../data/entities'
+import { GatewayPaymentOperation, GatewaySessionInitialization, GatewayTransaction } from '../data/entities'
 import { canApplyManualAction, isValidTransition, type ManualGatewayAction } from './status-machine'
 import { emitPaymentGatewayEvent } from '../events'
 import { readGatewayMetadata, readWebhookLog } from './transaction-fields'
+import {
+  alignCapturedAmountWithStatus,
+  assertCaptureWithinRemaining,
+  formatAmountUnits,
+  parseAmountUnits,
+  releaseCaptureAmount,
+  reserveCaptureAmount,
+  settleCapturedAmount,
+} from './capture-ledger'
 import {
   completePaymentOperation,
   failPaymentOperation,
@@ -45,12 +54,6 @@ function assertManualActionAllowed(action: ManualGatewayAction, transaction: Gat
   }
 }
 
-function assertCaptureAmountAllowed(amount: number | undefined, transaction: GatewayTransaction): void {
-  if (amount !== undefined && amount > Number(transaction.amount)) {
-    throw conflict(`Capture amount ${amount} exceeds authorized transaction amount ${transaction.amount}`)
-  }
-}
-
 function applyAdapterResultStatus(
   action: ManualGatewayAction,
   transaction: GatewayTransaction,
@@ -199,6 +202,12 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
     payload: Record<string, unknown>
     scope: { organizationId: string; tenantId: string }
     assertInitialAllowed?: (transaction: GatewayTransaction) => void
+    beforeInvoke?: (context: { transaction: GatewayTransaction; operation: GatewayPaymentOperation }) => Promise<void>
+    releaseOnFailure?: (context: {
+      transaction: GatewayTransaction
+      operation: GatewayPaymentOperation
+      providerInvoked: boolean
+    }) => Promise<void>
     invoke: (context: {
       adapter: GatewayAdapter
       credentials: Record<string, unknown>
@@ -231,7 +240,17 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       return prepared.result as unknown as TResult
     }
 
+    const operation = prepared.claim.record
+    // Everything after this flips to true is post-settlement: the provider moved the money and the
+    // completion transaction committed it. A later event or logging failure must not undo either,
+    // so the failure path below only runs while the operation can still be rolled back.
+    let settled = false
+    // Flips once the provider call returned, so the failure path can tell "the provider never
+    // moved the money" from "the provider moved it and only our bookkeeping failed" — the two
+    // cases need opposite rollback decisions.
+    let providerInvoked = false
     try {
+      await input.beforeInvoke?.({ transaction, operation })
       const { adapter, credentials } = await resolveAdapterAndCredentials(
         transaction.providerKey,
         { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
@@ -242,6 +261,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         transaction,
         idempotencyKey: prepared.claim.providerIdempotencyKey,
       })
+      providerInvoked = true
       const statusChanged = await completePaymentOperation(
         em,
         prepared.claim,
@@ -253,6 +273,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
           return changed
         },
       )
+      settled = true
       if (statusChanged) {
         await emitStatusEvent(result.status, {
           transactionId: transaction.id,
@@ -265,7 +286,12 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       await input.afterCommit(transaction, result)
       return result
     } catch (error: unknown) {
-      await Promise.allSettled([failPaymentOperation(em, prepared.claim)])
+      if (!settled) {
+        if (input.releaseOnFailure) {
+          await input.releaseOnFailure({ transaction, operation, providerInvoked }).catch(() => undefined)
+        }
+        await Promise.allSettled([failPaymentOperation(em, prepared.claim)])
+      }
       throw error
     }
   }
@@ -285,6 +311,9 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         ?? (session.clientSession?.type === 'redirect' ? session.clientSession.redirectUrl : null),
       clientSecret: session.clientSecret ?? null,
       amount: String(input.amount),
+      // An automatic-capture session comes back already captured, so the ledger has to start
+      // at the full amount — otherwise a later manual capture would look like the first one.
+      capturedAmount: session.status === 'captured' ? String(input.amount) : '0',
       currencyCode: input.currencyCode,
       gatewayMetadata: {
         ...(session.providerData ?? {}),
@@ -491,16 +520,57 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       scope: { organizationId: string; tenantId: string },
       operationId?: string,
     ): Promise<CaptureResult> {
+      let reservedUnits: bigint | null = null
+      let providerAmount = amount
       return executeManualOperation({
         action: 'capture',
         transactionId,
         operationId,
         payload: { amount: amount ?? null },
         scope,
-        assertInitialAllowed: (transaction) => assertCaptureAmountAllowed(amount, transaction),
+        assertInitialAllowed: (transaction) => { assertCaptureWithinRemaining(transaction, amount) },
+        beforeInvoke: async ({ transaction, operation }) => {
+          const alreadyCapturedUnits = parseAmountUnits(transaction.capturedAmount)
+          reservedUnits = await reserveCaptureAmount(em, { transaction, operation, amount, scope })
+          // "Capture the rest" has to name the remaining amount once part of the authorization is
+          // already captured, otherwise the provider would capture the full amount a second time.
+          if (amount === undefined && alreadyCapturedUnits > 0n) {
+            providerAmount = Number(formatAmountUnits(reservedUnits))
+          }
+        },
+        // The slice goes back only while the provider has not been called yet. Once the capture
+        // call returned, the money may already have moved and only the completion transaction
+        // failed, so releasing would reopen the authorization for a fresh operation id and allow an
+        // over-capture. Holding the reservation is the conservative outcome: a retry of this same
+        // operation id reuses both the reservation and the provider idempotency key, so the provider
+        // itself collapses the duplicate.
+        releaseOnFailure: async ({ transaction, operation, providerInvoked }) => {
+          if (reservedUnits === null) return
+          if (providerInvoked) {
+            await writeTransactionLog(
+              transaction.providerKey,
+              { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+              transaction.id,
+              'warn',
+              'Capture reservation stays outstanding because the provider call already returned',
+              { operationId: operation.operationId, reservedAmount: formatAmountUnits(reservedUnits) },
+            )
+            return
+          }
+          const released = await releaseCaptureAmount(em, { transactionId, operation, reservedUnits, scope })
+          if (released) return
+          await writeTransactionLog(
+            transaction.providerKey,
+            { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+            transaction.id,
+            'warn',
+            'Capture reservation stays outstanding after a failed capture',
+            { operationId: operation.operationId, reservedAmount: formatAmountUnits(reservedUnits) },
+          )
+        },
         invoke: ({ adapter, credentials, transaction, idempotencyKey }) => adapter.capture({
           sessionId: readProviderSessionId(transaction),
-          amount,
+          amount: providerAmount,
           credentials,
           idempotencyKey,
         }),
@@ -509,6 +579,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
             ...readGatewayMetadata(transaction.gatewayMetadata),
             captureResult: result.providerData,
           }
+          if (reservedUnits !== null) settleCapturedAmount(transaction, reservedUnits, result.capturedAmount)
         },
         afterCommit: (transaction, result) => writeTransactionLog(
           transaction.providerKey,
@@ -604,6 +675,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       if (status.status !== transaction.unifiedStatus && isValidTransition(transaction.unifiedStatus as UnifiedPaymentStatus, status.status)) {
         const previousStatus = transaction.unifiedStatus
         transaction.unifiedStatus = status.status
+        alignCapturedAmountWithStatus(transaction, status.status)
         transaction.gatewayStatus = status.status
         transaction.gatewayMetadata = { ...readGatewayMetadata(transaction.gatewayMetadata), statusResult: status.providerData ?? null }
         transaction.lastPolledAt = new Date()
@@ -650,6 +722,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       const previousStatus = transaction.unifiedStatus
       if (shouldApplyStatus) {
         transaction.unifiedStatus = update.unifiedStatus
+        alignCapturedAmountWithStatus(transaction, update.unifiedStatus)
       }
       if (update.providerStatus) {
         transaction.gatewayStatus = update.providerStatus

package/src/modules/payment_gateways/lib/payment-operation-idempotency.ts

@@ -170,6 +170,7 @@ export async function preparePaymentOperation(
     attemptToken: claim.attemptToken,
     attemptCount: 1,
     result: null,
+    reservedAmount: null,
     leaseExpiresAt: claim.leaseExpiresAt,
     organizationId: input.scope.organizationId,
     tenantId: input.scope.tenantId,

package/src/modules/payment_gateways/migrations/.snapshot-open-mercato.json

@@ -195,6 +195,23 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "reserved_amount": {
+          "name": "reserved_amount",
+          "type": "numeric(18,4)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": 18,
+          "scale": 4,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "decimal"
+        },
         "result": {
           "name": "result",
           "type": "jsonb",
@@ -560,6 +577,23 @@
           "enumItems": [],
           "mappedType": "decimal"
         },
+        "captured_amount": {
+          "name": "captured_amount",
+          "type": "numeric(18,4)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": 18,
+          "scale": 4,
+          "default": "'0'",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "decimal"
+        },
         "client_secret": {
           "name": "client_secret",
           "type": "text",

package/src/modules/payment_gateways/migrations/Migration20260725101500_payment_gateways.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260725101500_payment_gateways extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "gateway_transactions" add column "captured_amount" numeric(18,4) not null default '0';`);
+    this.addSql(`alter table "gateway_payment_operations" add column "reserved_amount" numeric(18,4) null;`);
+    // Backfill the captured-to-date ledger from the succeeded capture operations, which are the
+    // only capture path since the payment operation ledger landed. Transactions captured before
+    // that (no succeeded capture rows) fall back to their full amount when their status says the
+    // money was taken. A historical `partially_captured` transaction has no recoverable captured
+    // amount, so it starts at 0 and can still be over-captured once.
+    this.addSql(`update "gateway_transactions" as t set "captured_amount" = coalesce((select sum((o."result"->>'capturedAmount')::numeric) from "gateway_payment_operations" as o where o."transaction_id" = t."id" and o."operation_type" = 'capture' and o."status" = 'succeeded'), case when t."unified_status" in ('captured', 'refunded', 'partially_refunded') then t."amount" else 0 end);`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "gateway_payment_operations" drop column "reserved_amount";`);
+    this.addSql(`alter table "gateway_transactions" drop column "captured_amount";`);
+  }
+
+}

package/src/modules/query_index/lib/indexer.ts

@@ -3,9 +3,12 @@ import { resolveEntityTableName } from '@open-mercato/shared/lib/query/engine'
 import { resolveTenantEncryptionService } from '@open-mercato/shared/lib/encryption/customFieldValues'
 import { decryptIndexDocForSearch, encryptIndexDocForStorage } from '@open-mercato/shared/lib/encryption/indexDoc'
 import { sql } from 'kysely'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import { replaceSearchTokensForRecord, deleteSearchTokensForRecord } from './search-tokens'
 import { attachAggregateSearchField } from './document'
 
+const logger = createLogger('query_index').child({ component: 'indexer' })
+
 type BuildDocParams = {
   entityType: string // '<module>:<entity>'
   recordId: string
@@ -121,8 +124,12 @@ export async function buildIndexDoc(em: EntityManager, params: BuildDocParams):
     }
   } catch {}
 
+  // Kept outside the guard below: a failure while building the aggregate search field is a
+  // bug in the aggregation or its configuration, and must surface instead of being mistaken
+  // for an encryption failure and silently skipping encryption.
+  doc = attachAggregateSearchField(doc)
+
   try {
-    doc = attachAggregateSearchField(doc)
     const encryption = resolveTenantEncryptionService(em as any)
     doc = await encryptIndexDocForStorage(
       params.entityType,
@@ -130,7 +137,23 @@ export async function buildIndexDoc(em: EntityManager, params: BuildDocParams):
       { tenantId: params.tenantId ?? null, organizationId: params.organizationId ?? null },
       encryption,
     )
-  } catch {}
+  } catch (error) {
+    // `encryptIndexDocForStorage` already returns the document untouched when encryption is
+    // absent or disabled, so a throw here is always a genuine encryption failure. Returning
+    // `doc` would hand the caller the plaintext document to write into `entity_indexes`,
+    // which must stay encrypted at rest; returning `null` would mean "record gone" and make
+    // `upsertIndexRow` delete a healthy index row. Fail loudly instead: the projection keeps
+    // its previous, correctly encrypted contents and the `query_index.upsert_one` subscriber
+    // persists the error via `recordIndexerError`.
+    logger.error('Index document encryption failed; refusing to return an unencrypted document', {
+      entityType: params.entityType,
+      recordId: params.recordId,
+      tenantId: params.tenantId ?? null,
+      organizationId: params.organizationId ?? null,
+      err: error,
+    })
+    throw error
+  }
 
   return doc
 }

package/src/modules/workflows/backend/definitions/visual-editor/page.tsx

@@ -11,6 +11,7 @@ import { useState, useCallback, useEffect } from 'react'
 import { useRouter, useSearchParams, usePathname } from 'next/navigation'
 import { graphToDefinition, definitionToGraph, validateWorkflowGraph, generateStepId, generateTransitionId, appendWorkflowEdge, ValidationError } from '../../../lib/graph-utils'
 import { performDeleteEdgeFlow, performDeleteNodeFlow } from '../../../lib/visual-editor-delete-flow'
+import { humanizeDefinitionIssuePath } from '../../../lib/format-validation-error'
 import { workflowDefinitionDataSchema } from '../../../data/validators'
 import { Page } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -357,11 +358,19 @@ export default function VisualEditorPage() {
       triggers: triggers.length > 0 ? triggers : undefined,
     }
 
-    // Run Zod schema validation before saving
+    // Run Zod schema validation before saving. Report every issue, not just the
+    // first: a save rejected for one missing activity field used to look like
+    // "nothing happened" once the operator fixed that field and hit a second
+    // one (#4232). Paths are humanized (steps.2.activities.0.config.endpoint →
+    // step 3 › activity 1 › endpoint) so the message points at the node to open.
     const schemaResult = workflowDefinitionDataSchema.safeParse(definitionData)
     if (!schemaResult.success) {
-      const firstIssue = schemaResult.error.issues[0]
-      flash(`Schema error: ${firstIssue.path.join('.')} - ${firstIssue.message}`, 'error')
+      const issues = schemaResult.error.issues
+      const described = issues
+        .slice(0, 3)
+        .map((issue) => `${humanizeDefinitionIssuePath(issue.path)}: ${issue.message}`)
+      const suffix = issues.length > described.length ? ` (+${issues.length - described.length} more)` : ''
+      flash(`Cannot save — ${described.join('; ')}${suffix}`, 'error')
       return
     }