@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/src/lib/query/types.ts

@@ -151,12 +151,27 @@ export type EncryptedSortRowCapWarning = {
   entity: EntityId
   sortFields: string[]
   maxRows: number
+  /**
+   * Exact when `meta.listCountCapWarning` is absent; a floor when it is
+   * present (the list total itself was bounded at the cap).
+   */
   totalMatched: number
 }
 
+/**
+ * Present when the list COUNT was bounded at `cap` matching rows
+ * (`OM_LIST_COUNT_CAP`): `total` is a floor, not an exact value. Surfaced on
+ * CRUD list payloads as `totalIsCapped: true`.
+ */
+export type ListCountCapWarning = {
+  entity: EntityId
+  cap: number
+}
+
 export type QueryResultMeta = {
   partialIndexWarning?: PartialIndexWarning
   encryptedSortRowCapWarning?: EncryptedSortRowCapWarning
+  listCountCapWarning?: ListCountCapWarning
 }
 
 export type QueryResult<T = any> = {

package/src/lib/queue/dispatchOrigin.ts

@@ -0,0 +1,35 @@
+/**
+ * Trusted dispatch-origin markers for queue jobs.
+ *
+ * Jobs that drive privileged side effects (payment webhook processors and
+ * similar sinks) MUST only execute payloads enqueued by trusted infrastructure
+ * code paths. The scheduler dispatch layer and inbound webhook routes mark the
+ * payloads they enqueue; sensitive workers verify the marker before doing work.
+ *
+ * The scheduler payload sanitizer strips every caller-supplied `_`-prefixed
+ * key from scheduled target payloads, so a marker cannot be forged through the
+ * scheduler job API. Direct queue/Redis write access is operator-level access
+ * and outside this threat model.
+ */
+
+export const QUEUE_JOB_ORIGIN_KEY = '_jobOrigin'
+
+export type QueueJobOrigin = 'inbound-webhook' | 'scheduler'
+
+export function markQueueJobOrigin<T extends Record<string, unknown>>(
+  payload: T,
+  origin: QueueJobOrigin,
+): T {
+  return { ...payload, [QUEUE_JOB_ORIGIN_KEY]: origin }
+}
+
+export function readQueueJobOrigin(payload: unknown): QueueJobOrigin | null {
+  if (!payload || typeof payload !== 'object') return null
+  const value = (payload as Record<string, unknown>)[QUEUE_JOB_ORIGIN_KEY]
+  if (value === 'inbound-webhook' || value === 'scheduler') return value
+  return null
+}
+
+export function isTrustedWebhookDispatch(payload: unknown): boolean {
+  return readQueueJobOrigin(payload) === 'inbound-webhook'
+}

package/src/lib/search/config.ts

@@ -8,6 +8,15 @@ export type SearchConfig = {
   enablePartials: boolean
   hashAlgorithm: 'sha256' | 'sha1' | 'md5'
   storeRawTokens: boolean
+  /**
+   * When true, a like/ilike on a PLAINTEXT base column runs as exact SQL ILIKE instead of being
+   * rewritten into an approximate search-token match; encrypted columns always keep the token
+   * path (ILIKE against ciphertext cannot match). Off by default: token matching can be faster
+   * than an unanchored ILIKE, which may need a full scan without a trigram index — but it is
+   * approximate (fragments under minTokenLength vanish, so `ZK 1/2026` degrades to its year and
+   * an all-short term drops the predicate). Flip it on when list search must be exact.
+   */
+  useIlikeForNonEncryptedFields?: boolean
   blocklistedFields: string[]
   entityBlocklistedFields?: Record<string, string[]>
   maxFieldChars?: number
@@ -112,6 +121,7 @@ export function resolveSearchConfig(): SearchConfig {
     enablePartials: parseBoolean(process.env.OM_SEARCH_ENABLE_PARTIAL, true),
     hashAlgorithm: parseHashAlgorithm(process.env.OM_SEARCH_HASH_ALGO),
     storeRawTokens: parseBoolean(process.env.OM_SEARCH_STORE_RAW_TOKENS, false),
+    useIlikeForNonEncryptedFields: parseBoolean(process.env.OM_SEARCH_USE_ILIKE_FOR_NON_ENCRYPTED_FIELDS, false),
     blocklistedFields: blocklist.global,
     entityBlocklistedFields: blocklist.byEntity,
     maxFieldChars: parseNumber(process.env.OM_SEARCH_MAX_FIELD_CHARS, DEFAULT_SEARCH_MAX_FIELD_CHARS, 0),

package/src/lib/search/entityAccess.ts

@@ -0,0 +1,132 @@
+import type { SearchEntityConfig } from '../../modules/search'
+import { authorizeFeatures } from '../../security/featurePolicy'
+
+/**
+ * Minimal shape of the `searchIndexer` DI service consumed by per-entity ACL
+ * resolution. Kept structural so callers and tests can pass a plain object
+ * instead of constructing a full `SearchIndexer`.
+ */
+export type SearchEntityConfigLookup = {
+  getEntityConfig: (entityId: string) => SearchEntityConfig | undefined
+  getAllEntityConfigs: () => SearchEntityConfig[]
+}
+
+export type SearchEntityAccessSubject = {
+  grantedFeatures: readonly string[]
+  isSuperAdmin?: boolean
+}
+
+export type SearchEntityDenyReason =
+  /** No module declares this entity in a `search.ts` config. */
+  | 'unconfigured'
+  /** The entity is configured for search but declares no `aclFeatures`. */
+  | 'no-acl-features'
+  /** The caller does not hold the entity's declared view feature(s). */
+  | 'insufficient-features'
+
+export type SearchEntityAccessOptions = {
+  /**
+   * Called once per denied entity type. Exists so a silent drop is diagnosable:
+   * results disappearing because a module forgot to declare `aclFeatures` looks
+   * identical, from the palette, to results that simply did not match.
+   */
+  onDeny?: (entityId: string, reason: SearchEntityDenyReason) => void
+}
+
+/**
+ * Decide whether a caller may see results for one entity type.
+ *
+ * The single `search.global` gate on the palette only says "this user may use
+ * global search"; it says nothing about which records they may read. Each entity
+ * declares the owning module's view feature(s) in `aclFeatures`, and those are
+ * what actually authorize the read — the same rule the `search_get` /
+ * `search_aggregate` AI tools already apply.
+ *
+ * Fails closed: an entity that is not registered for search, or that declares no
+ * `aclFeatures`, is never exposed to a non-superadmin caller.
+ */
+export function canReadSearchEntity(
+  entityId: string,
+  lookup: SearchEntityConfigLookup,
+  subject: SearchEntityAccessSubject,
+  options: SearchEntityAccessOptions = {},
+): boolean {
+  if (subject.isSuperAdmin) return true
+
+  const config = lookup.getEntityConfig(entityId)
+  if (!config) {
+    options.onDeny?.(entityId, 'unconfigured')
+    return false
+  }
+
+  const required = config.aclFeatures
+  if (!required || required.length === 0) {
+    options.onDeny?.(entityId, 'no-acl-features')
+    return false
+  }
+
+  const allowed = authorizeFeatures(required, {
+    grantedFeatures: subject.grantedFeatures,
+    unrestricted: false,
+  })
+  if (!allowed) options.onDeny?.(entityId, 'insufficient-features')
+  return allowed
+}
+
+/**
+ * The entity types this caller may read, narrowed to `requestedEntityTypes` when
+ * the caller asked for specific ones.
+ *
+ * Restricting the query up front is what keeps `limit` meaningful. Filtering only
+ * after the search would spend the whole result budget on records the caller
+ * cannot see: an employee granted just `customers.people.view` would get the top
+ * 50 hits across every entity type, then watch most of them be dropped, and the
+ * palette would look empty even with hundreds of matching people behind it.
+ *
+ * Returns `undefined` when no restriction applies (superadmin with no explicit
+ * request), and an empty array when nothing is readable — callers should
+ * short-circuit on that rather than pass it down as "no filter".
+ */
+export function resolveReadableEntityTypes(
+  lookup: SearchEntityConfigLookup,
+  subject: SearchEntityAccessSubject,
+  requestedEntityTypes?: string[],
+): string[] | undefined {
+  if (subject.isSuperAdmin) return requestedEntityTypes
+
+  const readable = lookup
+    .getAllEntityConfigs()
+    .filter((config) => config.enabled !== false)
+    .map((config) => config.entityId)
+    .filter((entityId) => canReadSearchEntity(entityId, lookup, subject))
+
+  if (!requestedEntityTypes) return readable
+  const requested = new Set(requestedEntityTypes)
+  return readable.filter((entityId) => requested.has(entityId))
+}
+
+/**
+ * Drop the results whose entity type the caller is not allowed to read.
+ *
+ * Filtering happens server-side so an under-privileged caller never receives the
+ * presenter title, subtitle or deep link of a record they cannot open. Decisions
+ * are memoized per entity type because a single response commonly mixes dozens of
+ * results across a handful of types.
+ */
+export function filterSearchResultsByEntityAccess<T extends { entityId: string }>(
+  results: readonly T[],
+  lookup: SearchEntityConfigLookup,
+  subject: SearchEntityAccessSubject,
+  options: SearchEntityAccessOptions = {},
+): T[] {
+  if (subject.isSuperAdmin) return [...results]
+
+  const decisions = new Map<string, boolean>()
+  return results.filter((result) => {
+    const cached = decisions.get(result.entityId)
+    if (cached !== undefined) return cached
+    const allowed = canReadSearchEntity(result.entityId, lookup, subject, options)
+    decisions.set(result.entityId, allowed)
+    return allowed
+  })
+}

package/src/modules/events/__tests__/factory.test.ts

@@ -0,0 +1,88 @@
+const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
+
+type EventFactoryModule = typeof import('../factory')
+
+describe('event definition registry', () => {
+  const globalScope = globalThis as Record<string, unknown>
+  const originalRegistry = globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+
+  beforeEach(() => {
+    delete globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+  })
+
+  afterAll(() => {
+    if (originalRegistry === undefined) {
+      delete globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+    } else {
+      globalScope[GLOBAL_EVENT_REGISTRY_KEY] = originalRegistry
+    }
+  })
+
+  it('shares declarations and registered configs across isolated module instances', () => {
+    let firstInstance: EventFactoryModule | undefined
+    let secondInstance: EventFactoryModule | undefined
+
+    jest.isolateModules(() => {
+      firstInstance = require('../factory') as EventFactoryModule
+      const config = firstInstance.createModuleEvents({
+        moduleId: 'isolated_events_test',
+        events: [{
+          id: 'isolated_events_test.invalidated',
+          label: 'Invalidated',
+          crossProcessBroadcast: true,
+        }] as const,
+      })
+      firstInstance.registerEventModuleConfigs([config])
+    })
+
+    jest.isolateModules(() => {
+      secondInstance = require('../factory') as EventFactoryModule
+    })
+
+    expect(secondInstance).not.toBe(firstInstance)
+    expect(secondInstance?.isEventDeclared('isolated_events_test.invalidated')).toBe(true)
+    expect(secondInstance?.isCrossProcessBroadcastEvent('isolated_events_test.invalidated')).toBe(true)
+    expect(secondInstance?.getDeclaredEvents()).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        id: 'isolated_events_test.invalidated',
+        module: 'isolated_events_test',
+      }),
+    ]))
+    expect(secondInstance?.getEventModuleConfigs()).toHaveLength(1)
+  })
+
+  it('refreshes a module definition during HMR without duplicating its event id', () => {
+    let firstInstance: EventFactoryModule | undefined
+    let secondInstance: EventFactoryModule | undefined
+
+    jest.isolateModules(() => {
+      firstInstance = require('../factory') as EventFactoryModule
+      firstInstance.createModuleEvents({
+        moduleId: 'hmr_events_test',
+        events: [{ id: 'hmr_events_test.changed', label: 'Before' }] as const,
+      })
+    })
+
+    jest.isolateModules(() => {
+      secondInstance = require('../factory') as EventFactoryModule
+      secondInstance.createModuleEvents({
+        moduleId: 'hmr_events_test',
+        events: [{
+          id: 'hmr_events_test.changed',
+          label: 'After',
+          clientBroadcast: true,
+        }] as const,
+      })
+    })
+
+    expect(firstInstance?.isBroadcastEvent('hmr_events_test.changed')).toBe(true)
+    expect(firstInstance?.getAllDeclaredEventIds()).toEqual(['hmr_events_test.changed'])
+    expect(firstInstance?.getDeclaredEvents()).toEqual([
+      expect.objectContaining({
+        id: 'hmr_events_test.changed',
+        label: 'After',
+        clientBroadcast: true,
+      }),
+    ])
+  })
+})

