@open-mercato/shared 0.6.7-develop.6795.1.8a3f27921c → 0.6.7-develop.6814.1.0627c7e9f1

package/dist/lib/webhooks/verify.js

@@ -1,13 +1,16 @@
 import { timingSafeEqual, createHmac } from "node:crypto";
 import { parseWebhookSecret } from "./secrets.js";
-const TOLERANCE_SECONDS = 5 * 60;
-function verifyWebhookSignature(msgId, timestamp, body, signatureHeader, secrets, toleranceSeconds = TOLERANCE_SECONDS) {
-  const timestampNum = parseInt(timestamp, 10);
-  if (isNaN(timestampNum)) {
-    return { valid: false };
+const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 5 * 60;
+function isWebhookTimestampWithinTolerance(timestamp, toleranceSeconds = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  const normalizedTimestamp = timestamp.trim();
+  if (!/^\d+$/.test(normalizedTimestamp)) {
+    return false;
   }
-  const now = Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - timestampNum) > toleranceSeconds) {
+  const timestampNum = Number.parseInt(normalizedTimestamp, 10);
+  return Math.abs(nowSeconds - timestampNum) <= toleranceSeconds;
+}
+function verifyWebhookSignature(msgId, timestamp, body, signatureHeader, secrets, toleranceSeconds = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS) {
+  if (!isWebhookTimestampWithinTolerance(timestamp, toleranceSeconds)) {
     return { valid: false };
   }
   const signedContent = `${msgId}.${timestamp}.${body}`;
@@ -29,6 +32,8 @@ function verifyWebhookSignature(msgId, timestamp, body, signatureHeader, secrets
   return { valid: false };
 }
 export {
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  isWebhookTimestampWithinTolerance,
   verifyWebhookSignature
 };
 //# sourceMappingURL=verify.js.map

package/dist/lib/webhooks/verify.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/webhooks/verify.ts"],
-  "sourcesContent": ["import { timingSafeEqual, createHmac } from 'node:crypto'\nimport { parseWebhookSecret } from './secrets'\nimport type { WebhookVerificationResult } from './types'\n\nconst TOLERANCE_SECONDS = 5 * 60 // 5 minutes\n\n/**\n * Verify a Standard Webhooks signature against one or more secrets.\n * Returns verification result with which key matched.\n */\nexport function verifyWebhookSignature(\n  msgId: string,\n  timestamp: string,\n  body: string,\n  signatureHeader: string,\n  secrets: string[],\n  toleranceSeconds: number = TOLERANCE_SECONDS,\n): WebhookVerificationResult {\n  const timestampNum = parseInt(timestamp, 10)\n  if (isNaN(timestampNum)) {\n    return { valid: false }\n  }\n\n  const now = Math.floor(Date.now() / 1000)\n  if (Math.abs(now - timestampNum) > toleranceSeconds) {\n    return { valid: false }\n  }\n\n  const signedContent = `${msgId}.${timestamp}.${body}`\n  const providedSignatures = signatureHeader.split(' ')\n\n  for (let keyIndex = 0; keyIndex < secrets.length; keyIndex++) {\n    const key = parseWebhookSecret(secrets[keyIndex])\n    const expectedSig = createHmac('sha256', key)\n      .update(signedContent)\n      .digest('base64')\n\n    for (const sig of providedSignatures) {\n      const parts = sig.split(',')\n      if (parts.length !== 2 || parts[0] !== 'v1') continue\n\n      const sigBytes = Buffer.from(parts[1], 'base64')\n      const expectedBytes = Buffer.from(expectedSig, 'base64')\n\n      if (sigBytes.length !== expectedBytes.length) continue\n\n      if (timingSafeEqual(sigBytes, expectedBytes)) {\n        return { valid: true, matchedKeyIndex: keyIndex }\n      }\n    }\n  }\n\n  return { valid: false }\n}\n"],
-  "mappings": "AAAA,SAAS,iBAAiB,kBAAkB;AAC5C,SAAS,0BAA0B;AAGnC,MAAM,oBAAoB,IAAI;AAMvB,SAAS,uBACd,OACA,WACA,MACA,iBACA,SACA,mBAA2B,mBACA;AAC3B,QAAM,eAAe,SAAS,WAAW,EAAE;AAC3C,MAAI,MAAM,YAAY,GAAG;AACvB,WAAO,EAAE,OAAO,MAAM;AAAA,EACxB;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,MAAI,KAAK,IAAI,MAAM,YAAY,IAAI,kBAAkB;AACnD,WAAO,EAAE,OAAO,MAAM;AAAA,EACxB;AAEA,QAAM,gBAAgB,GAAG,KAAK,IAAI,SAAS,IAAI,IAAI;AACnD,QAAM,qBAAqB,gBAAgB,MAAM,GAAG;AAEpD,WAAS,WAAW,GAAG,WAAW,QAAQ,QAAQ,YAAY;AAC5D,UAAM,MAAM,mBAAmB,QAAQ,QAAQ,CAAC;AAChD,UAAM,cAAc,WAAW,UAAU,GAAG,EACzC,OAAO,aAAa,EACpB,OAAO,QAAQ;AAElB,eAAW,OAAO,oBAAoB;AACpC,YAAM,QAAQ,IAAI,MAAM,GAAG;AAC3B,UAAI,MAAM,WAAW,KAAK,MAAM,CAAC,MAAM,KAAM;AAE7C,YAAM,WAAW,OAAO,KAAK,MAAM,CAAC,GAAG,QAAQ;AAC/C,YAAM,gBAAgB,OAAO,KAAK,aAAa,QAAQ;AAEvD,UAAI,SAAS,WAAW,cAAc,OAAQ;AAE9C,UAAI,gBAAgB,UAAU,aAAa,GAAG;AAC5C,eAAO,EAAE,OAAO,MAAM,iBAAiB,SAAS;AAAA,MAClD;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,MAAM;AACxB;",
+  "sourcesContent": ["import { timingSafeEqual, createHmac } from 'node:crypto'\nimport { parseWebhookSecret } from './secrets'\nimport type { WebhookVerificationResult } from './types'\n\nexport const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 5 * 60 // 5 minutes\n\nexport function isWebhookTimestampWithinTolerance(\n  timestamp: string,\n  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,\n  nowSeconds: number = Math.floor(Date.now() / 1000),\n): boolean {\n  const normalizedTimestamp = timestamp.trim()\n  if (!/^\\d+$/.test(normalizedTimestamp)) {\n    return false\n  }\n\n  const timestampNum = Number.parseInt(normalizedTimestamp, 10)\n  return Math.abs(nowSeconds - timestampNum) <= toleranceSeconds\n}\n\n/**\n * Verify a Standard Webhooks signature against one or more secrets.\n * Returns verification result with which key matched.\n */\nexport function verifyWebhookSignature(\n  msgId: string,\n  timestamp: string,\n  body: string,\n  signatureHeader: string,\n  secrets: string[],\n  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,\n): WebhookVerificationResult {\n  if (!isWebhookTimestampWithinTolerance(timestamp, toleranceSeconds)) {\n    return { valid: false }\n  }\n\n  const signedContent = `${msgId}.${timestamp}.${body}`\n  const providedSignatures = signatureHeader.split(' ')\n\n  for (let keyIndex = 0; keyIndex < secrets.length; keyIndex++) {\n    const key = parseWebhookSecret(secrets[keyIndex])\n    const expectedSig = createHmac('sha256', key)\n      .update(signedContent)\n      .digest('base64')\n\n    for (const sig of providedSignatures) {\n      const parts = sig.split(',')\n      if (parts.length !== 2 || parts[0] !== 'v1') continue\n\n      const sigBytes = Buffer.from(parts[1], 'base64')\n      const expectedBytes = Buffer.from(expectedSig, 'base64')\n\n      if (sigBytes.length !== expectedBytes.length) continue\n\n      if (timingSafeEqual(sigBytes, expectedBytes)) {\n        return { valid: true, matchedKeyIndex: keyIndex }\n      }\n    }\n  }\n\n  return { valid: false }\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB,kBAAkB;AAC5C,SAAS,0BAA0B;AAG5B,MAAM,sCAAsC,IAAI;AAEhD,SAAS,kCACd,WACA,mBAA2B,qCAC3B,aAAqB,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI,GACxC;AACT,QAAM,sBAAsB,UAAU,KAAK;AAC3C,MAAI,CAAC,QAAQ,KAAK,mBAAmB,GAAG;AACtC,WAAO;AAAA,EACT;AAEA,QAAM,eAAe,OAAO,SAAS,qBAAqB,EAAE;AAC5D,SAAO,KAAK,IAAI,aAAa,YAAY,KAAK;AAChD;AAMO,SAAS,uBACd,OACA,WACA,MACA,iBACA,SACA,mBAA2B,qCACA;AAC3B,MAAI,CAAC,kCAAkC,WAAW,gBAAgB,GAAG;AACnE,WAAO,EAAE,OAAO,MAAM;AAAA,EACxB;AAEA,QAAM,gBAAgB,GAAG,KAAK,IAAI,SAAS,IAAI,IAAI;AACnD,QAAM,qBAAqB,gBAAgB,MAAM,GAAG;AAEpD,WAAS,WAAW,GAAG,WAAW,QAAQ,QAAQ,YAAY;AAC5D,UAAM,MAAM,mBAAmB,QAAQ,QAAQ,CAAC;AAChD,UAAM,cAAc,WAAW,UAAU,GAAG,EACzC,OAAO,aAAa,EACpB,OAAO,QAAQ;AAElB,eAAW,OAAO,oBAAoB;AACpC,YAAM,QAAQ,IAAI,MAAM,GAAG;AAC3B,UAAI,MAAM,WAAW,KAAK,MAAM,CAAC,MAAM,KAAM;AAE7C,YAAM,WAAW,OAAO,KAAK,MAAM,CAAC,GAAG,QAAQ;AAC/C,YAAM,gBAAgB,OAAO,KAAK,aAAa,QAAQ;AAEvD,UAAI,SAAS,WAAW,cAAc,OAAQ;AAE9C,UAAI,gBAAgB,UAAU,aAAa,GAAG;AAC5C,eAAO,EAAE,OAAO,MAAM,iBAAiB,SAAS;AAAA,MAClD;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,MAAM;AACxB;",
   "names": []
 }

package/dist/modules/payment_gateways/types.js

@@ -1,3 +1,4 @@
+import { DEFAULT_WEBHOOK_BODY_LIMIT_BYTES } from "../../lib/webhooks/body.js";
 const ADAPTER_REGISTRY_KEY = "__openMercatoPaymentGatewayAdapters__";
 const WEBHOOK_REGISTRY_KEY = "__openMercatoPaymentGatewayWebhookHandlers__";
 const DESCRIPTOR_REGISTRY_KEY = "__openMercatoPaymentGatewayDescriptors__";
@@ -61,11 +62,17 @@ function clearGatewayAdapters() {
   getAdapterRegistry().clear();
 }
 function registerWebhookHandler(providerKey, handler, options) {
+  if (options?.maxBodyBytes !== void 0 && (!Number.isSafeInteger(options.maxBodyBytes) || options.maxBodyBytes <= 0 || options.maxBodyBytes > DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)) {
+    throw new Error(
+      `[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer no greater than ${DEFAULT_WEBHOOK_BODY_LIMIT_BYTES}`
+    );
+  }
   const webhookHandlerRegistry = getWebhookHandlerRegistry();
   webhookHandlerRegistry.set(providerKey, {
     handler,
     queue: options?.queue,
-    readSessionIdHint: options?.readSessionIdHint
+    readSessionIdHint: options?.readSessionIdHint,
+    maxBodyBytes: options?.maxBodyBytes
   });
   return () => {
     webhookHandlerRegistry.delete(providerKey);

package/dist/modules/payment_gateways/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/payment_gateways/types.ts"],
-  "sourcesContent": ["// \u2500\u2500 Unified Payment Status \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport type UnifiedPaymentStatus =\n  | 'pending'\n  | 'authorized'\n  | 'captured'\n  | 'partially_captured'\n  | 'refunded'\n  | 'partially_refunded'\n  | 'cancelled'\n  | 'failed'\n  | 'expired'\n  | 'unknown'\n\n// \u2500\u2500 GatewayAdapter Interface \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface GatewayAdapter {\n  readonly providerKey: string\n\n  /** Create a payment session / payment intent */\n  createSession(input: CreateSessionInput): Promise<CreateSessionResult>\n\n  /** Capture an authorized payment */\n  capture(input: CaptureInput): Promise<CaptureResult>\n\n  /** Refund a captured payment (full or partial) */\n  refund(input: RefundInput): Promise<RefundResult>\n\n  /** Cancel / void an authorized payment before capture */\n  cancel(input: CancelInput): Promise<CancelResult>\n\n  /** Get current payment status from provider */\n  getStatus(input: GetStatusInput): Promise<GatewayPaymentStatus>\n\n  /** Verify and parse an inbound webhook event */\n  verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent>\n\n  /** Map provider status to unified status */\n  mapStatus(providerStatus: string, eventType?: string): UnifiedPaymentStatus\n}\n\nexport type PaymentGatewayDescriptorFieldType =\n  | 'text'\n  | 'number'\n  | 'select'\n  | 'multiselect'\n  | 'boolean'\n  | 'textarea'\n  | 'secret'\n  | 'url'\n\nexport interface PaymentGatewayDescriptorField {\n  key: string\n  label: string\n  type: PaymentGatewayDescriptorFieldType\n  description?: string\n  required?: boolean\n  options?: Array<{ value: string; label: string }>\n}\n\nexport type PaymentGatewayRendererType = 'embedded' | 'redirect'\n\nexport interface PaymentGatewayRendererDescriptor {\n  key: string\n  label: string\n  type: PaymentGatewayRendererType\n  description?: string\n  supportedPaymentTypes?: '*' | string[]\n  settingsFields?: PaymentGatewayDescriptorField[]\n}\n\nexport interface PaymentGatewayPresentationRequest {\n  mode?: 'auto' | PaymentGatewayRendererType\n  rendererKey?: string\n  rendererSettings?: Record<string, unknown>\n}\n\nexport interface PaymentGatewayDescriptor {\n  providerKey: string\n  label: string\n  sessionConfig?: {\n    fields?: PaymentGatewayDescriptorField[]\n    supportedCurrencies?: '*' | string[]\n    supportedPaymentTypes?: Array<{ value: string; label: string }>\n    defaultRendererKey?: string\n    renderers?: PaymentGatewayRendererDescriptor[]\n    /**\n     * @deprecated Use `renderers` and `defaultRendererKey`.\n     */\n    presentation?: 'embedded' | 'redirect' | 'either'\n    /**\n     * @deprecated Use `renderers`.\n     */\n    embeddedRenderers?: string[]\n  }\n}\n\nexport interface EmbeddedPaymentGatewayClientSession {\n  type: 'embedded'\n  rendererKey: string\n  payload?: Record<string, unknown>\n  settings?: Record<string, unknown>\n}\n\nexport interface RedirectPaymentGatewayClientSession {\n  type: 'redirect'\n  redirectUrl: string\n  target?: 'self' | 'top'\n}\n\nexport type PaymentGatewayClientSession =\n  | EmbeddedPaymentGatewayClientSession\n  | RedirectPaymentGatewayClientSession\n\n// \u2500\u2500 Order Amount Reconciliation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface PaymentGatewayScope {\n  organizationId: string\n  tenantId: string\n}\n\nexport interface PaymentOrderTotal {\n  orderId: string\n  currencyCode: string\n  amountDue: number\n}\n\n/**\n * Contract a module that owns orders implements so `payment_gateways` can\n * reconcile a caller-supplied session amount against the authoritative amount\n * due, without depending on that module. Implementations MUST scope the lookup\n * by tenant and organization and MUST return `null` for anything outside the\n * caller's scope, so an out-of-scope order is indistinguishable from a missing\n * one. The `sales` module registers the default implementation under the\n * `paymentOrderTotalResolver` DI name.\n */\nexport interface PaymentOrderTotalResolver {\n  resolveOrderTotal(orderId: string, scope: PaymentGatewayScope): Promise<PaymentOrderTotal | null>\n}\n\n// \u2500\u2500 Input / Output Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface CreateSessionInput {\n  orderId?: string\n  paymentId: string\n  /** Stable operation key for provider-native session creation idempotency. */\n  idempotencyKey?: string\n  tenantId: string\n  organizationId: string\n  amount: number\n  currencyCode: string\n  captureMethod?: 'automatic' | 'manual'\n  paymentTypes?: string[]\n  description?: string\n  successUrl?: string\n  cancelUrl?: string\n  metadata?: Record<string, unknown>\n  credentials: Record<string, unknown>\n  lineItems?: SessionLineItem[]\n  presentation?: PaymentGatewayPresentationRequest\n}\n\nexport interface SessionLineItem {\n  name: string\n  quantity: number\n  unitAmount: number\n  currencyCode: string\n}\n\nexport interface CreateSessionResult {\n  sessionId: string\n  clientSecret?: string\n  redirectUrl?: string\n  status: UnifiedPaymentStatus\n  providerData?: Record<string, unknown>\n  clientSession?: PaymentGatewayClientSession\n}\n\nexport interface CaptureInput {\n  sessionId: string\n  amount?: number\n  credentials: Record<string, unknown>\n  metadata?: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface CaptureResult {\n  status: UnifiedPaymentStatus\n  capturedAmount: number\n  providerData?: Record<string, unknown>\n}\n\nexport interface RefundInput {\n  sessionId: string\n  amount?: number\n  reason?: string\n  credentials: Record<string, unknown>\n  metadata?: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface RefundResult {\n  refundId: string\n  status: UnifiedPaymentStatus\n  refundedAmount: number\n  providerData?: Record<string, unknown>\n}\n\nexport interface CancelInput {\n  sessionId: string\n  reason?: string\n  credentials: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface CancelResult {\n  status: UnifiedPaymentStatus\n  providerData?: Record<string, unknown>\n}\n\nexport interface GetStatusInput {\n  sessionId: string\n  credentials: Record<string, unknown>\n}\n\nexport interface GatewayPaymentStatus {\n  status: UnifiedPaymentStatus\n  amount: number\n  amountReceived: number\n  currencyCode: string\n  providerData?: Record<string, unknown>\n}\n\nexport interface VerifyWebhookInput {\n  rawBody: string | Buffer\n  headers: Record<string, string | string[] | undefined>\n  credentials: Record<string, unknown>\n}\n\nexport interface WebhookEvent {\n  eventType: string\n  eventId: string\n  data: Record<string, unknown>\n  idempotencyKey: string\n  timestamp: Date\n}\n\n// \u2500\u2500 Webhook Handler \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface WebhookHandlerRegistration {\n  handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>\n  queue?: string\n  readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null\n}\n\n// \u2500\u2500 Adapter Registry Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface RegisterAdapterOptions {\n  version?: string\n}\n\n// \u2500\u2500 Registries \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst ADAPTER_REGISTRY_KEY = '__openMercatoPaymentGatewayAdapters__'\nconst WEBHOOK_REGISTRY_KEY = '__openMercatoPaymentGatewayWebhookHandlers__'\nconst DESCRIPTOR_REGISTRY_KEY = '__openMercatoPaymentGatewayDescriptors__'\n\nfunction getAdapterRegistry(): Map<string, GatewayAdapter> {\n  const globalState = globalThis as typeof globalThis & {\n    [ADAPTER_REGISTRY_KEY]?: Map<string, GatewayAdapter>\n  }\n  if (!globalState[ADAPTER_REGISTRY_KEY]) {\n    globalState[ADAPTER_REGISTRY_KEY] = new Map<string, GatewayAdapter>()\n  }\n  return globalState[ADAPTER_REGISTRY_KEY]\n}\n\nfunction getWebhookHandlerRegistry(): Map<string, WebhookHandlerRegistration> {\n  const globalState = globalThis as typeof globalThis & {\n    [WEBHOOK_REGISTRY_KEY]?: Map<string, WebhookHandlerRegistration>\n  }\n  if (!globalState[WEBHOOK_REGISTRY_KEY]) {\n    globalState[WEBHOOK_REGISTRY_KEY] = new Map<string, WebhookHandlerRegistration>()\n  }\n  return globalState[WEBHOOK_REGISTRY_KEY]\n}\n\nfunction getDescriptorRegistry(): Map<string, PaymentGatewayDescriptor> {\n  const globalState = globalThis as typeof globalThis & {\n    [DESCRIPTOR_REGISTRY_KEY]?: Map<string, PaymentGatewayDescriptor>\n  }\n  if (!globalState[DESCRIPTOR_REGISTRY_KEY]) {\n    globalState[DESCRIPTOR_REGISTRY_KEY] = new Map<string, PaymentGatewayDescriptor>()\n  }\n  return globalState[DESCRIPTOR_REGISTRY_KEY]\n}\n\nfunction adapterKey(providerKey: string, version?: string): string {\n  return version ? `${providerKey}:${version}` : providerKey\n}\n\nexport function registerGatewayAdapter(adapter: GatewayAdapter, options?: RegisterAdapterOptions): () => void {\n  const adapterRegistry = getAdapterRegistry()\n  const key = adapterKey(adapter.providerKey, options?.version)\n  adapterRegistry.set(key, adapter)\n  if (options?.version) {\n    // Also register as default if no default exists\n    if (!adapterRegistry.has(adapter.providerKey)) {\n      adapterRegistry.set(adapter.providerKey, adapter)\n    }\n  }\n  return () => {\n    adapterRegistry.delete(key)\n  }\n}\n\nexport function getGatewayAdapter(providerKey: string, version?: string): GatewayAdapter | undefined {\n  const adapterRegistry = getAdapterRegistry()\n  if (version) {\n    return adapterRegistry.get(adapterKey(providerKey, version)) ?? adapterRegistry.get(providerKey)\n  }\n  return adapterRegistry.get(providerKey)\n}\n\nexport function listGatewayAdapters(): GatewayAdapter[] {\n  const adapterRegistry = getAdapterRegistry()\n  const seen = new Set<string>()\n  const result: GatewayAdapter[] = []\n  for (const [key, adapter] of adapterRegistry) {\n    if (!key.includes(':') && !seen.has(adapter.providerKey)) {\n      seen.add(adapter.providerKey)\n      result.push(adapter)\n    }\n  }\n  return result\n}\n\nexport function clearGatewayAdapters(): void {\n  getAdapterRegistry().clear()\n}\n\nexport function registerWebhookHandler(\n  providerKey: string,\n  handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>,\n  options?: {\n    queue?: string\n    readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null\n  },\n): () => void {\n  const webhookHandlerRegistry = getWebhookHandlerRegistry()\n  webhookHandlerRegistry.set(providerKey, {\n    handler,\n    queue: options?.queue,\n    readSessionIdHint: options?.readSessionIdHint,\n  })\n  return () => {\n    webhookHandlerRegistry.delete(providerKey)\n  }\n}\n\nexport function getWebhookHandler(providerKey: string): WebhookHandlerRegistration | undefined {\n  return getWebhookHandlerRegistry().get(providerKey)\n}\n\nexport function clearWebhookHandlers(): void {\n  getWebhookHandlerRegistry().clear()\n}\n\nexport function registerPaymentGatewayDescriptor(descriptor: PaymentGatewayDescriptor): () => void {\n  const descriptorRegistry = getDescriptorRegistry()\n  descriptorRegistry.set(descriptor.providerKey, descriptor)\n  return () => {\n    descriptorRegistry.delete(descriptor.providerKey)\n  }\n}\n\nexport function getPaymentGatewayDescriptor(providerKey: string): PaymentGatewayDescriptor | undefined {\n  return getDescriptorRegistry().get(providerKey)\n}\n\nexport function listPaymentGatewayDescriptors(): PaymentGatewayDescriptor[] {\n  return Array.from(getDescriptorRegistry().values()).sort((left, right) => left.label.localeCompare(right.label))\n}\n\nexport function clearPaymentGatewayDescriptors(): void {\n  getDescriptorRegistry().clear()\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { DEFAULT_WEBHOOK_BODY_LIMIT_BYTES } from '../../lib/webhooks/body'\n\n// \u2500\u2500 Unified Payment Status \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport type UnifiedPaymentStatus =\n  | 'pending'\n  | 'authorized'\n  | 'captured'\n  | 'partially_captured'\n  | 'refunded'\n  | 'partially_refunded'\n  | 'cancelled'\n  | 'failed'\n  | 'expired'\n  | 'unknown'\n\n// \u2500\u2500 GatewayAdapter Interface \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface GatewayAdapter {\n  readonly providerKey: string\n\n  /** Create a payment session / payment intent */\n  createSession(input: CreateSessionInput): Promise<CreateSessionResult>\n\n  /** Capture an authorized payment */\n  capture(input: CaptureInput): Promise<CaptureResult>\n\n  /** Refund a captured payment (full or partial) */\n  refund(input: RefundInput): Promise<RefundResult>\n\n  /** Cancel / void an authorized payment before capture */\n  cancel(input: CancelInput): Promise<CancelResult>\n\n  /** Get current payment status from provider */\n  getStatus(input: GetStatusInput): Promise<GatewayPaymentStatus>\n\n  /** Verify and parse an inbound webhook event */\n  verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent>\n\n  /** Map provider status to unified status */\n  mapStatus(providerStatus: string, eventType?: string): UnifiedPaymentStatus\n}\n\nexport type PaymentGatewayDescriptorFieldType =\n  | 'text'\n  | 'number'\n  | 'select'\n  | 'multiselect'\n  | 'boolean'\n  | 'textarea'\n  | 'secret'\n  | 'url'\n\nexport interface PaymentGatewayDescriptorField {\n  key: string\n  label: string\n  type: PaymentGatewayDescriptorFieldType\n  description?: string\n  required?: boolean\n  options?: Array<{ value: string; label: string }>\n}\n\nexport type PaymentGatewayRendererType = 'embedded' | 'redirect'\n\nexport interface PaymentGatewayRendererDescriptor {\n  key: string\n  label: string\n  type: PaymentGatewayRendererType\n  description?: string\n  supportedPaymentTypes?: '*' | string[]\n  settingsFields?: PaymentGatewayDescriptorField[]\n}\n\nexport interface PaymentGatewayPresentationRequest {\n  mode?: 'auto' | PaymentGatewayRendererType\n  rendererKey?: string\n  rendererSettings?: Record<string, unknown>\n}\n\nexport interface PaymentGatewayDescriptor {\n  providerKey: string\n  label: string\n  sessionConfig?: {\n    fields?: PaymentGatewayDescriptorField[]\n    supportedCurrencies?: '*' | string[]\n    supportedPaymentTypes?: Array<{ value: string; label: string }>\n    defaultRendererKey?: string\n    renderers?: PaymentGatewayRendererDescriptor[]\n    /**\n     * @deprecated Use `renderers` and `defaultRendererKey`.\n     */\n    presentation?: 'embedded' | 'redirect' | 'either'\n    /**\n     * @deprecated Use `renderers`.\n     */\n    embeddedRenderers?: string[]\n  }\n}\n\nexport interface EmbeddedPaymentGatewayClientSession {\n  type: 'embedded'\n  rendererKey: string\n  payload?: Record<string, unknown>\n  settings?: Record<string, unknown>\n}\n\nexport interface RedirectPaymentGatewayClientSession {\n  type: 'redirect'\n  redirectUrl: string\n  target?: 'self' | 'top'\n}\n\nexport type PaymentGatewayClientSession =\n  | EmbeddedPaymentGatewayClientSession\n  | RedirectPaymentGatewayClientSession\n\n// \u2500\u2500 Order Amount Reconciliation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface PaymentGatewayScope {\n  organizationId: string\n  tenantId: string\n}\n\nexport interface PaymentOrderTotal {\n  orderId: string\n  currencyCode: string\n  amountDue: number\n}\n\n/**\n * Contract a module that owns orders implements so `payment_gateways` can\n * reconcile a caller-supplied session amount against the authoritative amount\n * due, without depending on that module. Implementations MUST scope the lookup\n * by tenant and organization and MUST return `null` for anything outside the\n * caller's scope, so an out-of-scope order is indistinguishable from a missing\n * one. The `sales` module registers the default implementation under the\n * `paymentOrderTotalResolver` DI name.\n */\nexport interface PaymentOrderTotalResolver {\n  resolveOrderTotal(orderId: string, scope: PaymentGatewayScope): Promise<PaymentOrderTotal | null>\n}\n\n// \u2500\u2500 Input / Output Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface CreateSessionInput {\n  orderId?: string\n  paymentId: string\n  /** Stable operation key for provider-native session creation idempotency. */\n  idempotencyKey?: string\n  tenantId: string\n  organizationId: string\n  amount: number\n  currencyCode: string\n  captureMethod?: 'automatic' | 'manual'\n  paymentTypes?: string[]\n  description?: string\n  successUrl?: string\n  cancelUrl?: string\n  metadata?: Record<string, unknown>\n  credentials: Record<string, unknown>\n  lineItems?: SessionLineItem[]\n  presentation?: PaymentGatewayPresentationRequest\n}\n\nexport interface SessionLineItem {\n  name: string\n  quantity: number\n  unitAmount: number\n  currencyCode: string\n}\n\nexport interface CreateSessionResult {\n  sessionId: string\n  clientSecret?: string\n  redirectUrl?: string\n  status: UnifiedPaymentStatus\n  providerData?: Record<string, unknown>\n  clientSession?: PaymentGatewayClientSession\n}\n\nexport interface CaptureInput {\n  sessionId: string\n  amount?: number\n  credentials: Record<string, unknown>\n  metadata?: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface CaptureResult {\n  status: UnifiedPaymentStatus\n  capturedAmount: number\n  providerData?: Record<string, unknown>\n}\n\nexport interface RefundInput {\n  sessionId: string\n  amount?: number\n  reason?: string\n  credentials: Record<string, unknown>\n  metadata?: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface RefundResult {\n  refundId: string\n  status: UnifiedPaymentStatus\n  refundedAmount: number\n  providerData?: Record<string, unknown>\n}\n\nexport interface CancelInput {\n  sessionId: string\n  reason?: string\n  credentials: Record<string, unknown>\n  idempotencyKey?: string\n}\n\nexport interface CancelResult {\n  status: UnifiedPaymentStatus\n  providerData?: Record<string, unknown>\n}\n\nexport interface GetStatusInput {\n  sessionId: string\n  credentials: Record<string, unknown>\n}\n\nexport interface GatewayPaymentStatus {\n  status: UnifiedPaymentStatus\n  amount: number\n  amountReceived: number\n  currencyCode: string\n  providerData?: Record<string, unknown>\n}\n\nexport interface VerifyWebhookInput {\n  rawBody: string | Buffer\n  headers: Record<string, string | string[] | undefined>\n  credentials: Record<string, unknown>\n}\n\nexport interface WebhookEvent {\n  eventType: string\n  eventId: string\n  data: Record<string, unknown>\n  idempotencyKey: string\n  timestamp: Date\n}\n\n// \u2500\u2500 Webhook Handler \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface WebhookHandlerRegistration {\n  handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>\n  queue?: string\n  readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null\n  maxBodyBytes?: number\n}\n\n// \u2500\u2500 Adapter Registry Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface RegisterAdapterOptions {\n  version?: string\n}\n\n// \u2500\u2500 Registries \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst ADAPTER_REGISTRY_KEY = '__openMercatoPaymentGatewayAdapters__'\nconst WEBHOOK_REGISTRY_KEY = '__openMercatoPaymentGatewayWebhookHandlers__'\nconst DESCRIPTOR_REGISTRY_KEY = '__openMercatoPaymentGatewayDescriptors__'\n\nfunction getAdapterRegistry(): Map<string, GatewayAdapter> {\n  const globalState = globalThis as typeof globalThis & {\n    [ADAPTER_REGISTRY_KEY]?: Map<string, GatewayAdapter>\n  }\n  if (!globalState[ADAPTER_REGISTRY_KEY]) {\n    globalState[ADAPTER_REGISTRY_KEY] = new Map<string, GatewayAdapter>()\n  }\n  return globalState[ADAPTER_REGISTRY_KEY]\n}\n\nfunction getWebhookHandlerRegistry(): Map<string, WebhookHandlerRegistration> {\n  const globalState = globalThis as typeof globalThis & {\n    [WEBHOOK_REGISTRY_KEY]?: Map<string, WebhookHandlerRegistration>\n  }\n  if (!globalState[WEBHOOK_REGISTRY_KEY]) {\n    globalState[WEBHOOK_REGISTRY_KEY] = new Map<string, WebhookHandlerRegistration>()\n  }\n  return globalState[WEBHOOK_REGISTRY_KEY]\n}\n\nfunction getDescriptorRegistry(): Map<string, PaymentGatewayDescriptor> {\n  const globalState = globalThis as typeof globalThis & {\n    [DESCRIPTOR_REGISTRY_KEY]?: Map<string, PaymentGatewayDescriptor>\n  }\n  if (!globalState[DESCRIPTOR_REGISTRY_KEY]) {\n    globalState[DESCRIPTOR_REGISTRY_KEY] = new Map<string, PaymentGatewayDescriptor>()\n  }\n  return globalState[DESCRIPTOR_REGISTRY_KEY]\n}\n\nfunction adapterKey(providerKey: string, version?: string): string {\n  return version ? `${providerKey}:${version}` : providerKey\n}\n\nexport function registerGatewayAdapter(adapter: GatewayAdapter, options?: RegisterAdapterOptions): () => void {\n  const adapterRegistry = getAdapterRegistry()\n  const key = adapterKey(adapter.providerKey, options?.version)\n  adapterRegistry.set(key, adapter)\n  if (options?.version) {\n    // Also register as default if no default exists\n    if (!adapterRegistry.has(adapter.providerKey)) {\n      adapterRegistry.set(adapter.providerKey, adapter)\n    }\n  }\n  return () => {\n    adapterRegistry.delete(key)\n  }\n}\n\nexport function getGatewayAdapter(providerKey: string, version?: string): GatewayAdapter | undefined {\n  const adapterRegistry = getAdapterRegistry()\n  if (version) {\n    return adapterRegistry.get(adapterKey(providerKey, version)) ?? adapterRegistry.get(providerKey)\n  }\n  return adapterRegistry.get(providerKey)\n}\n\nexport function listGatewayAdapters(): GatewayAdapter[] {\n  const adapterRegistry = getAdapterRegistry()\n  const seen = new Set<string>()\n  const result: GatewayAdapter[] = []\n  for (const [key, adapter] of adapterRegistry) {\n    if (!key.includes(':') && !seen.has(adapter.providerKey)) {\n      seen.add(adapter.providerKey)\n      result.push(adapter)\n    }\n  }\n  return result\n}\n\nexport function clearGatewayAdapters(): void {\n  getAdapterRegistry().clear()\n}\n\nexport function registerWebhookHandler(\n  providerKey: string,\n  handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>,\n  options?: {\n    queue?: string\n    readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null\n    maxBodyBytes?: number\n  },\n): () => void {\n  if (\n    options?.maxBodyBytes !== undefined\n    && (!Number.isSafeInteger(options.maxBodyBytes)\n      || options.maxBodyBytes <= 0\n      || options.maxBodyBytes > DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)\n  ) {\n    throw new Error(\n      `[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer no greater than ${DEFAULT_WEBHOOK_BODY_LIMIT_BYTES}`,\n    )\n  }\n  const webhookHandlerRegistry = getWebhookHandlerRegistry()\n  webhookHandlerRegistry.set(providerKey, {\n    handler,\n    queue: options?.queue,\n    readSessionIdHint: options?.readSessionIdHint,\n    maxBodyBytes: options?.maxBodyBytes,\n  })\n  return () => {\n    webhookHandlerRegistry.delete(providerKey)\n  }\n}\n\nexport function getWebhookHandler(providerKey: string): WebhookHandlerRegistration | undefined {\n  return getWebhookHandlerRegistry().get(providerKey)\n}\n\nexport function clearWebhookHandlers(): void {\n  getWebhookHandlerRegistry().clear()\n}\n\nexport function registerPaymentGatewayDescriptor(descriptor: PaymentGatewayDescriptor): () => void {\n  const descriptorRegistry = getDescriptorRegistry()\n  descriptorRegistry.set(descriptor.providerKey, descriptor)\n  return () => {\n    descriptorRegistry.delete(descriptor.providerKey)\n  }\n}\n\nexport function getPaymentGatewayDescriptor(providerKey: string): PaymentGatewayDescriptor | undefined {\n  return getDescriptorRegistry().get(providerKey)\n}\n\nexport function listPaymentGatewayDescriptors(): PaymentGatewayDescriptor[] {\n  return Array.from(getDescriptorRegistry().values()).sort((left, right) => left.label.localeCompare(right.label))\n}\n\nexport function clearPaymentGatewayDescriptors(): void {\n  getDescriptorRegistry().clear()\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/widgets/extension-points.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/widgets/extension-points.ts"],
-  "sourcesContent": ["export type ExtensionHostFamily =\n  | 'generic'\n  | 'menu'\n  | 'data-table'\n  | 'crud-form'\n  | 'detail'\n  | 'portal-page'\n  | 'component-handle'\n  | 'entity'\n  | 'api-route'\n  | 'command'\n  | 'event'\n  | 'query-lifecycle'\n  | 'dashboard'\n  | 'notification'\n  | 'integration'\n  | 'specialized-registry'\n  | 'module-override'\n\nexport type ExtensionHostCapability =\n  | 'render-widget'\n  | 'headless-widget'\n  | 'menu-item'\n  | 'column-widget'\n  | 'row-action'\n  | 'bulk-action'\n  | 'filter-widget'\n  | 'toolbar-widget'\n  | 'field-widget'\n  | 'lifecycle-handler'\n  | 'component-replacement'\n  | 'response-enricher'\n  | 'query-enricher'\n  | 'api-interceptor'\n  | 'command-interceptor'\n  | 'mutation-guard'\n  | 'entity-extension'\n  | 'async-subscriber'\n  | 'sync-subscriber'\n  | 'browser-client'\n  | 'browser-portal'\n  | 'registry-contribution'\n  | 'module-override'\n\nexport type ExtensionHostActivation = 'always' | 'host-opt-in' | 'caller-opt-in' | 'feature-gated'\n\nexport type ExtensionPointPatternParameter = {\n  source: string\n  pattern?: string\n}\n\ntype ExtensionHostDeclarationBase = {\n  source: string\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  aliases?: readonly string[]\n  fallbacks?: readonly string[]\n}\n\ntype InjectionExtensionHostDeclarationBase = ExtensionHostDeclarationBase & {\n  family: Exclude<ExtensionHostFamily, 'data-table' | 'crud-form' | 'component-handle'>\n  supported: readonly ExtensionHostCapability[]\n}\n\nexport type InjectionExtensionHostDeclaration = InjectionExtensionHostDeclarationBase & (\n  | {\n      spotId: string\n      pattern?: never\n      parameters?: never\n    }\n  | {\n      spotId?: never\n      pattern: string\n      parameters: Readonly<Record<string, ExtensionPointPatternParameter>>\n    }\n)\n\nexport type DataTableExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'data-table'\n  tableId: string\n  baseSpotId?: string\n}\n\nexport type CrudFormExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'crud-form'\n  entityId: string\n  spotId?: string\n}\n\nexport type ComponentExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'component-handle'\n  componentId: string\n  propsContract?: string\n}\n\nexport type ModuleExtensionHostDeclaration =\n  | InjectionExtensionHostDeclaration\n  | DataTableExtensionHostDeclaration\n  | CrudFormExtensionHostDeclaration\n  | ComponentExtensionHostDeclaration\n\nexport type ModuleExtensionPoints<\n  TModuleId extends string = string,\n  THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>> = Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n> = {\n  moduleId: TModuleId\n  hosts: THosts\n}\n\nexport function defineModuleExtensionPoints<\n  const TModuleId extends string,\n  const THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n>(declaration: ModuleExtensionPoints<TModuleId, THosts>): ModuleExtensionPoints<TModuleId, THosts> {\n  return Object.freeze({\n    ...declaration,\n    hosts: Object.freeze({ ...declaration.hosts }),\n  })\n}\n\nexport function injectionExtensionHost<const TDeclaration extends InjectionExtensionHostDeclaration>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration> {\n  const hasExactId = typeof declaration.spotId === 'string' && declaration.spotId.length > 0\n  const hasPattern = typeof declaration.pattern === 'string' && declaration.pattern.length > 0\n  if (hasExactId === hasPattern) {\n    throw new Error('[internal] injection extension hosts require exactly one of spotId or pattern')\n  }\n  if (hasPattern && (!declaration.parameters || Object.keys(declaration.parameters).length === 0)) {\n    throw new Error('[internal] patterned injection extension hosts require named parameters')\n  }\n  return Object.freeze({ ...declaration })\n}\n\nexport function dataTableExtensionHost<\n  const TDeclaration extends Omit<DataTableExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'data-table' }> {\n  return Object.freeze({ family: 'data-table', ...declaration })\n}\n\nexport function crudFormExtensionHost<\n  const TDeclaration extends Omit<CrudFormExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'crud-form' }> {\n  return Object.freeze({ family: 'crud-form', ...declaration })\n}\n\nexport function componentExtensionHost<\n  const TDeclaration extends Omit<ComponentExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'component-handle' }> {\n  return Object.freeze({ family: 'component-handle', ...declaration })\n}\n\nexport type BoundExtensionSurface = {\n  key: string\n  suffix: string | null\n  capabilities: readonly ExtensionHostCapability[]\n  bound: boolean\n  phases?: readonly string[]\n  operations?: readonly string[]\n}\n\nexport const DATA_TABLE_EXTENSION_SURFACES = [\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: true },\n  { key: 'toolbar', suffix: 'toolbar', capabilities: ['toolbar-widget'], bound: true },\n  { key: 'searchTrailing', suffix: 'search-trailing', capabilities: ['render-widget'], bound: true },\n  { key: 'columns', suffix: 'columns', capabilities: ['column-widget'], bound: true },\n  { key: 'rowActions', suffix: 'row-actions', capabilities: ['row-action'], bound: true },\n  { key: 'bulkActions', suffix: 'bulk-actions', capabilities: ['bulk-action'], bound: true },\n  { key: 'filters', suffix: 'filters', capabilities: ['filter-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'emptyState', suffix: 'empty-state', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_EXTENSION_SURFACES = [\n  { key: 'base', suffix: null, capabilities: ['render-widget', 'lifecycle-handler'], bound: true },\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'fields', suffix: 'fields', capabilities: ['field-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'beforeFields', suffix: 'before-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'afterFields', suffix: 'after-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: false },\n  { key: 'sidebar', suffix: 'sidebar', capabilities: ['render-widget'], bound: false },\n  { key: 'group', suffix: 'group:{groupId}', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldBefore', suffix: 'field:{fieldId}:before', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldAfter', suffix: 'field:{fieldId}:after', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_LIFECYCLE_PHASES = [\n  'transformValidation',\n  'transformDisplayData',\n  'onBeforeNavigate',\n  'onAppEvent',\n  'onVisibilityChange',\n  'onBeforeDelete',\n  'onDelete',\n  'onAfterDelete',\n  'onDeleteError',\n  'onFieldChange',\n  'transformFormData',\n  'onBeforeSave',\n  'onSave',\n  'onAfterSave',\n] as const\n\nexport const CRUD_FORM_OPERATIONS = ['create', 'update', 'delete'] as const\n\nexport function dataTableExtensionSpotId(tableId: string, suffix?: string): string {\n  return suffix ? `data-table:${tableId}:${suffix}` : `data-table:${tableId}`\n}\n\nexport function crudFormExtensionSpotId(entityId: string, suffix?: string): string {\n  return suffix ? `crud-form:${entityId}:${suffix}` : `crud-form:${entityId}`\n}\n\nexport function extensionSpotChildId(spotId: string, suffix: string): string {\n  return `${spotId}:${suffix}`\n}\n\nexport function resolveExtensionPointPattern(\n  pattern: string,\n  parameters: Readonly<Record<string, string>>,\n): string {\n  return pattern.replace(/\\{([^}]+)\\}/g, (token, parameterName: string) => parameters[parameterName] ?? token)\n}\n\nexport type ModuleExtensionSurfaceFacts = {\n  hosts: ModuleExtensionHostFact[]\n  contributions: ModuleExtensionContributionFact[]\n  unresolved: ModuleExtensionUnresolvedFact[]\n}\n\nexport type ModuleExtensionHostFact = {\n  key: string\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref'\n  family: ExtensionHostFamily\n  ownerModule: string\n  capabilities: ExtensionHostCapability[]\n  phases?: string[]\n  operations?: string[]\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  bound: boolean\n  stability: 'frozen' | 'stable'\n  source:\n    | { kind: 'declaration'; path: string; symbol: string }\n    | { kind: 'fact-ref'; factSection: string; factKey: string }\n    | { kind: 'framework'; path: string; symbol: string }\n  aliases?: string[]\n  patternParameters?: Record<string, ExtensionPointPatternParameter>\n  fallbacks?: string[]\n}\n\nexport type ModuleExtensionTargetFact = {\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref' | 'optional-external' | 'unresolved'\n  factRef?: { factSection: string; factKey: string }\n  optionalOwnerPackage?: string\n}\n\nexport type ModuleExtensionContributionBase = {\n  id: string\n  targets: ModuleExtensionTargetFact[]\n  phases?: string[]\n  operations?: string[]\n  features?: string[]\n  scopeContract: string\n  activation?: ExtensionHostActivation\n  placement?: { relativeTo?: string; position?: 'first' | 'last' | 'before' | 'after'; priority?: number }\n  roundTripId?: string\n  override?: { domain: string; key: string; mode: 'disable-replace' | 'replace' | 'additive' }\n  source: { path: string; symbol?: string }\n}\n\nexport type ModuleExtensionContributionFact = ModuleExtensionContributionBase & (\n  | {\n      kind: 'widget'\n      details: {\n        payload: 'render' | 'headless' | 'menu' | 'dashboard' | 'notification' | 'integration'\n        registryKey: string\n        itemIds?: string[]\n        labelKeys?: string[]\n        contextContract?: string\n        dataContract?: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'data-table'\n      details: {\n        payload: 'column' | 'row-action' | 'bulk-action' | 'filter' | 'toolbar' | 'render'\n        tableId: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'crud-form'\n      details: {\n        payload: 'render' | 'field' | 'lifecycle-handler'\n        entityId: string\n        fieldIds?: string[]\n        groupIds?: string[]\n        requestHeaderCapability: boolean\n      }\n    }\n  | {\n      kind: 'component-override'\n      details: { handle: string; mode: 'replace' | 'wrapper' | 'props'; propsContract: string }\n    }\n  | {\n      kind: 'response-enricher'\n      details: {\n        targetEntity: string\n        surfaces: Array<'list' | 'detail'>\n        timeoutMs: number\n        fallback: 'none' | 'configured'\n        critical: boolean\n        cachePosture: 'record-pure' | 'rerun-on-list-cache-hit'\n        queryEngine?: {\n          engines: string[]\n          applyOn: Array<'list' | 'detail'>\n          activation: 'caller-opt-in'\n        }\n      }\n    }\n  | {\n      kind: 'api-interceptor'\n      details: {\n        route: string\n        methods: string[]\n        phases: Array<'before' | 'after'>\n        activation: 'crud-pipeline' | 'custom-route-bridge'\n        timeoutMs: number\n        failurePosture: 'fail-closed' | 'fallback'\n      }\n    }\n  | {\n      kind: 'command-interceptor'\n      details: {\n        targetCommand: string\n        phases: Array<'before-execute' | 'after-execute' | 'before-undo' | 'after-undo'>\n      }\n    }\n  | {\n      kind: 'mutation-guard'\n      details: {\n        entityId: string\n        operations: Array<'create' | 'update' | 'delete'>\n        capabilities: Array<'block' | 'rewrite' | 'after-success'>\n        optimisticLock: 'preserved'\n      }\n    }\n  | {\n      kind: 'entity-extension'\n      details: {\n        hostEntityId: string\n        extensionEntityId: string\n        linkId: string\n        scopeContract: string\n        orphanContract: string\n      }\n    }\n  | {\n      kind: 'subscriber'\n      details: {\n        event: string\n        subscriberId: string\n        persistent: boolean\n        sync: boolean\n        priority?: number\n      }\n    }\n  | {\n      kind: 'browser-reaction'\n      details: {\n        transports: Array<'client' | 'portal' | 'notification-effect'>\n        hooks: string[]\n        audienceScopeContract: string\n        maxPayloadBytes?: number\n        dedupWindowMs?: number\n      }\n    }\n  | {\n      kind: 'specialized-registry'\n      details: {\n        registry: 'notification' | 'integration' | 'search' | 'vector' | 'ai' | 'payment' | 'shipping' | 'currency' | 'workflow'\n        registryId: string\n        specialistRoute: string\n      }\n    }\n  | {\n      kind: 'module-override'\n      details: {\n        domain: string\n        key: string\n        mode: 'disable-replace' | 'replace' | 'additive'\n      }\n    }\n)\n\nexport type ModuleExtensionUnresolvedFact = {\n  key: string\n  source: { path: string; symbol?: string }\n  reason:\n    | 'unclassified-binding'\n    | 'unbound-declaration'\n    | 'dynamic-without-pattern'\n    | 'unresolved-first-party-target'\n}\n"],
+  "sourcesContent": ["export type ExtensionHostFamily =\n  | 'generic'\n  | 'menu'\n  | 'data-table'\n  | 'crud-form'\n  | 'detail'\n  | 'portal-page'\n  | 'component-handle'\n  | 'entity'\n  | 'api-route'\n  | 'command'\n  | 'event'\n  | 'query-lifecycle'\n  | 'dashboard'\n  | 'notification'\n  | 'integration'\n  | 'specialized-registry'\n  | 'module-override'\n\nexport type ExtensionHostCapability =\n  | 'render-widget'\n  | 'headless-widget'\n  | 'menu-item'\n  | 'column-widget'\n  | 'row-action'\n  | 'bulk-action'\n  | 'filter-widget'\n  | 'toolbar-widget'\n  | 'field-widget'\n  | 'lifecycle-handler'\n  | 'component-replacement'\n  | 'response-enricher'\n  | 'query-enricher'\n  | 'api-interceptor'\n  | 'command-interceptor'\n  | 'mutation-guard'\n  | 'entity-extension'\n  | 'async-subscriber'\n  | 'sync-subscriber'\n  | 'browser-client'\n  | 'browser-portal'\n  | 'registry-contribution'\n  | 'module-override'\n\nexport type ExtensionHostActivation = 'always' | 'host-opt-in' | 'caller-opt-in' | 'feature-gated'\n\nexport type ExtensionPointPatternParameter = {\n  source: string\n  pattern?: string\n}\n\ntype ExtensionHostDeclarationBase = {\n  source: string\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  aliases?: readonly string[]\n  fallbacks?: readonly string[]\n}\n\ntype InjectionExtensionHostDeclarationBase = ExtensionHostDeclarationBase & {\n  family: Exclude<ExtensionHostFamily, 'data-table' | 'crud-form' | 'component-handle'>\n  supported: readonly ExtensionHostCapability[]\n}\n\nexport type InjectionExtensionHostDeclaration = InjectionExtensionHostDeclarationBase & (\n  | {\n      spotId: string\n      pattern?: never\n      parameters?: never\n    }\n  | {\n      spotId?: never\n      pattern: string\n      parameters: Readonly<Record<string, ExtensionPointPatternParameter>>\n    }\n)\n\nexport type DataTableExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'data-table'\n  tableId: string\n  baseSpotId?: string\n}\n\nexport type CrudFormExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'crud-form'\n  entityId: string\n  spotId?: string\n}\n\nexport type ComponentExtensionHostDeclaration = ExtensionHostDeclarationBase & {\n  family: 'component-handle'\n  componentId: string\n  propsContract?: string\n}\n\nexport type ModuleExtensionHostDeclaration =\n  | InjectionExtensionHostDeclaration\n  | DataTableExtensionHostDeclaration\n  | CrudFormExtensionHostDeclaration\n  | ComponentExtensionHostDeclaration\n\nexport type ModuleExtensionPoints<\n  TModuleId extends string = string,\n  THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>> = Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n> = {\n  moduleId: TModuleId\n  hosts: THosts\n}\n\nexport function defineModuleExtensionPoints<\n  const TModuleId extends string,\n  const THosts extends Readonly<Record<string, ModuleExtensionHostDeclaration>>,\n>(declaration: ModuleExtensionPoints<TModuleId, THosts>): ModuleExtensionPoints<TModuleId, THosts> {\n  return Object.freeze({\n    ...declaration,\n    hosts: Object.freeze({ ...declaration.hosts }),\n  })\n}\n\nexport function injectionExtensionHost<const TDeclaration extends InjectionExtensionHostDeclaration>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration> {\n  const hasExactId = typeof declaration.spotId === 'string' && declaration.spotId.length > 0\n  const hasPattern = typeof declaration.pattern === 'string' && declaration.pattern.length > 0\n  if (hasExactId === hasPattern) {\n    throw new Error('[internal] injection extension hosts require exactly one of spotId or pattern')\n  }\n  if (hasPattern && (!declaration.parameters || Object.keys(declaration.parameters).length === 0)) {\n    throw new Error('[internal] patterned injection extension hosts require named parameters')\n  }\n  return Object.freeze({ ...declaration })\n}\n\nexport function dataTableExtensionHost<\n  const TDeclaration extends Omit<DataTableExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'data-table' }> {\n  return Object.freeze({ family: 'data-table', ...declaration })\n}\n\nexport function crudFormExtensionHost<\n  const TDeclaration extends Omit<CrudFormExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'crud-form' }> {\n  return Object.freeze({ family: 'crud-form', ...declaration })\n}\n\nexport function componentExtensionHost<\n  const TDeclaration extends Omit<ComponentExtensionHostDeclaration, 'family'>,\n>(\n  declaration: TDeclaration,\n): Readonly<TDeclaration & { family: 'component-handle' }> {\n  return Object.freeze({ family: 'component-handle', ...declaration })\n}\n\nexport type BoundExtensionSurface = {\n  key: string\n  suffix: string | null\n  capabilities: readonly ExtensionHostCapability[]\n  bound: boolean\n  phases?: readonly string[]\n  operations?: readonly string[]\n}\n\nexport const DATA_TABLE_EXTENSION_SURFACES = [\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: true },\n  { key: 'toolbar', suffix: 'toolbar', capabilities: ['toolbar-widget'], bound: true },\n  { key: 'searchTrailing', suffix: 'search-trailing', capabilities: ['render-widget'], bound: true },\n  { key: 'columns', suffix: 'columns', capabilities: ['column-widget'], bound: true },\n  { key: 'rowActions', suffix: 'row-actions', capabilities: ['row-action'], bound: true },\n  { key: 'bulkActions', suffix: 'bulk-actions', capabilities: ['bulk-action'], bound: true },\n  { key: 'filters', suffix: 'filters', capabilities: ['filter-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'emptyState', suffix: 'empty-state', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_EXTENSION_SURFACES = [\n  { key: 'base', suffix: null, capabilities: ['render-widget', 'lifecycle-handler'], bound: true },\n  { key: 'header', suffix: 'header', capabilities: ['render-widget'], bound: true },\n  { key: 'fields', suffix: 'fields', capabilities: ['field-widget'], bound: true },\n  { key: 'replacement', suffix: null, capabilities: ['component-replacement'], bound: true },\n  { key: 'beforeFields', suffix: 'before-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'afterFields', suffix: 'after-fields', capabilities: ['render-widget'], bound: false },\n  { key: 'footer', suffix: 'footer', capabilities: ['render-widget'], bound: false },\n  { key: 'sidebar', suffix: 'sidebar', capabilities: ['render-widget'], bound: false },\n  { key: 'group', suffix: 'group:{groupId}', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldBefore', suffix: 'field:{fieldId}:before', capabilities: ['render-widget'], bound: false },\n  { key: 'fieldAfter', suffix: 'field:{fieldId}:after', capabilities: ['render-widget'], bound: false },\n] as const satisfies readonly BoundExtensionSurface[]\n\nexport const CRUD_FORM_LIFECYCLE_PHASES = [\n  'transformValidation',\n  'transformDisplayData',\n  'onBeforeNavigate',\n  'onAppEvent',\n  'onVisibilityChange',\n  'onBeforeDelete',\n  'onDelete',\n  'onAfterDelete',\n  'onDeleteError',\n  'onFieldChange',\n  'transformFormData',\n  'onBeforeSave',\n  'onSave',\n  'onAfterSave',\n] as const\n\nexport const CRUD_FORM_OPERATIONS = ['create', 'update', 'delete'] as const\n\nexport function dataTableExtensionSpotId(tableId: string, suffix?: string): string {\n  return suffix ? `data-table:${tableId}:${suffix}` : `data-table:${tableId}`\n}\n\nexport function crudFormExtensionSpotId(entityId: string, suffix?: string): string {\n  return suffix ? `crud-form:${entityId}:${suffix}` : `crud-form:${entityId}`\n}\n\nexport function extensionSpotChildId(spotId: string, suffix: string): string {\n  return `${spotId}:${suffix}`\n}\n\nexport function resolveExtensionPointPattern(\n  pattern: string,\n  parameters: Readonly<Record<string, string>>,\n): string {\n  return pattern.replace(/\\{([^}]+)\\}/g, (token, parameterName: string) => parameters[parameterName] ?? token)\n}\n\n/**\n * Portable, structural copy of the CLI provenance source reference\n * (`ModuleFactSourceRef` in `packages/cli/.../module-facts.ts`). Redefined here\n * \u2014 rather than imported \u2014 so `@open-mercato/shared` keeps zero dependency on\n * `@open-mercato/cli`. Field names are kept byte-identical so the two are\n * assignable across the package boundary.\n */\nexport type ModuleFactSourceRef = {\n  sourcePath: string\n  exportName?: string\n  line?: number\n}\n\n/** Portable, structural copy of the CLI provenance fact reference. */\nexport type ModuleFactRef = {\n  factSection: string\n  factKey: string\n}\n\nexport type ModuleExtensionContributionKind = ModuleExtensionContributionFact['kind']\n\nexport type ModuleExtensionActivationKind =\n  | 'crud-response-enricher'\n  | 'query-enricher'\n  | 'mutation-guard'\n  | 'api-interceptor-bridge'\n  | 'command-interceptor-bridge'\n  | 'widget-injection-consumer'\n  | 'component-extension-consumer'\n  | 'dashboard-host-consumer'\n\nexport type ModuleExtensionTargetRef = {\n  kind:\n    | 'module'\n    | 'entity'\n    | 'api-route'\n    | 'command'\n    | 'widget-spot'\n    | 'component'\n    | 'event'\n    | 'notification'\n    | 'wildcard'\n  id: string\n  moduleId?: string\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n}\n\nexport type ModuleExtensionActivation = {\n  id: string\n  kind: ModuleExtensionActivationKind\n  host: ModuleExtensionTargetRef\n  contributionKinds: ModuleExtensionContributionKind[]\n  phases?: string[]\n  /**\n   * Mutation operations the call site guards, when statically declared. A\n   * contribution declaring only other operations is not bound by this activation.\n   */\n  operations?: string[]\n  source: ModuleFactSourceRef\n  bridge?: ModuleFactRef\n}\n\nexport type ModuleExtensionResolution =\n  | 'bound'\n  | 'capability-only'\n  | 'optional-target-missing'\n  | 'wildcard'\n  | 'unresolved'\n\nexport type ModuleIncomingExtensionRef = {\n  contributionId: string\n  contributionKind: ModuleExtensionContributionKind\n  contributorModuleId: string\n  target: ModuleExtensionTargetRef\n  activationId?: string\n  resolution: ModuleExtensionResolution\n  source: ModuleFactSourceRef\n}\n\nexport type ModuleContributionResolution = {\n  contributionId: string\n  target: ModuleExtensionTargetRef\n  resolution: ModuleExtensionResolution\n  activationIds: string[]\n}\n\n/**\n * Additive, optional bidirectional-topology fields layered on top of the\n * existing extension-surface facts. Every field is optional so legacy consumers\n * and pre-existing generated output remain byte-compatible.\n */\nexport type ModuleExtensionSurfaceFactsAdditions = {\n  activations?: ModuleExtensionActivation[]\n  incoming?: ModuleIncomingExtensionRef[]\n  contributionResolutions?: ModuleContributionResolution[]\n}\n\nexport type ModuleExtensionSurfaceFacts = {\n  hosts: ModuleExtensionHostFact[]\n  contributions: ModuleExtensionContributionFact[]\n  unresolved: ModuleExtensionUnresolvedFact[]\n} & ModuleExtensionSurfaceFactsAdditions\n\nexport type ModuleExtensionHostFact = {\n  key: string\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref'\n  family: ExtensionHostFamily\n  ownerModule: string\n  capabilities: ExtensionHostCapability[]\n  phases?: string[]\n  operations?: string[]\n  contextContract?: string\n  dataContract?: string\n  scopeContract?: string\n  runtimeContract?: string\n  activation?: ExtensionHostActivation\n  bound: boolean\n  stability: 'frozen' | 'stable'\n  source:\n    | { kind: 'declaration'; path: string; symbol: string }\n    | { kind: 'fact-ref'; factSection: string; factKey: string }\n    | { kind: 'framework'; path: string; symbol: string }\n  aliases?: string[]\n  patternParameters?: Record<string, ExtensionPointPatternParameter>\n  fallbacks?: string[]\n}\n\nexport type ModuleExtensionTargetFact = {\n  id: string\n  resolution: 'exact' | 'pattern' | 'framework' | 'fact-ref' | 'optional-external' | 'unresolved'\n  factRef?: { factSection: string; factKey: string }\n  optionalOwnerPackage?: string\n}\n\nexport type ModuleExtensionContributionBase = {\n  id: string\n  targets: ModuleExtensionTargetFact[]\n  phases?: string[]\n  operations?: string[]\n  features?: string[]\n  scopeContract: string\n  activation?: ExtensionHostActivation\n  placement?: { relativeTo?: string; position?: 'first' | 'last' | 'before' | 'after'; priority?: number }\n  roundTripId?: string\n  override?: { domain: string; key: string; mode: 'disable-replace' | 'replace' | 'additive' }\n  source: { path: string; symbol?: string }\n}\n\nexport type ModuleExtensionContributionFact = ModuleExtensionContributionBase & (\n  | {\n      kind: 'widget'\n      details: {\n        payload: 'render' | 'headless' | 'menu' | 'dashboard' | 'notification' | 'integration'\n        registryKey: string\n        itemIds?: string[]\n        labelKeys?: string[]\n        contextContract?: string\n        dataContract?: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'data-table'\n      details: {\n        payload: 'column' | 'row-action' | 'bulk-action' | 'filter' | 'toolbar' | 'render'\n        tableId: string\n        executionGuard: 'host' | 'contribution' | 'both'\n      }\n    }\n  | {\n      kind: 'crud-form'\n      details: {\n        payload: 'render' | 'field' | 'lifecycle-handler'\n        entityId: string\n        fieldIds?: string[]\n        groupIds?: string[]\n        requestHeaderCapability: boolean\n      }\n    }\n  | {\n      kind: 'component-override'\n      details: { handle: string; mode: 'replace' | 'wrapper' | 'props'; propsContract: string }\n    }\n  | {\n      kind: 'response-enricher'\n      details: {\n        targetEntity: string\n        surfaces: Array<'list' | 'detail'>\n        timeoutMs: number\n        fallback: 'none' | 'configured'\n        critical: boolean\n        cachePosture: 'record-pure' | 'rerun-on-list-cache-hit'\n        queryEngine?: {\n          engines: string[]\n          applyOn: Array<'list' | 'detail'>\n          activation: 'caller-opt-in'\n        }\n      }\n    }\n  | {\n      kind: 'api-interceptor'\n      details: {\n        route: string\n        methods: string[]\n        phases: Array<'before' | 'after'>\n        activation: 'crud-pipeline' | 'custom-route-bridge'\n        timeoutMs: number\n        failurePosture: 'fail-closed' | 'fallback'\n      }\n    }\n  | {\n      kind: 'command-interceptor'\n      details: {\n        targetCommand: string\n        phases: Array<'before-execute' | 'after-execute' | 'before-undo' | 'after-undo'>\n      }\n    }\n  | {\n      kind: 'mutation-guard'\n      details: {\n        entityId: string\n        operations: Array<'create' | 'update' | 'delete'>\n        capabilities: Array<'block' | 'rewrite' | 'after-success'>\n        optimisticLock: 'preserved'\n      }\n    }\n  | {\n      kind: 'entity-extension'\n      details: {\n        hostEntityId: string\n        extensionEntityId: string\n        linkId: string\n        scopeContract: string\n        orphanContract: string\n      }\n    }\n  | {\n      kind: 'subscriber'\n      details: {\n        event: string\n        subscriberId: string\n        persistent: boolean\n        sync: boolean\n        priority?: number\n      }\n    }\n  | {\n      kind: 'browser-reaction'\n      details: {\n        transports: Array<'client' | 'portal' | 'notification-effect'>\n        hooks: string[]\n        audienceScopeContract: string\n        maxPayloadBytes?: number\n        dedupWindowMs?: number\n        /**\n         * Statically declared handler id. Runtime keys `notifications.handlers`\n         * overrides by it, so it is absent when the module declares no id (such a\n         * handler cannot be overridden).\n         */\n        overrideKey?: string\n      }\n    }\n  | {\n      kind: 'specialized-registry'\n      details: {\n        registry: 'notification' | 'integration' | 'search' | 'vector' | 'ai' | 'payment' | 'shipping' | 'currency' | 'workflow'\n        registryId: string\n        specialistRoute: string\n      }\n    }\n  | {\n      kind: 'module-override'\n      details: {\n        domain: string\n        key: string\n        mode: 'disable-replace' | 'replace' | 'additive'\n      }\n    }\n)\n\nexport type ModuleExtensionUnresolvedFact = {\n  key: string\n  source: { path: string; symbol?: string }\n  reason:\n    | 'unclassified-binding'\n    | 'unbound-declaration'\n    | 'dynamic-without-pattern'\n    | 'unresolved-first-party-target'\n}\n"],
   "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.7-develop.6795.1.8a3f27921c",
+  "version": "0.6.7-develop.6814.1.0627c7e9f1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.7-develop.6795.1.8a3f27921c",
+    "@open-mercato/cache": "0.6.7-develop.6814.1.0627c7e9f1",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/di/__tests__/container-app-di-absent.test.ts

@@ -0,0 +1,139 @@
+// The app-level DI override module (`@/di`) is OPTIONAL: most apps ship no
+// src/di.ts, and packages contexts cannot resolve the alias at all. Its
+// absence must not produce warnings — only real load/register failures do
+// (covered in container-app-di.test.ts). This file deliberately does NOT
+// mock '@/di', so the import fails with module-not-found, exercising the
+// quiet branch.
+
+jest.mock(
+  '@open-mercato/shared/lib/db/mikro',
+  () => {
+    const baseEm: any = {
+      fork: () => baseEm,
+      getRepository: () => ({ find: async () => [], findOne: async () => null }),
+    }
+    return {
+      __esModule: true,
+      getOrm: async () => ({ em: baseEm }),
+      getOrmEntities: () => [],
+      registerOrmEntities: () => {},
+    }
+  },
+  { virtual: false },
+)
+
+jest.mock(
+  '@mikro-orm/core',
+  () => ({
+    __esModule: true,
+    RequestContext: { getEntityManager: () => null },
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/query/engine',
+  () => ({ __esModule: true, BasicQueryEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/data/engine',
+  () => ({ __esModule: true, DefaultDataEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/commands',
+  () => ({
+    __esModule: true,
+    commandRegistry: {},
+    CommandBus: class { constructor() {} },
+  }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/modules/overrides',
+  () => ({
+    __esModule: true,
+    applyDiOverridesToContainer: () => {},
+  }),
+  { virtual: false },
+)
+
+// Keep this suite hermetic: without this mock the REAL core bootstrap module
+// loads (and runs its module-level side effects) whenever generated files
+// exist on disk, polluting globalThis state shared with sibling test files.
+jest.mock(
+  '@open-mercato/core/bootstrap',
+  () => ({
+    __esModule: true,
+    bootstrap: async () => {},
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/encryption/subscriber',
+  () => ({
+    __esModule: true,
+    registerTenantEncryptionSubscriber: () => {},
+  }),
+  { virtual: true },
+)
+
+const mockWarn = jest.fn()
+jest.mock('../../logger', () => ({
+  createLogger: () => ({
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: (...args: unknown[]) => mockWarn(...args),
+    error: jest.fn(),
+    child() { return this },
+  }),
+}))
+
+const {
+  createRequestContainer,
+  registerAppDiRegistrar,
+  registerDiRegistrars,
+  resetBootstrapCache,
+} = require('@open-mercato/shared/lib/di/container')
+
+describe('app-level DI override hook when @/di is absent', () => {
+  beforeEach(() => {
+    resetBootstrapCache()
+    registerAppDiRegistrar(null)
+    registerDiRegistrars([])
+    mockWarn.mockClear()
+  })
+
+  it('creates the container without warning', async () => {
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockWarn).not.toHaveBeenCalled()
+  })
+
+  it('warns once when @/di fails because a nested app alias is missing', async () => {
+    const nestedAliasError = Object.assign(new Error("Cannot find module '@/di/helpers'"), {
+      code: 'MODULE_NOT_FOUND',
+    })
+    jest.doMock('@/di', () => {
+      throw nestedAliasError
+    }, { virtual: true })
+
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockWarn).toHaveBeenCalledTimes(1)
+    expect(mockWarn).toHaveBeenCalledWith(
+      'App-level DI override module (@/di) failed to load; its registrations are skipped',
+      { err: nestedAliasError },
+    )
+  })
+})

package/src/lib/di/__tests__/container-app-di.test.ts

@@ -0,0 +1,173 @@
+// Tests for the app-level DI override hook (`src/di.ts` → `@/di`) in
+// `createRequestContainer()`. The hook used to swallow EVERY failure with
+// bare `catch {}` blocks, so a src/di.ts whose register() threw — or a @/di
+// module that failed to load for any reason other than being absent — was
+// skipped without a trace and the documented override point silently did
+// nothing. Absence of the optional module must stay quiet; real failures
+// must be logged.
+
+import { asValue } from 'awilix'
+
+jest.mock(
+  '@open-mercato/shared/lib/db/mikro',
+  () => {
+    const baseEm: any = {
+      fork: () => baseEm,
+      getRepository: () => ({ find: async () => [], findOne: async () => null }),
+    }
+    return {
+      __esModule: true,
+      getOrm: async () => ({ em: baseEm }),
+      getOrmEntities: () => [],
+      registerOrmEntities: () => {},
+    }
+  },
+  { virtual: false },
+)
+
+jest.mock(
+  '@mikro-orm/core',
+  () => ({
+    __esModule: true,
+    RequestContext: { getEntityManager: () => null },
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/query/engine',
+  () => ({ __esModule: true, BasicQueryEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/data/engine',
+  () => ({ __esModule: true, DefaultDataEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/commands',
+  () => ({
+    __esModule: true,
+    commandRegistry: {},
+    CommandBus: class { constructor() {} },
+  }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/modules/overrides',
+  () => ({
+    __esModule: true,
+    applyDiOverridesToContainer: () => {},
+  }),
+  { virtual: false },
+)
+
+// Keep this suite hermetic: without this mock the REAL core bootstrap module
+// loads (and runs its module-level side effects) whenever generated files
+// exist on disk, polluting globalThis state shared with sibling test files.
+jest.mock(
+  '@open-mercato/core/bootstrap',
+  () => ({
+    __esModule: true,
+    bootstrap: async () => {},
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/encryption/subscriber',
+  () => ({
+    __esModule: true,
+    registerTenantEncryptionSubscriber: () => {},
+  }),
+  { virtual: true },
+)
+
+const mockWarn = jest.fn()
+jest.mock('../../logger', () => ({
+  createLogger: () => ({
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: (...args: unknown[]) => mockWarn(...args),
+    error: jest.fn(),
+    child() { return this },
+  }),
+}))
+
+const mockAppDiRegister = jest.fn()
+jest.mock(
+  '@/di',
+  () => ({
+    __esModule: true,
+    register: (...args: unknown[]) => mockAppDiRegister(...args),
+  }),
+  { virtual: true },
+)
+
+const {
+  createRequestContainer,
+  registerAppDiRegistrar,
+  registerDiRegistrars,
+  resetBootstrapCache,
+} = require('@open-mercato/shared/lib/di/container')
+
+describe('app-level DI override hook (@/di)', () => {
+  beforeEach(() => {
+    resetBootstrapCache()
+    registerAppDiRegistrar(null)
+    registerDiRegistrars([])
+    mockWarn.mockClear()
+    mockAppDiRegister.mockReset()
+  })
+
+  it('calls register() with the request container and applies its registrations', async () => {
+    mockAppDiRegister.mockImplementation((container: any) => {
+      container.register({ appOverrideProbe: asValue('from-app-di') })
+    })
+    const container = await createRequestContainer()
+    expect(mockAppDiRegister).toHaveBeenCalledTimes(1)
+    expect(mockAppDiRegister).toHaveBeenCalledWith(container)
+    expect(container.resolve('appOverrideProbe')).toBe('from-app-di')
+    expect(mockWarn).not.toHaveBeenCalled()
+  })
+
+  it('awaits an async register()', async () => {
+    mockAppDiRegister.mockImplementation(async (container: any) => {
+      await Promise.resolve()
+      container.register({ appOverrideProbe: asValue('async-app-di') })
+    })
+    const container = await createRequestContainer()
+    expect(container.resolve('appOverrideProbe')).toBe('async-app-di')
+    expect(mockWarn).not.toHaveBeenCalled()
+  })
+
+  it('warns instead of silently swallowing when register() throws', async () => {
+    mockAppDiRegister.mockImplementation(() => {
+      throw new Error('boom from app di')
+    })
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockAppDiRegister).toHaveBeenCalledTimes(2)
+    expect(mockWarn).toHaveBeenCalledTimes(1)
+    const [message, fields] = mockWarn.mock.calls[0]
+    expect(String(message)).toContain('register()')
+    expect((fields as { err: Error }).err.message).toBe('boom from app di')
+  })
+
+  it('warns when an async register() rejects', async () => {
+    mockAppDiRegister.mockImplementation(async () => {
+      throw new Error('async boom from app di')
+    })
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockAppDiRegister).toHaveBeenCalledTimes(2)
+    expect(mockWarn).toHaveBeenCalledTimes(1)
+  })
+})