@open-mercato/shared 0.9.0 → 0.9.1-develop.7462.1.94c09f158f

package/src/lib/bootstrap/factory.ts

@@ -143,9 +143,14 @@ async function registerWidgetsAndOptionalPackages(data: BootstrapData, options:
   // browser-facing UI registries. API-only bootstraps avoid loading @open-mercato/ui.
   try {
     const coreInjection = await import('@open-mercato/core/modules/widgets/lib/injection')
-    if (!options.skipCoreInjectionWidgets) {
-      coreInjection.registerCoreInjectionWidgets(data.injectionWidgetEntries)
-    }
+    // A partitioned runtime still needs its own entries — server-side resolvers read this
+    // registry on request paths — it just must not shrink what a fuller partition already
+    // published in the same process. Merge does both; skipping registration altogether left
+    // API-only processes with an unregistered registry that throws on first read.
+    coreInjection.registerCoreInjectionWidgets(
+      data.injectionWidgetEntries,
+      options.skipCoreInjectionWidgets ? { mode: 'merge' } : undefined,
+    )
     coreInjection.registerCoreInjectionTables(data.injectionTables, data.injectionWidgetEntries)
     coreInjection.registerEnabledModuleIds(
       data.modules.map((module) => module.id).filter((id): id is string => typeof id === 'string' && id.length > 0),

package/src/lib/bootstrap/types.ts

@@ -73,7 +73,11 @@ export interface BootstrapOptions {
   registrationKey?: string
   /** Skip browser-facing dashboard/injection registries in API-only runtimes. */
   skipUiRegistries?: boolean
-  /** Keep an existing core injection-widget registry intact in partitioned runtimes. */
+  /**
+   * Keep an existing core injection-widget registry intact in partitioned runtimes: this
+   * bootstrap's entries are merged in rather than published as the whole registry, so a
+   * partition that registers second never shrinks what the first one already exposed.
+   */
   skipCoreInjectionWidgets?: boolean
   onRegistrationComplete?: () => void
   appDiRegistrar?: AppDiRegistrar

package/src/lib/commands/__tests__/command-bus.test.ts

@@ -7,7 +7,7 @@ import {
   isCommandInterceptorError,
 } from '@open-mercato/shared/lib/commands'
 import { registerCommandInterceptors } from '@open-mercato/shared/lib/commands/command-interceptor-store'
-import type { CommandInterceptor } from '@open-mercato/shared/lib/commands/command-interceptor'
+import type { CommandInterceptor, CommandInterceptorContext } from '@open-mercato/shared/lib/commands/command-interceptor'
 
 describe('CommandBus', () => {
   afterEach(() => {
@@ -296,6 +296,57 @@ describe('CommandBus', () => {
     )
   })
 
+  it('defers opted-in before snapshots until after the transactional write guard', async () => {
+    const calls: string[] = []
+    const transactionalEm = { id: 'transaction-em' }
+    const buildLogMock = jest.fn(() => ({
+      actionLabel: 'Transaction snapshot',
+      resourceKind: 'test',
+      resourceId: 'transactional',
+    }))
+    const prepare = jest.fn(async (_input, ctx) => {
+      calls.push('prepare')
+      expect(ctx.transactionalEm).toBe(transactionalEm)
+      return { before: { state: 'locked-before' } }
+    })
+
+    registerCommand({
+      id: 'test.command.transactional-snapshot',
+      prepare,
+      prepareSnapshotInsideTransaction: true,
+      execute: jest.fn(async (_input, ctx) => {
+        calls.push('execute')
+        await ctx.beforeTransactionalWrite?.(transactionalEm as never)
+        calls.push('mutate')
+        return { ok: true }
+      }),
+      buildLog: buildLogMock,
+    })
+
+    const logMock = jest.fn(async () => ({ id: 'transaction-log' }))
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-transaction', tenantId: 'tenant-transaction', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+      beforeTransactionalWrite: jest.fn(async () => {
+        calls.push('lock')
+      }),
+    }
+
+    await bus.execute('test.command.transactional-snapshot', { input: {}, ctx })
+
+    expect(calls).toEqual(['execute', 'lock', 'prepare', 'mutate'])
+    expect(prepare).toHaveBeenCalledTimes(1)
+    expect(buildLogMock).toHaveBeenCalledWith(expect.objectContaining({
+      snapshots: { before: { state: 'locked-before' }, after: undefined },
+    }))
+  })
+
   it('loads a command file lazily before execution', async () => {
     const execute = jest.fn(async () => ({ ok: true }))
     registerCommandLoaders([
@@ -538,6 +589,54 @@ describe('CommandBus', () => {
   })
 
   describe('interceptor rejections', () => {
+    it('passes the original request to beforeExecute for preflight version checks', async () => {
+      registerCommand({ id: 'test.request-context', execute: jest.fn(async () => ({ ok: true })) })
+      const beforeExecute = jest.fn(async (_input: unknown, context: { request?: Request | null }) => {
+        expect(context.request?.headers.get('x-om-ext-optimistic-lock-expected-updated-at')).toBe('2026-09-29T11:00:00.000Z')
+        return { ok: false, status: 422 }
+      })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [{
+        id: 'test.request-context-interceptor', targetCommand: 'test.request-context', beforeExecute,
+      }] }])
+      const request = new Request('http://localhost/test', { headers: { 'x-om-ext-optimistic-lock-expected-updated-at': '2026-09-29T11:00:00.000Z' } })
+      const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+      const bus = new CommandBus()
+      await expect(bus.execute('test.request-context', { input: {}, ctx: {
+        container,
+        auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: null },
+        organizationScope: null,
+        selectedOrganizationId: null,
+        organizationIds: null,
+        request,
+      } })).rejects.toMatchObject({ status: 422 })
+      expect(beforeExecute).toHaveBeenCalledTimes(1)
+    })
+
+    it('passes request and organization scope to both execution lifecycle hooks', async () => {
+      registerCommand({ id: 'test.lifecycle-context', execute: async () => ({ ok: true }) })
+      const request = new Request('http://localhost/test')
+      const organizationScope = { selectedId: 'parent', filterIds: ['parent', 'child'], allowedIds: ['parent', 'child'], tenantId: 'tenant-1' }
+      const beforeExecute = jest.fn(async (_input: unknown, context: CommandInterceptorContext) => {
+        expect(context.request).toBe(request)
+        expect(context.organizationScope).toBe(organizationScope)
+        return { ok: true }
+      })
+      const afterExecute = jest.fn(async (_input: unknown, _result: unknown, context: CommandInterceptorContext) => {
+        expect(context.request).toBe(request)
+        expect(context.organizationScope).toBe(organizationScope)
+      })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [{
+        id: 'test.lifecycle-context-interceptor', targetCommand: 'test.lifecycle-context', beforeExecute, afterExecute,
+      }] }])
+      await new CommandBus().execute('test.lifecycle-context', { input: {}, ctx: {
+        container: createContainer({ injectionMode: InjectionMode.CLASSIC }),
+        auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: 'parent' },
+        organizationScope, selectedOrganizationId: 'parent', organizationIds: ['parent', 'child'], request,
+      } })
+      expect(beforeExecute).toHaveBeenCalledTimes(1)
+      expect(afterExecute).toHaveBeenCalledTimes(1)
+    })
+
     const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
       id: 'test.block',
       targetCommand: 'test.*',

package/src/lib/commands/command-bus.ts

@@ -297,6 +297,8 @@ export class CommandBus {
         auth: baseOptions.ctx.auth ?? null,
         selectedOrganizationId: baseOptions.ctx.selectedOrganizationId ?? baseOptions.ctx.auth?.orgId ?? null,
         container: baseOptions.ctx.container,
+        organizationScope: baseOptions.ctx.organizationScope ?? null,
+        request: baseOptions.ctx.request ?? null,
       }
       const beforeResult = await runCommandInterceptorsBefore(
         allInterceptors, commandId, baseOptions.input, interceptorCtx, resolvedUserFeatures,
@@ -338,16 +340,40 @@ export class CommandBus {
     }
 
     const executeCore = async (coreOptions: CommandExecutionOptions<TInput>) => {
-      const sourceLog = coreOptions.redoLogEntry ?? null
-      const snapshots = await this.prepareSnapshots(handler, coreOptions)
+      const snapshots: { before?: unknown } = {}
+      let executionOptions = coreOptions
+      if (handler.prepareSnapshotInsideTransaction && handler.prepare) {
+        const prepare = handler.prepare
+        const originalCtx = coreOptions.ctx
+        const originalBeforeTransactionalWrite = originalCtx.beforeTransactionalWrite
+        let prepared = false
+        let transactionalCtx: CommandRuntimeContext
+        transactionalCtx = {
+          ...originalCtx,
+          beforeTransactionalWrite: async (em, input) => {
+            await originalBeforeTransactionalWrite?.(em, input)
+            if (prepared) return
+            Object.assign(
+              snapshots,
+              (await prepare(coreOptions.input, { ...transactionalCtx, transactionalEm: em })) ?? {},
+            )
+            prepared = true
+          },
+        }
+        executionOptions = { ...coreOptions, ctx: transactionalCtx }
+      } else {
+        Object.assign(snapshots, await this.prepareSnapshots(handler, coreOptions))
+      }
+      effectiveOptions = executionOptions
+      const sourceLog = executionOptions.redoLogEntry ?? null
       const result =
         sourceLog && typeof handler.redo === 'function'
-          ? await handler.redo({ input: coreOptions.input, ctx: coreOptions.ctx, logEntry: sourceLog })
-          : await handler.execute(coreOptions.input, coreOptions.ctx)
-      const afterSnapshot = await this.captureAfter(handler, coreOptions, result)
+          ? await handler.redo({ input: executionOptions.input, ctx: executionOptions.ctx, logEntry: sourceLog })
+          : await handler.execute(executionOptions.input, executionOptions.ctx)
+      const afterSnapshot = await this.captureAfter(handler, executionOptions, result)
       const snapshotsWithAfter = { ...snapshots, after: afterSnapshot }
-      const logMeta = await this.buildLog(handler, coreOptions, result, snapshotsWithAfter)
-      let mergedMeta = this.mergeMetadata(coreOptions.metadata, logMeta)
+      const logMeta = await this.buildLog(handler, executionOptions, result, snapshotsWithAfter)
+      let mergedMeta = this.mergeMetadata(executionOptions.metadata, logMeta)
       // Interceptors opt into audit-log enrichment with a reserved `logContext` key rather
       // than the generic `context` one, so the metadata an interceptor already passes to its
       // own afterExecute hook is never silently promoted into audit storage.
@@ -362,7 +388,7 @@ export class CommandBus {
           ...logContextRecord,
         }
       }
-      const baseContext = asRecord(coreOptions.metadata?.context) ?? {}
+      const baseContext = asRecord(executionOptions.metadata?.context) ?? {}
       const logMetaContext = asRecord(logMeta?.context) ?? {}
       if (Object.keys(interceptorContextMerged).length > 0 || Object.keys(baseContext).length > 0 || Object.keys(logMetaContext).length > 0) {
         mergedMeta = mergedMeta ?? {}
@@ -376,7 +402,7 @@ export class CommandBus {
       if (undoable && mergedMeta?.replayable !== false) {
         mergedMeta = mergedMeta ?? {}
         if (!mergedMeta.undoToken) mergedMeta.undoToken = defaultUndoToken()
-        if (mergedMeta.actorUserId === undefined) mergedMeta.actorUserId = coreOptions.ctx.auth?.sub ?? null
+        if (mergedMeta.actorUserId === undefined) mergedMeta.actorUserId = executionOptions.ctx.auth?.sub ?? null
       } else if (mergedMeta?.replayable === false) {
         mergedMeta.undoToken = null
       }
@@ -405,7 +431,7 @@ export class CommandBus {
           if (inferred) mergedMeta.changes = inferred
         }
       }
-      const logEntry = await this.persistLog(commandId, coreOptions, mergedMeta)
+      const logEntry = await this.persistLog(commandId, executionOptions, mergedMeta)
       return { result, mergedMeta, logEntry }
     }
 
@@ -474,6 +500,8 @@ export class CommandBus {
           auth: effectiveOptions.ctx.auth ?? null,
           selectedOrganizationId: effectiveOptions.ctx.selectedOrganizationId ?? effectiveOptions.ctx.auth?.orgId ?? null,
           container: effectiveOptions.ctx.container,
+          organizationScope: effectiveOptions.ctx.organizationScope ?? null,
+          request: effectiveOptions.ctx.request ?? null,
         }
         const afterResult = await runCommandInterceptorsAfter(
           allInterceptors, commandId, effectiveOptions.input, result, interceptorCtx,
@@ -545,6 +573,8 @@ export class CommandBus {
         auth: replayCtx.auth ?? null,
         selectedOrganizationId: replayCtx.selectedOrganizationId ?? replayCtx.auth?.orgId ?? null,
         container: replayCtx.container,
+        organizationScope: replayCtx.organizationScope ?? null,
+        request: replayCtx.request ?? null,
       }
       const beforeResult = await runCommandInterceptorsBeforeUndo(
         allInterceptors, log.commandId, undoCtx, interceptorCtx, resolvedUserFeatures,
@@ -659,6 +689,8 @@ export class CommandBus {
           auth: ctx.auth ?? null,
           selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
           container: ctx.container,
+          organizationScope: ctx.organizationScope ?? null,
+          request: ctx.request ?? null,
         }
         await runCommandInterceptorsAfterUndo(
           allInterceptors, log.commandId, undoCtx, interceptorCtx,

package/src/lib/commands/command-interceptor.ts

@@ -1,4 +1,5 @@
 import type { AwilixContainer } from 'awilix'
+import type { OrganizationScope } from '@open-mercato/shared/lib/auth/principal-service'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 
 export interface CommandInterceptor {
@@ -47,8 +48,11 @@ export interface CommandInterceptorContext {
   auth: AuthContext | null
   /** Selected organization ID */
   selectedOrganizationId: string | null
+  organizationScope?: OrganizationScope | null
   /** DI container (read-only usage recommended) */
   container: AwilixContainer
+  /** Original request, when the command was called through HTTP. */
+  request?: Request | null
   /** Metadata passthrough from beforeExecute to afterExecute (or beforeUndo to afterUndo) */
   metadata?: Record<string, unknown>
 }

package/src/lib/commands/types.ts

@@ -67,6 +67,14 @@ export type CommandRuntimeContext = {
    * surrounding work as a single atomic, single-locked operation.
    */
   transactionalEm?: EntityManager
+  /**
+   * Optional server-side guard that supported command handlers invoke after
+   * opening their write transaction and before reading or mutating records.
+   * The guard receives that same transaction-bound EntityManager and, when the
+   * handler provides it, the final input after command interceptors. The input
+   * stays optional so existing handlers and callers remain source-compatible.
+   */
+  beforeTransactionalWrite?: (em: EntityManager, input?: unknown) => Promise<void>
   /**
    * Identifies the owner of an already-active {@link transactionalEm} lifetime.
    * Atomic replay accepts an ambient EntityManager only when this is the exact
@@ -243,6 +251,12 @@ export interface CommandHandler<TInput = unknown, TResult = unknown> {
    */
   readonly outputSchema?: ZodTypeAny
   prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null
+  /**
+   * Opt in to taking the undo snapshot inside the write transaction. The bus
+   * defers `prepare()` into `ctx.beforeTransactionalWrite`, after the handler's
+   * transaction guard and before its first read or mutation.
+   */
+  readonly prepareSnapshotInsideTransaction?: boolean
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined
   captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown

package/src/lib/encryption/__tests__/tenantDataEncryptionService.test.ts

@@ -883,3 +883,26 @@ describe('TenantDataEncryptionService map read failures (issue #6334)', () => {
     expect(execute).toHaveBeenCalledTimes(2)
   })
 })
+
+describe('TenantDataEncryptionService transaction-aware map reads', () => {
+  it('prefers the EntityManager executor over the bare connection', async () => {
+    const entityId = 'test:transaction_aware_map_read'
+    const execute = jest.fn(async () => [{
+      entity_id: entityId,
+      fields_json: [{ field: 'display_name' }],
+    }])
+    const bareExecute = jest.fn(async () => {
+      throw new Error('bare connection must not be used')
+    })
+    const service = new TenantDataEncryptionService({
+      execute,
+      getConnection: () => ({ execute: bareExecute }),
+    } as never)
+    jest.spyOn(service, 'isEnabled').mockReturnValue(true)
+
+    await expect(service.getEncryptedFieldNames(entityId, 'tenant-transaction', 'org-transaction'))
+      .resolves.toEqual(['display_name'])
+    expect(execute).toHaveBeenCalled()
+    expect(bareExecute).not.toHaveBeenCalled()
+  })
+})

package/src/lib/webhooks/__tests__/body.test.ts

@@ -2,6 +2,7 @@
 import {
   DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
   readBoundedRequestBody,
+  readBoundedRequestBytes,
   resolveWebhookBodyLimitBytes,
   WebhookBodyTooLargeError,
 } from '../body'
@@ -77,6 +78,53 @@ describe('readBoundedRequestBody', () => {
   })
 })
 
+describe('readBoundedRequestBytes', () => {
+  it('preserves exact bytes including invalid UTF-8', async () => {
+    const bytes = new Uint8Array([0xff, 0xfe, 0x41, 0xc3, 0x28])
+    const { request } = makeStreamingRequest([bytes.slice(0, 2), bytes.slice(2)])
+
+    const result = await readBoundedRequestBytes(request, { maxBytes: bytes.byteLength })
+
+    expect(Array.from(result)).toEqual(Array.from(bytes))
+    expect(new TextDecoder().decode(result)).toContain('\uFFFD')
+  })
+
+  it('returns an empty array for a missing body', async () => {
+    const request = new Request('http://localhost/webhook', { method: 'POST' })
+
+    expect((await readBoundedRequestBytes(request)).byteLength).toBe(0)
+    await expect(readBoundedRequestBody(request)).resolves.toBe('')
+  })
+
+  it('enforces the declared and streamed limits and cancels the stream', async () => {
+    const declared = new Request('http://localhost/webhook', {
+      method: 'POST',
+      headers: { 'content-length': '6' },
+      body: 'ok',
+    })
+    await expect(readBoundedRequestBytes(declared, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+
+    const { request, cancel } = makeStreamingRequest([
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([4, 5, 6]),
+      new Uint8Array([7, 8, 9]),
+    ])
+    await expect(readBoundedRequestBytes(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+    expect(cancel).toHaveBeenCalled()
+  })
+
+  it('keeps the string reader decoding the same bytes', async () => {
+    const bytes = new TextEncoder().encode('zażółć')
+    const { request } = makeStreamingRequest([bytes])
+
+    await expect(readBoundedRequestBody(request)).resolves.toBe('zażółć')
+  })
+})
+
 describe('resolveWebhookBodyLimitBytes', () => {
   it('uses the documented default for missing or invalid configuration', () => {
     expect(resolveWebhookBodyLimitBytes(undefined)).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)

package/src/lib/webhooks/body.ts

@@ -23,10 +23,10 @@ export function resolveWebhookBodyLimitBytes(
   return Number.isSafeInteger(parsed) ? parsed : fallback
 }
 
-export async function readBoundedRequestBody(
+export async function readBoundedRequestBytes(
   request: Request,
   options?: { maxBytes?: number },
-): Promise<string> {
+): Promise<Uint8Array> {
   const configuredLimit = options?.maxBytes ?? resolveWebhookBodyLimitBytes()
   const maxBytes = Number.isSafeInteger(configuredLimit) && configuredLimit > 0
     ? configuredLimit
@@ -39,7 +39,7 @@ export async function readBoundedRequestBody(
     }
   }
 
-  if (!request.body) return ''
+  if (!request.body) return new Uint8Array(0)
 
   const reader = request.body.getReader()
   const chunks: Uint8Array[] = []
@@ -66,5 +66,12 @@ export async function readBoundedRequestBody(
     body.set(chunk, offset)
     offset += chunk.byteLength
   }
-  return new TextDecoder().decode(body)
+  return body
+}
+
+export async function readBoundedRequestBody(
+  request: Request,
+  options?: { maxBytes?: number },
+): Promise<string> {
+  return new TextDecoder().decode(await readBoundedRequestBytes(request, options))
 }

package/src/lib/webhooks/index.ts

@@ -4,6 +4,7 @@ export { generateWebhookSecret, parseWebhookSecret, isValidWebhookSecret } from
 export {
   DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
   readBoundedRequestBody,
+  readBoundedRequestBytes,
   resolveWebhookBodyLimitBytes,
   WebhookBodyTooLargeError,
 } from './body'

package/src/modules/payment_gateways/__tests__/types.test.ts

@@ -3,6 +3,9 @@ import {
   getWebhookHandler,
   registerWebhookHandler,
   type VerifyWebhookInput,
+  type WebhookLocatorContext,
+  type WebhookResponseOutcome,
+  WebhookVerificationUnavailableError,
   type WebhookEvent,
 } from '../types'
 
@@ -34,4 +37,45 @@ describe('payment gateway webhook registration', () => {
       expect(getWebhookHandler('invalid')).toBeUndefined()
     },
   )
+
+  it('stays compatible with one-argument locator hints', () => {
+    const readSessionIdHint = (payload: Record<string, unknown> | null) => (payload ? 'sess' : null)
+    registerWebhookHandler('legacy', handler, { readSessionIdHint })
+
+    expect(getWebhookHandler('legacy')?.readSessionIdHint?.({})).toBe('sess')
+    expect(getWebhookHandler('legacy')?.rawBody).toBeUndefined()
+    expect(getWebhookHandler('legacy')?.formatResponse).toBeUndefined()
+  })
+
+  it('passes through the optional extension hooks', () => {
+    const readSessionIdHint = (_payload: Record<string, unknown> | null, context?: WebhookLocatorContext) =>
+      context ? String(context.headers['x-id']) : null
+    const readPaymentIdHint = () => 'pay'
+    const formatResponse = (outcome: WebhookResponseOutcome) => ({ status: 200, body: outcome })
+    registerWebhookHandler('extended', handler, {
+      readSessionIdHint,
+      readPaymentIdHint,
+      rawBody: 'bytes',
+      formatResponse,
+    })
+
+    const registration = getWebhookHandler('extended')
+    expect(registration?.rawBody).toBe('bytes')
+    expect(registration?.readPaymentIdHint).toBe(readPaymentIdHint)
+    expect(registration?.formatResponse).toBe(formatResponse)
+    expect(registration?.readSessionIdHint?.(null, { rawBody: '', headers: { 'x-id': 'abc' } })).toBe('abc')
+  })
+
+  it('rejects an unknown rawBody mode', () => {
+    expect(() =>
+      registerWebhookHandler('bad', handler, { rawBody: 'stream' as unknown as 'text' }),
+    ).toThrow('[internal] Payment gateway webhook rawBody must be')
+    expect(getWebhookHandler('bad')).toBeUndefined()
+  })
+
+  it('exposes a typed verification-unavailable error', () => {
+    const error = new WebhookVerificationUnavailableError()
+    expect(error).toBeInstanceOf(Error)
+    expect(error.name).toBe('WebhookVerificationUnavailableError')
+  })
 })

package/src/modules/payment_gateways/types.ts

@@ -237,6 +237,45 @@ export interface VerifyWebhookInput {
   rawBody: string | Buffer
   headers: Record<string, string | string[] | undefined>
   credentials: Record<string, unknown>
+  /** Platform-resolved payment the webhook is expected to concern, when a locator found one. */
+  candidate?: WebhookCandidateSnapshot
+}
+
+/** Raw request material handed to webhook locator hints. */
+export interface WebhookLocatorContext {
+  rawBody: string | Buffer
+  headers: Record<string, string | string[] | undefined>
+}
+
+export interface WebhookCandidateSnapshot {
+  transactionId: string
+  paymentId: string
+  providerSessionId: string | null
+  amount: string
+  currencyCode: string
+}
+
+export type WebhookResponseOutcome =
+  | 'accepted'
+  | 'no_candidate'
+  | 'verification_failed'
+  | 'verification_unavailable'
+  | 'processing_failed'
+  | 'payload_too_large'
+  | 'rate_limited'
+
+export interface WebhookHttpResponse {
+  status: number
+  body: string | Record<string, unknown>
+  contentType?: string
+}
+
+/** Thrown by a webhook handler when verification cannot be performed (for example a provider outage). */
+export class WebhookVerificationUnavailableError extends Error {
+  constructor(message = 'Webhook verification is unavailable') {
+    super(message)
+    this.name = 'WebhookVerificationUnavailableError'
+  }
 }
 
 export interface WebhookEvent {
@@ -252,10 +291,15 @@ export interface WebhookEvent {
 export interface WebhookHandlerRegistration {
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>
   queue?: string
-  readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+  readSessionIdHint?: (payload: Record<string, unknown> | null, context?: WebhookLocatorContext) => string | null
+  readPaymentIdHint?: (payload: Record<string, unknown> | null, context?: WebhookLocatorContext) => string | null
   maxBodyBytes?: number
+  rawBody?: WebhookRawBodyMode
+  formatResponse?: (outcome: WebhookResponseOutcome) => WebhookHttpResponse
 }
 
+export type WebhookRawBodyMode = 'text' | 'bytes'
+
 // ── Adapter Registry Options ────────────────────────────────────────────────
 
 export interface RegisterAdapterOptions {
@@ -345,12 +389,11 @@ export function clearGatewayAdapters(): void {
 export function registerWebhookHandler(
   providerKey: string,
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>,
-  options?: {
-    queue?: string
-    readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
-    maxBodyBytes?: number
-  },
+  options?: Omit<WebhookHandlerRegistration, 'handler'>,
 ): () => void {
+  if (options?.rawBody !== undefined && options.rawBody !== 'text' && options.rawBody !== 'bytes') {
+    throw new Error("[internal] Payment gateway webhook rawBody must be 'text' or 'bytes'")
+  }
   if (
     options?.maxBodyBytes !== undefined
     && (!Number.isSafeInteger(options.maxBodyBytes)
@@ -366,7 +409,10 @@ export function registerWebhookHandler(
     handler,
     queue: options?.queue,
     readSessionIdHint: options?.readSessionIdHint,
+    readPaymentIdHint: options?.readPaymentIdHint,
     maxBodyBytes: options?.maxBodyBytes,
+    rawBody: options?.rawBody,
+    formatResponse: options?.formatResponse,
   })
   return () => {
     webhookHandlerRegistry.delete(providerKey)

package/src/modules/widgets/__tests__/injection-loader.partitioned-registration.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Regression coverage for the partitioned-bootstrap registry contract.
+ *
+ * A Node process can run more than one bootstrap partition: the API-only one
+ * (`skipCoreInjectionWidgets: true`) and the full page one. Two invariants have to hold
+ * together, and skipping registration outright only satisfied the first:
+ *
+ * 1. the partition that registers second must never shrink the registry the first published;
+ * 2. an API-only process must still be able to READ the registry, because module API routes
+ *    resolve widget contributions on the request path.
+ */
+import { describe, it, expect, beforeEach, jest } from '@jest/globals'
+import type { ModuleInjectionWidgetEntry } from '@open-mercato/shared/modules/registry'
+
+const GLOBAL_INJECTION_WIDGETS_KEY = '__openMercatoCoreInjectionWidgetEntries__'
+
+function entry(key: string): ModuleInjectionWidgetEntry {
+  return { moduleId: key.split(':')[0]!, key, source: 'package', widgetId: key, loader: async () => ({}) as never }
+}
+
+type Loader = typeof import('@open-mercato/shared/modules/widgets/injection-loader')
+
+function freshLoader(): Loader {
+  delete (globalThis as Record<string, unknown>)[GLOBAL_INJECTION_WIDGETS_KEY]
+  let loader!: Loader
+  jest.isolateModules(() => {
+    loader = require('@open-mercato/shared/modules/widgets/injection-loader') as Loader
+  })
+  return loader
+}
+
+describe('core injection widget registration modes', () => {
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)[GLOBAL_INJECTION_WIDGETS_KEY]
+  })
+
+  it('replaces the registry by default', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('b:two')])
+    loader.registerCoreInjectionWidgets([entry('a:one')])
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one'])
+  })
+
+  it('populates an unregistered registry in merge mode instead of leaving it throwing', () => {
+    const loader = freshLoader()
+    expect(() => loader.getCoreInjectionWidgets()).toThrow(/not registered/)
+
+    loader.registerCoreInjectionWidgets([entry('a:one')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one'])
+  })
+
+  it('never shrinks a registry a fuller partition already published', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('b:two'), entry('c:three')])
+    loader.registerCoreInjectionWidgets([entry('a:one')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one', 'b:two', 'c:three'])
+  })
+
+  it('adds only the entries the registry does not already carry', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([entry('a:one')])
+    loader.registerCoreInjectionWidgets([entry('a:one'), entry('d:four')], { mode: 'merge' })
+
+    expect(loader.getCoreInjectionWidgets().map((it) => it.key)).toEqual(['a:one', 'd:four'])
+  })
+
+  it('leaves an unregistered registry untouched when it has nothing to contribute', () => {
+    const loader = freshLoader()
+    loader.registerCoreInjectionWidgets([], { mode: 'merge' })
+
+    // Publishing an empty array here would turn the loud "not registered" bootstrap error into
+    // silently missing contributions on every request.
+    expect(() => loader.getCoreInjectionWidgets()).toThrow(/not registered/)
+  })
+})