package/src/modules/events/factory.ts

@@ -65,17 +65,54 @@ export function getGlobalEventBus(): GlobalEventBus | null {
 // Event Registry for Validation
 // =============================================================================
 
-// Global set of all declared event IDs for runtime validation
-const allDeclaredEventIds = new Set<string>()
+type EventRegistryState = {
+  declaredEventIds: Set<string>
+  declaredEvents: EventDefinition[]
+  registeredEventConfigs: EventModuleConfig[] | null
+}
+
+const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
+
+const fallbackEventRegistryState: EventRegistryState = {
+  declaredEventIds: new Set<string>(),
+  declaredEvents: [],
+  registeredEventConfigs: null,
+}
+
+function isEventRegistryState(value: unknown): value is EventRegistryState {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<EventRegistryState>
+  return candidate.declaredEventIds instanceof Set
+    && Array.isArray(candidate.declaredEvents)
+    && (candidate.registeredEventConfigs === null || Array.isArray(candidate.registeredEventConfigs))
+}
 
-// Global registry of all declared events with their full definitions
-const allDeclaredEvents: EventDefinition[] = []
+function getEventRegistryState(): EventRegistryState {
+  try {
+    const globalScope = globalThis as Record<string, unknown>
+    const existing = globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+    if (isEventRegistryState(existing)) return existing
+    globalScope[GLOBAL_EVENT_REGISTRY_KEY] = fallbackEventRegistryState
+    return fallbackEventRegistryState
+  } catch {
+    // Restricted runtimes may deny global access. Keep the previous
+    // module-local behavior as a safe fallback.
+    return fallbackEventRegistryState
+  }
+}
 
 function addDeclaredEvent(event: EventDefinition): void {
-  allDeclaredEventIds.add(event.id)
-  // Avoid duplicates if createModuleEvents/registerEventModuleConfigs is called multiple times (e.g., HMR)
-  if (!allDeclaredEvents.find(e => e.id === event.id)) {
-    allDeclaredEvents.push(event)
+  const state = getEventRegistryState()
+  state.declaredEventIds.add(event.id)
+  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === event.id)
+  if (existingIndex < 0) {
+    state.declaredEvents.push(event)
+    return
+  }
+  // Refresh a module's own definition in place during HMR without allowing a
+  // duplicate declaration from another module to take over the event id.
+  if (state.declaredEvents[existingIndex]?.module === event.module) {
+    state.declaredEvents[existingIndex] = event
   }
 }
 
@@ -84,7 +121,7 @@ function addDeclaredEvent(event: EventDefinition): void {
  * Used for runtime validation to ensure only declared events are emitted.
  */
 export function isEventDeclared(eventId: string): boolean {
-  return allDeclaredEventIds.has(eventId)
+  return getEventRegistryState().declaredEventIds.has(eventId)
 }
 
 /**
@@ -92,7 +129,7 @@ export function isEventDeclared(eventId: string): boolean {
  * Useful for debugging and introspection.
  */
 export function getAllDeclaredEventIds(): string[] {
-  return Array.from(allDeclaredEventIds)
+  return Array.from(getEventRegistryState().declaredEventIds)
 }
 
 /**
@@ -100,7 +137,7 @@ export function getAllDeclaredEventIds(): string[] {
  * Used by the API to return available events for workflow triggers.
  */
 export function getDeclaredEvents(): EventDefinition[] {
-  return [...allDeclaredEvents]
+  return [...getEventRegistryState().declaredEvents]
 }
 
 /**
@@ -108,16 +145,52 @@ export function getDeclaredEvents(): EventDefinition[] {
  * Used by the SSE endpoint to filter events for the DOM Event Bridge.
  */
 export function isBroadcastEvent(eventId: string): boolean {
-  const event = allDeclaredEvents.find(e => e.id === eventId)
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
   return event?.clientBroadcast === true
 }
 
+/**
+ * Check if an event should be published over the server-to-server event bridge.
+ * Browser-broadcast events remain eligible for backward compatibility, while
+ * crossProcessBroadcast supports private process coordination without SSE.
+ */
+export function isCrossProcessBroadcastEvent(eventId: string): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  return event?.clientBroadcast === true || event?.crossProcessBroadcast === true
+}
+
+/**
+ * Check whether an event is reserved for private server-to-server
+ * coordination. Workflow-authored EMIT_EVENT activities must not emit these
+ * events because their payload and event id are tenant-managed input.
+ */
+export function isPrivateCrossProcessBroadcastEvent(eventId: string): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  return event?.crossProcessBroadcast === true && event?.clientBroadcast !== true
+}
+
+/**
+ * Verify provenance for a private cross-process event. The module id is
+ * stamped by a declared module emitter or another trusted server-side seam;
+ * tenant-managed event payloads never participate in this decision.
+ */
+export function isPrivateCrossProcessEventEmitter(
+  eventId: string,
+  emitterModuleId: string | undefined,
+): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  if (event?.crossProcessBroadcast !== true) return true
+  return typeof event.module === 'string'
+    && event.module.length > 0
+    && event.module === emitterModuleId
+}
+
 /**
  * Check if an event has portalBroadcast enabled.
  * Used by the portal SSE endpoint to filter events for the Portal Event Bridge.
  */
 export function isPortalBroadcastEvent(eventId: string): boolean {
-  const event = allDeclaredEvents.find(e => e.id === eventId)
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
   return event?.portalBroadcast === true
 }
 
@@ -125,17 +198,16 @@ export function isPortalBroadcastEvent(eventId: string): boolean {
 // Bootstrap Registration (similar to searchModuleConfigs pattern)
 // =============================================================================
 
-let _registeredEventConfigs: EventModuleConfig[] | null = null
-
 /**
  * Register event module configurations globally.
  * Called during app bootstrap with configs from events.generated.ts.
  */
 export function registerEventModuleConfigs(configs: EventModuleConfig[]): void {
-  if (_registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {
+  const state = getEventRegistryState()
+  if (state.registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {
     logger.debug('Event module configs re-registered (this may occur during HMR)')
   }
-  _registeredEventConfigs = configs
+  state.registeredEventConfigs = configs
   for (const config of configs) {
     for (const event of config.events) {
       addDeclaredEvent(event)
@@ -148,7 +220,7 @@ export function registerEventModuleConfigs(configs: EventModuleConfig[]): void {
  * Returns empty array if not registered.
  */
 export function getEventModuleConfigs(): EventModuleConfig[] {
-  return _registeredEventConfigs ?? []
+  return getEventRegistryState().registeredEventConfigs ?? []
 }
 
 // =============================================================================
@@ -239,7 +311,27 @@ export function createModuleEvents<
       return
     }
 
-    await eventBus.emit(eventId, payload, emitOptions)
+    const eventDefinition = fullEvents.find((event) => event.id === eventId)
+    const isClientBroadcast = eventDefinition?.clientBroadcast === true
+    const trustedOptions = eventDefinition?.crossProcessBroadcast === true || isClientBroadcast
+      ? {
+          ...emitOptions,
+          // Browser-broadcast module emitters historically accepted scope in
+          // their typed payload. Preserve that contract at the trusted module
+          // boundary while the event bus itself relies only on options.
+          ...(isClientBroadcast && emitOptions?.tenantId === undefined
+            ? { tenantId: payload.tenantId ?? null }
+            : {}),
+          ...(isClientBroadcast && emitOptions?.organizationId === undefined
+            ? { organizationId: payload.organizationId ?? null }
+            : {}),
+          ...(isClientBroadcast && emitOptions?.organizationIds === undefined && Array.isArray(payload.organizationIds)
+            ? { organizationIds: payload.organizationIds.filter((value): value is string => typeof value === 'string') }
+            : {}),
+          emitterModuleId: moduleId,
+        }
+      : emitOptions
+    await eventBus.emit(eventId, payload, trustedOptions)
   }
 
   return {

package/src/modules/events/types.ts

@@ -34,6 +34,8 @@ export interface EventDefinition {
   excludeFromTriggers?: boolean
   /** When true, this event is bridged to the browser via SSE (DOM Event Bridge). Default: false */
   clientBroadcast?: boolean
+  /** When true, this event is bridged between server processes without enabling browser delivery. Default: false */
+  crossProcessBroadcast?: boolean
   /** When true, this event is bridged to the customer portal via SSE (Portal Event Bridge). Default: false */
   portalBroadcast?: boolean
 }
@@ -66,6 +68,21 @@ export interface EmitOptions {
   tenantId?: string | null
   /** Trusted organization scope forwarded to subscribers separately from the payload */
   organizationId?: string | null
+  /**
+   * Trusted multi-organization audience forwarded to subscribers separately
+   * from the payload. Mirrors the documented SSE audience contract, where a
+   * clientBroadcast event may target several organizations at once; carried in
+   * trusted options so the receiver never falls back to payload scope.
+   */
+  organizationIds?: string[] | null
+  /**
+   * Module that emitted a private cross-process coordination event.
+   *
+   * This is stamped by `createModuleEvents`; application inputs must not set or
+   * derive it from event payloads.
+   * @internal
+   */
+  emitterModuleId?: string
 }
 
 // =============================================================================

package/src/modules/registry.ts

@@ -196,7 +196,19 @@ export type ModuleWorker = {
   concurrency: number
   lockDuration?: number
   maxStalledCount?: number
+  /**
+   * Reports a job the queue abandoned without running the handler.
+   *
+   * Present only for workers whose metadata declares it; the generator emits it as a lazy import
+   * beside the handler, because the registry serializes metadata as literals and a function cannot
+   * survive that.
+   */
+  onJobAbandoned?: (payload: unknown, info: { jobId: string | null; reason: string }) => void | Promise<void>
   handler: ModuleWorkerHandler
+  /** Opt-in flag exposing this queue as a user-facing scheduler target (issue #5213). */
+  schedulerSafe?: boolean
+  /** Creator features required beyond scheduler.jobs.manage when schedulerSafe is set. */
+  schedulerRequiredFeatures?: string[]
 }
 
 export type ModuleInfo = {
@@ -554,3 +566,31 @@ export function createLazyModuleWorker(
     return handler(job, ctx)
   }
 }
+
+/**
+ * Resolves a worker's `metadata.onJobAbandoned` on first use.
+ *
+ * The generator serializes worker metadata as literals, so a function declared there cannot be
+ * emitted inline the way `concurrency` or `lockDuration` are. It is emitted as this thunk instead —
+ * the same lazy-import treatment the handler already gets — and only for workers whose metadata
+ * declares the callback, so no other queue acquires one (and with it, a sweep) by accident.
+ */
+export function createLazyModuleWorkerAbandonHook(
+  loadModule: () => Promise<unknown>,
+  id: string
+): (payload: unknown, info: { jobId: string | null; reason: string }) => Promise<void> {
+  let hookPromise: Promise<((payload: unknown, info: { jobId: string | null; reason: string }) => unknown) | null> | null = null
+  return async (payload, info) => {
+    hookPromise ??= loadModule().then((loaded) => {
+      const metadata = (loaded as { metadata?: { onJobAbandoned?: unknown } } | null)?.metadata
+      return typeof metadata?.onJobAbandoned === 'function'
+        ? (metadata.onJobAbandoned as (payload: unknown, info: { jobId: string | null; reason: string }) => unknown)
+        : null
+    })
+    const hook = await hookPromise
+    if (!hook) {
+      throw new Error(`[registry] Worker "${id}" was registered with an abandoned-job hook but its metadata no longer declares one`)
+    }
+    await hook(payload, info)
+  }
+}

package/src/modules/widgets/component-registry.ts

@@ -26,6 +26,20 @@ export type ComponentOverride<TProps = unknown> = {
       propsSchema: ZodType<TProps>
     }
   | {
+      /**
+       * Higher-order component composed around the resolved component.
+       *
+       * The platform invokes it **at most once per `(wrapper, wrapped component)` pair**
+       * and caches the composed component for the lifetime of the registry, so that a
+       * wrapped subtree keeps a stable React identity instead of remounting on every
+       * override resolution.
+       *
+       * A wrapper MUST therefore be a pure function of `Original`: it may only read
+       * dynamic values — feature flags, locale, tenant configuration, the clock, request
+       * state — inside the render body of the component it returns, never at composition
+       * time. On the server the registry outlives a single request, so a value captured
+       * at composition time would be frozen across requests and tenants.
+       */
       wrapper: (Original: ComponentType<TProps>) => ComponentType<TProps>
     }
   | {