@open-mercato/shared 0.6.8-develop.6977.1.5041da373e → 0.6.8-develop.6981.1.5c7cff2f3b

package/AGENTS.md

@@ -50,7 +50,7 @@ yarn workspace @open-mercato/shared build
 | `i18n/` | When translating strings — `useT()` client-side, `resolveTranslations()` server-side | `@open-mercato/shared/lib/i18n/context` or `/server` |
 | `indexers/` | When building query index helpers | `@open-mercato/shared/lib/indexers` |
 | `logger/` | When emitting diagnostics — `createLogger(namespace)` instead of raw `console.*` (migrate incrementally, Boy Scout rule). Message-first with structured fields (`logger.warn('Payload too large', { event, maxBytes })`), errors under `err`, `child(bindings)` for context, `getLogLevel()`/`isLevelEnabled()` to gate expensive fields; level via `OM_LOG_LEVEL`. Never log credentials, PII, or payload bodies | `@open-mercato/shared/lib/logger` |
-| `modules/` | When registering or listing modules; `surfaceFingerprint` gives a deploy-time hash of the enabled modules, their declared ACL features, and the backend route manifest — mix it into any cache key whose payload is derived from those (no DB write exists to tag-invalidate on, so an omitted fingerprint serves the pre-deploy payload forever). It cannot see React-element fields such as a route `icon`, so callers MUST still pass a `ttl` | `@open-mercato/shared/lib/modules/registry`, `@open-mercato/shared/lib/modules/surfaceFingerprint` |
+| `modules/` | When registering or listing modules; `onModulesRegistered(listener)` subscribes to (re-)registrations so a cache derived from the module list can drop what it built from an incomplete one — bootstrap may register an i18n-only set before the full module list merges in, and listeners fire only when the registered set actually changed, so nothing is added to the request path. Its governing contract — notification timing, fail-soft handling of a throwing or rejecting listener, snapshot-based change detection, listener lifetime under HMR, and the globals a test MUST clear — is [`.ai/specs/2026-08-12-module-registry-registration-listeners.md`](../../.ai/specs/2026-08-12-module-registry-registration-listeners.md); `surfaceFingerprint` gives a deploy-time hash of the enabled modules, their declared ACL features, and the backend route manifest — mix it into any cache key whose payload is derived from those (no DB write exists to tag-invalidate on, so an omitted fingerprint serves the pre-deploy payload forever). It cannot see React-element fields such as a route `icon`, so callers MUST still pass a `ttl` | `@open-mercato/shared/lib/modules/registry`, `@open-mercato/shared/lib/modules/surfaceFingerprint` |
 | `number.ts` | When parsing numeric strings from env/query params with a fallback and optional min/integer constraint | `@open-mercato/shared/lib/number` |
 | `openapi/` | When generating CRUD OpenAPI specs | `@open-mercato/shared/lib/openapi/crud` |
 | `profiler/` | When profiling with `OM_PROFILE` env flag | `@open-mercato/shared/lib/profiler` |

package/dist/lib/modules/registry.js

@@ -3,12 +3,76 @@ import { invalidateDictionaryCache, invalidateDictionaryCacheLocales } from "../
 import { createLogger } from "../logger/index.js";
 const logger = createLogger("shared").child({ component: "modules-registry" });
 const GLOBAL_KEY = "__openMercatoModulesRegistry__";
+const LISTENERS_GLOBAL_KEY = "__openMercatoModulesRegistryListeners__";
+const SNAPSHOT_GLOBAL_KEY = "__openMercatoModulesRegistrySnapshot__";
+const UNREADABLE_CONTRACT_ENTRY = /* @__PURE__ */ Symbol("open-mercato.modules.unreadable-contract-entry");
+function registryGlobals() {
+  return globalThis;
+}
 function getGlobalModules() {
-  return globalThis[GLOBAL_KEY] ?? null;
+  return registryGlobals()[GLOBAL_KEY] ?? null;
 }
 function setGlobalModules(modules) {
-  ;
-  globalThis[GLOBAL_KEY] = modules;
+  registryGlobals()[GLOBAL_KEY] = modules;
+}
+function getListeners() {
+  const globalScope = registryGlobals();
+  const listeners = globalScope[LISTENERS_GLOBAL_KEY] ?? /* @__PURE__ */ new Set();
+  globalScope[LISTENERS_GLOBAL_KEY] = listeners;
+  return listeners;
+}
+function onModulesRegistered(listener) {
+  const listeners = getListeners();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function snapshotModules(modules) {
+  return modules.map((entry) => {
+    const contract = Object.keys(entry).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(entry, key);
+      if (!descriptor || !("value" in descriptor)) return [key, UNREADABLE_CONTRACT_ENTRY];
+      const value = descriptor.value;
+      return [key, Array.isArray(value) ? [...value] : value];
+    });
+    return [entry.id, contract];
+  });
+}
+function contractValuesMatch(previous, next) {
+  if (previous === UNREADABLE_CONTRACT_ENTRY || next === UNREADABLE_CONTRACT_ENTRY) return false;
+  if (Array.isArray(previous) && Array.isArray(next)) {
+    return previous.length === next.length && previous.every((item, index) => item === next[index]);
+  }
+  return previous === next;
+}
+function snapshotsMatch(previous, next) {
+  if (previous === null || previous.length !== next.length) return false;
+  return previous.every(([id, contract], index) => {
+    const [nextId, nextContract] = next[index];
+    if (id !== nextId || contract.length !== nextContract.length) return false;
+    return contract.every(([key, value], contractIndex) => {
+      const [nextKey, nextValue] = nextContract[contractIndex];
+      return key === nextKey && contractValuesMatch(value, nextValue);
+    });
+  });
+}
+function isPromiseLike(value) {
+  return typeof value?.then === "function";
+}
+function notifyModulesRegistered(modules) {
+  for (const listener of [...getListeners()]) {
+    try {
+      const result = listener(modules);
+      if (isPromiseLike(result)) {
+        Promise.resolve(result).catch((err) => {
+          logger.error("Module registration listener rejected", { err });
+        });
+      }
+    } catch (err) {
+      logger.error("Module registration listener failed", { err });
+    }
+  }
 }
 function hasRuntimeContracts(entry) {
   return Object.keys(entry).some((key) => key !== "id" && key !== "translations");
@@ -67,6 +131,13 @@ function registerModules(modules) {
   } else {
     invalidateDictionaryCache();
   }
+  const globalScope = registryGlobals();
+  const previousSnapshot = globalScope[SNAPSHOT_GLOBAL_KEY] ?? null;
+  const nextSnapshot = snapshotModules(registeredModules);
+  globalScope[SNAPSHOT_GLOBAL_KEY] = nextSnapshot;
+  if (!snapshotsMatch(previousSnapshot, nextSnapshot)) {
+    notifyModulesRegistered(registeredModules);
+  }
 }
 function getModules() {
   const modules = getGlobalModules();
@@ -80,6 +151,7 @@ function tryGetModules() {
 }
 export {
   getModules,
+  onModulesRegistered,
   registerModules,
   tryGetModules
 };

package/dist/lib/modules/registry.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/modules/registry.ts"],
-  "sourcesContent": ["import type { Module } from '@open-mercato/shared/modules/registry'\nimport { applyModuleOverridesToModules } from '@open-mercato/shared/modules/overrides'\nimport type { Locale } from '../i18n/config'\nimport { invalidateDictionaryCache, invalidateDictionaryCacheLocales } from '../i18n/dictionary-cache'\nimport { createLogger } from '../logger'\n\nconst logger = createLogger('shared').child({ component: 'modules-registry' })\n\n// Registration pattern for publishable packages.\n// Use globalThis to survive tsx/esbuild module duplication where the same\n// registry.ts file can be loaded as multiple module instances when mixing\n// dynamic and static imports \u2014 for example a standalone integration test\n// bootstraps via the source path while a worker handler resolves it through\n// node_modules/@open-mercato/shared/dist/. Mirrors the same workaround used\n// by `getDiRegistrars()` in `../di/container.ts`.\nconst GLOBAL_KEY = '__openMercatoModulesRegistry__'\n\nfunction getGlobalModules(): Module[] | null {\n  return (globalThis as any)[GLOBAL_KEY] ?? null\n}\n\nfunction setGlobalModules(modules: Module[]): void {\n  ;(globalThis as any)[GLOBAL_KEY] = modules\n}\n\nfunction hasRuntimeContracts(entry: Module): boolean {\n  return Object.keys(entry).some((key) => key !== 'id' && key !== 'translations')\n}\n\nfunction isI18nOnlyRegistration(modules: Module[]): boolean {\n  return modules.length > 0 && modules.every((entry) => !hasRuntimeContracts(entry))\n}\n\nfunction mergeI18nModules(existing: Module[], incoming: Module[]): Module[] {\n  const incomingById = new Map(incoming.map((entry) => [entry.id, entry]))\n  const existingIds = new Set(existing.map((entry) => entry.id))\n  const merged = existing.map((entry) => {\n    const i18nModule = incomingById.get(entry.id)\n    if (!i18nModule?.translations) return entry\n    return {\n      ...entry,\n      translations: {\n        ...(entry.translations ?? {}),\n        ...i18nModule.translations,\n      },\n    }\n  })\n\n  for (const entry of incoming) {\n    if (!existingIds.has(entry.id)) merged.push(entry)\n  }\n\n  return merged\n}\n\nfunction getTranslationLocales(modules: Module[]): Locale[] {\n  const locales = new Set<Locale>()\n  for (const entry of modules) {\n    for (const locale of Object.keys(entry.translations ?? {})) {\n      locales.add(locale as Locale)\n    }\n  }\n  return [...locales]\n}\n\nfunction preserveExistingTranslations(existing: Module[], incoming: Module[]): Module[] {\n  const existingById = new Map(existing.map((entry) => [entry.id, entry]))\n  return incoming.map((entry) => {\n    if (entry.translations) return entry\n    const translations = existingById.get(entry.id)?.translations\n    return translations ? { ...entry, translations } : entry\n  })\n}\n\nexport function registerModules(modules: Module[]) {\n  const existing = getGlobalModules()\n  if (existing !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('Modules re-registered (this may occur during HMR)')\n  }\n  const nextModules = applyModuleOverridesToModules(modules)\n  const i18nOnlyRegistration = isI18nOnlyRegistration(nextModules)\n  const shouldMergeI18nOnly = existing !== null && i18nOnlyRegistration\n  const registeredModules = shouldMergeI18nOnly\n    ? mergeI18nModules(existing, nextModules)\n    : preserveExistingTranslations(existing ?? [], nextModules)\n  setGlobalModules(registeredModules)\n  if (i18nOnlyRegistration) {\n    invalidateDictionaryCacheLocales(getTranslationLocales(nextModules))\n  } else {\n    invalidateDictionaryCache()\n  }\n}\n\nexport function getModules(): Module[] {\n  const modules = getGlobalModules()\n  if (!modules) {\n    throw new Error('[Bootstrap] Modules not registered. Call registerModules() at bootstrap.')\n  }\n  return modules\n}\n\n/**\n * Non-throwing counterpart of `getModules()` for call sites that have a\n * meaningful degraded behavior when bootstrap has not run \u2014 route unit tests\n * exercise a single handler without `registerModules()`, and a hard throw there\n * turns an unrelated assertion into a bootstrap error.\n */\nexport function tryGetModules(): Module[] | null {\n  return getGlobalModules()\n}\n"],
-  "mappings": "AACA,SAAS,qCAAqC;AAE9C,SAAS,2BAA2B,wCAAwC;AAC5E,SAAS,oBAAoB;AAE7B,MAAM,SAAS,aAAa,QAAQ,EAAE,MAAM,EAAE,WAAW,mBAAmB,CAAC;AAS7E,MAAM,aAAa;AAEnB,SAAS,mBAAoC;AAC3C,SAAQ,WAAmB,UAAU,KAAK;AAC5C;AAEA,SAAS,iBAAiB,SAAyB;AACjD;AAAC,EAAC,WAAmB,UAAU,IAAI;AACrC;AAEA,SAAS,oBAAoB,OAAwB;AACnD,SAAO,OAAO,KAAK,KAAK,EAAE,KAAK,CAAC,QAAQ,QAAQ,QAAQ,QAAQ,cAAc;AAChF;AAEA,SAAS,uBAAuB,SAA4B;AAC1D,SAAO,QAAQ,SAAS,KAAK,QAAQ,MAAM,CAAC,UAAU,CAAC,oBAAoB,KAAK,CAAC;AACnF;AAEA,SAAS,iBAAiB,UAAoB,UAA8B;AAC1E,QAAM,eAAe,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACvE,QAAM,cAAc,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,MAAM,EAAE,CAAC;AAC7D,QAAM,SAAS,SAAS,IAAI,CAAC,UAAU;AACrC,UAAM,aAAa,aAAa,IAAI,MAAM,EAAE;AAC5C,QAAI,CAAC,YAAY,aAAc,QAAO;AACtC,WAAO;AAAA,MACL,GAAG;AAAA,MACH,cAAc;AAAA,QACZ,GAAI,MAAM,gBAAgB,CAAC;AAAA,QAC3B,GAAG,WAAW;AAAA,MAChB;AAAA,IACF;AAAA,EACF,CAAC;AAED,aAAW,SAAS,UAAU;AAC5B,QAAI,CAAC,YAAY,IAAI,MAAM,EAAE,EAAG,QAAO,KAAK,KAAK;AAAA,EACnD;AAEA,SAAO;AACT;AAEA,SAAS,sBAAsB,SAA6B;AAC1D,QAAM,UAAU,oBAAI,IAAY;AAChC,aAAW,SAAS,SAAS;AAC3B,eAAW,UAAU,OAAO,KAAK,MAAM,gBAAgB,CAAC,CAAC,GAAG;AAC1D,cAAQ,IAAI,MAAgB;AAAA,IAC9B;AAAA,EACF;AACA,SAAO,CAAC,GAAG,OAAO;AACpB;AAEA,SAAS,6BAA6B,UAAoB,UAA8B;AACtF,QAAM,eAAe,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACvE,SAAO,SAAS,IAAI,CAAC,UAAU;AAC7B,QAAI,MAAM,aAAc,QAAO;AAC/B,UAAM,eAAe,aAAa,IAAI,MAAM,EAAE,GAAG;AACjD,WAAO,eAAe,EAAE,GAAG,OAAO,aAAa,IAAI;AAAA,EACrD,CAAC;AACH;AAEO,SAAS,gBAAgB,SAAmB;AACjD,QAAM,WAAW,iBAAiB;AAClC,MAAI,aAAa,QAAQ,QAAQ,IAAI,aAAa,eAAe;AAC/D,WAAO,MAAM,mDAAmD;AAAA,EAClE;AACA,QAAM,cAAc,8BAA8B,OAAO;AACzD,QAAM,uBAAuB,uBAAuB,WAAW;AAC/D,QAAM,sBAAsB,aAAa,QAAQ;AACjD,QAAM,oBAAoB,sBACtB,iBAAiB,UAAU,WAAW,IACtC,6BAA6B,YAAY,CAAC,GAAG,WAAW;AAC5D,mBAAiB,iBAAiB;AAClC,MAAI,sBAAsB;AACxB,qCAAiC,sBAAsB,WAAW,CAAC;AAAA,EACrE,OAAO;AACL,8BAA0B;AAAA,EAC5B;AACF;AAEO,SAAS,aAAuB;AACrC,QAAM,UAAU,iBAAiB;AACjC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,0EAA0E;AAAA,EAC5F;AACA,SAAO;AACT;AAQO,SAAS,gBAAiC;AAC/C,SAAO,iBAAiB;AAC1B;",
+  "sourcesContent": ["import type { Module } from '@open-mercato/shared/modules/registry'\nimport { applyModuleOverridesToModules } from '@open-mercato/shared/modules/overrides'\nimport type { Locale } from '../i18n/config'\nimport { invalidateDictionaryCache, invalidateDictionaryCacheLocales } from '../i18n/dictionary-cache'\nimport { createLogger } from '../logger'\n\nconst logger = createLogger('shared').child({ component: 'modules-registry' })\n\n// Registration pattern for publishable packages.\n// Use globalThis to survive tsx/esbuild module duplication where the same\n// registry.ts file can be loaded as multiple module instances when mixing\n// dynamic and static imports \u2014 for example a standalone integration test\n// bootstraps via the source path while a worker handler resolves it through\n// node_modules/@open-mercato/shared/dist/. Mirrors the same workaround used\n// by `getDiRegistrars()` in `../di/container.ts`.\nconst GLOBAL_KEY = '__openMercatoModulesRegistry__'\nconst LISTENERS_GLOBAL_KEY = '__openMercatoModulesRegistryListeners__'\nconst SNAPSHOT_GLOBAL_KEY = '__openMercatoModulesRegistrySnapshot__'\n\n/**\n * A listener may return a promise; `registerModules()` stays synchronous and\n * never awaits it, so the contract is fire-and-forget on both paths \u2014 a\n * synchronous throw and an asynchronous rejection are both observed and logged\n * rather than escaping into the bootstrap frame as an unhandled rejection.\n */\nexport type ModulesRegisteredListener = (modules: Module[]) => void | PromiseLike<void>\n\nconst UNREADABLE_CONTRACT_ENTRY = Symbol('open-mercato.modules.unreadable-contract-entry')\n\ntype RegistrationSnapshotEntry = readonly [id: string, contract: ReadonlyArray<readonly [string, unknown]>]\ntype RegistrationSnapshot = ReadonlyArray<RegistrationSnapshotEntry>\n\ntype ModulesRegistryGlobalScope = typeof globalThis & {\n  [GLOBAL_KEY]?: Module[] | null\n  [LISTENERS_GLOBAL_KEY]?: Set<ModulesRegisteredListener>\n  [SNAPSHOT_GLOBAL_KEY]?: RegistrationSnapshot | null\n}\n\nfunction registryGlobals(): ModulesRegistryGlobalScope {\n  return globalThis as ModulesRegistryGlobalScope\n}\n\nfunction getGlobalModules(): Module[] | null {\n  return registryGlobals()[GLOBAL_KEY] ?? null\n}\n\nfunction setGlobalModules(modules: Module[]): void {\n  registryGlobals()[GLOBAL_KEY] = modules\n}\n\nfunction getListeners(): Set<ModulesRegisteredListener> {\n  const globalScope = registryGlobals()\n  const listeners = globalScope[LISTENERS_GLOBAL_KEY] ?? new Set<ModulesRegisteredListener>()\n  globalScope[LISTENERS_GLOBAL_KEY] = listeners\n  return listeners\n}\n\n/**\n * Subscribe to module-registry (re-)registrations so caches derived from the\n * module list can drop what they built from an incomplete one. Bootstrap can\n * register modules more than once \u2014 an i18n-only registration is reconciled\n * with the full module list by `mergeI18nModules()` \u2014 and a consumer that\n * memoized its resolution in between would otherwise serve the pre-merge view\n * for the lifetime of the process (issue #5103).\n *\n * Listeners live on `globalThis` for the same module-duplication reason the\n * registry itself does, and they are notified only when the registered set\n * actually changed, so repeated identical bootstraps and HMR re-registrations\n * do not needlessly drop warm caches. Returns an unsubscribe function.\n *\n * Contract (`.ai/specs/2026-08-12-module-registry-registration-listeners.md`):\n * listeners run synchronously at the end of `registerModules()`, after the new\n * module list is readable through `getModules()`; a returned promise is never\n * awaited; neither a throw nor a rejection can break bootstrap; \"changed\" is\n * decided by the registration snapshot below, which sees module ids, their\n * top-level contract keys and the elements of array-valued ones \u2014 a mutation\n * deeper than that is invisible and its owner must invalidate its own cache.\n */\nexport function onModulesRegistered(listener: ModulesRegisteredListener): () => void {\n  const listeners = getListeners()\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * Freeze what the registered list declares, so a later in-place mutation of a\n * module object cannot retroactively rewrite what the previous registration\n * looked like. Comparing live `Module` references (the obvious cheap check)\n * cannot see an HMR bootstrap that reassigns `dashboardWidgets` on an existing\n * object and re-registers the same array \u2014 both sides are then the same\n * reference and the stale widget catalog survives until restart.\n */\nfunction snapshotModules(modules: Module[]): RegistrationSnapshot {\n  return modules.map((entry) => {\n    const contract = Object.keys(entry)\n      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))\n      .map((key) => {\n        const descriptor = Object.getOwnPropertyDescriptor(entry, key)\n        // An accessor is never invoked here: a module may declare a contract as a\n        // lazy getter that is expensive, side-effectful, or throws until the rest\n        // of bootstrap has run. It is recorded as unreadable instead, which never\n        // compares equal \u2014 erring toward dropping a warm cache rather than\n        // serving a stale one.\n        if (!descriptor || !('value' in descriptor)) return [key, UNREADABLE_CONTRACT_ENTRY] as const\n        const value = descriptor.value\n        return [key, Array.isArray(value) ? [...value] : value] as const\n      })\n    return [entry.id, contract] as const\n  })\n}\n\nfunction contractValuesMatch(previous: unknown, next: unknown): boolean {\n  if (previous === UNREADABLE_CONTRACT_ENTRY || next === UNREADABLE_CONTRACT_ENTRY) return false\n  if (Array.isArray(previous) && Array.isArray(next)) {\n    return previous.length === next.length && previous.every((item, index) => item === next[index])\n  }\n  return previous === next\n}\n\nfunction snapshotsMatch(previous: RegistrationSnapshot | null, next: RegistrationSnapshot): boolean {\n  if (previous === null || previous.length !== next.length) return false\n  return previous.every(([id, contract], index) => {\n    const [nextId, nextContract] = next[index]\n    if (id !== nextId || contract.length !== nextContract.length) return false\n    return contract.every(([key, value], contractIndex) => {\n      const [nextKey, nextValue] = nextContract[contractIndex]\n      return key === nextKey && contractValuesMatch(value, nextValue)\n    })\n  })\n}\n\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return typeof (value as PromiseLike<unknown> | null | undefined)?.then === 'function'\n}\n\nfunction notifyModulesRegistered(modules: Module[]): void {\n  for (const listener of [...getListeners()]) {\n    try {\n      const result = listener(modules)\n      if (isPromiseLike(result)) {\n        // The listener contract is fire-and-forget: registerModules() keeps its\n        // synchronous signature, so an async subscriber's rejection would land\n        // as an unhandled rejection (fatal under Node's default policy) unless\n        // it is observed here.\n        Promise.resolve(result).catch((err) => {\n          logger.error('Module registration listener rejected', { err })\n        })\n      }\n    } catch (err) {\n      logger.error('Module registration listener failed', { err })\n    }\n  }\n}\n\nfunction hasRuntimeContracts(entry: Module): boolean {\n  return Object.keys(entry).some((key) => key !== 'id' && key !== 'translations')\n}\n\nfunction isI18nOnlyRegistration(modules: Module[]): boolean {\n  return modules.length > 0 && modules.every((entry) => !hasRuntimeContracts(entry))\n}\n\nfunction mergeI18nModules(existing: Module[], incoming: Module[]): Module[] {\n  const incomingById = new Map(incoming.map((entry) => [entry.id, entry]))\n  const existingIds = new Set(existing.map((entry) => entry.id))\n  const merged = existing.map((entry) => {\n    const i18nModule = incomingById.get(entry.id)\n    if (!i18nModule?.translations) return entry\n    return {\n      ...entry,\n      translations: {\n        ...(entry.translations ?? {}),\n        ...i18nModule.translations,\n      },\n    }\n  })\n\n  for (const entry of incoming) {\n    if (!existingIds.has(entry.id)) merged.push(entry)\n  }\n\n  return merged\n}\n\nfunction getTranslationLocales(modules: Module[]): Locale[] {\n  const locales = new Set<Locale>()\n  for (const entry of modules) {\n    for (const locale of Object.keys(entry.translations ?? {})) {\n      locales.add(locale as Locale)\n    }\n  }\n  return [...locales]\n}\n\nfunction preserveExistingTranslations(existing: Module[], incoming: Module[]): Module[] {\n  const existingById = new Map(existing.map((entry) => [entry.id, entry]))\n  return incoming.map((entry) => {\n    if (entry.translations) return entry\n    const translations = existingById.get(entry.id)?.translations\n    return translations ? { ...entry, translations } : entry\n  })\n}\n\nexport function registerModules(modules: Module[]) {\n  const existing = getGlobalModules()\n  if (existing !== null && process.env.NODE_ENV === 'development') {\n    logger.debug('Modules re-registered (this may occur during HMR)')\n  }\n  const nextModules = applyModuleOverridesToModules(modules)\n  const i18nOnlyRegistration = isI18nOnlyRegistration(nextModules)\n  const shouldMergeI18nOnly = existing !== null && i18nOnlyRegistration\n  const registeredModules = shouldMergeI18nOnly\n    ? mergeI18nModules(existing, nextModules)\n    : preserveExistingTranslations(existing ?? [], nextModules)\n  setGlobalModules(registeredModules)\n  if (i18nOnlyRegistration) {\n    invalidateDictionaryCacheLocales(getTranslationLocales(nextModules))\n  } else {\n    invalidateDictionaryCache()\n  }\n  const globalScope = registryGlobals()\n  const previousSnapshot = globalScope[SNAPSHOT_GLOBAL_KEY] ?? null\n  const nextSnapshot = snapshotModules(registeredModules)\n  globalScope[SNAPSHOT_GLOBAL_KEY] = nextSnapshot\n  if (!snapshotsMatch(previousSnapshot, nextSnapshot)) {\n    notifyModulesRegistered(registeredModules)\n  }\n}\n\nexport function getModules(): Module[] {\n  const modules = getGlobalModules()\n  if (!modules) {\n    throw new Error('[Bootstrap] Modules not registered. Call registerModules() at bootstrap.')\n  }\n  return modules\n}\n\n/**\n * Non-throwing counterpart of `getModules()` for call sites that have a\n * meaningful degraded behavior when bootstrap has not run \u2014 route unit tests\n * exercise a single handler without `registerModules()`, and a hard throw there\n * turns an unrelated assertion into a bootstrap error.\n */\nexport function tryGetModules(): Module[] | null {\n  return getGlobalModules()\n}\n"],
+  "mappings": "AACA,SAAS,qCAAqC;AAE9C,SAAS,2BAA2B,wCAAwC;AAC5E,SAAS,oBAAoB;AAE7B,MAAM,SAAS,aAAa,QAAQ,EAAE,MAAM,EAAE,WAAW,mBAAmB,CAAC;AAS7E,MAAM,aAAa;AACnB,MAAM,uBAAuB;AAC7B,MAAM,sBAAsB;AAU5B,MAAM,4BAA4B,uBAAO,gDAAgD;AAWzF,SAAS,kBAA8C;AACrD,SAAO;AACT;AAEA,SAAS,mBAAoC;AAC3C,SAAO,gBAAgB,EAAE,UAAU,KAAK;AAC1C;AAEA,SAAS,iBAAiB,SAAyB;AACjD,kBAAgB,EAAE,UAAU,IAAI;AAClC;AAEA,SAAS,eAA+C;AACtD,QAAM,cAAc,gBAAgB;AACpC,QAAM,YAAY,YAAY,oBAAoB,KAAK,oBAAI,IAA+B;AAC1F,cAAY,oBAAoB,IAAI;AACpC,SAAO;AACT;AAuBO,SAAS,oBAAoB,UAAiD;AACnF,QAAM,YAAY,aAAa;AAC/B,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAUA,SAAS,gBAAgB,SAAyC;AAChE,SAAO,QAAQ,IAAI,CAAC,UAAU;AAC5B,UAAM,WAAW,OAAO,KAAK,KAAK,EAC/B,KAAK,CAAC,GAAG,MAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAE,EAC3C,IAAI,CAAC,QAAQ;AACZ,YAAM,aAAa,OAAO,yBAAyB,OAAO,GAAG;AAM7D,UAAI,CAAC,cAAc,EAAE,WAAW,YAAa,QAAO,CAAC,KAAK,yBAAyB;AACnF,YAAM,QAAQ,WAAW;AACzB,aAAO,CAAC,KAAK,MAAM,QAAQ,KAAK,IAAI,CAAC,GAAG,KAAK,IAAI,KAAK;AAAA,IACxD,CAAC;AACH,WAAO,CAAC,MAAM,IAAI,QAAQ;AAAA,EAC5B,CAAC;AACH;AAEA,SAAS,oBAAoB,UAAmB,MAAwB;AACtE,MAAI,aAAa,6BAA6B,SAAS,0BAA2B,QAAO;AACzF,MAAI,MAAM,QAAQ,QAAQ,KAAK,MAAM,QAAQ,IAAI,GAAG;AAClD,WAAO,SAAS,WAAW,KAAK,UAAU,SAAS,MAAM,CAAC,MAAM,UAAU,SAAS,KAAK,KAAK,CAAC;AAAA,EAChG;AACA,SAAO,aAAa;AACtB;AAEA,SAAS,eAAe,UAAuC,MAAqC;AAClG,MAAI,aAAa,QAAQ,SAAS,WAAW,KAAK,OAAQ,QAAO;AACjE,SAAO,SAAS,MAAM,CAAC,CAAC,IAAI,QAAQ,GAAG,UAAU;AAC/C,UAAM,CAAC,QAAQ,YAAY,IAAI,KAAK,KAAK;AACzC,QAAI,OAAO,UAAU,SAAS,WAAW,aAAa,OAAQ,QAAO;AACrE,WAAO,SAAS,MAAM,CAAC,CAAC,KAAK,KAAK,GAAG,kBAAkB;AACrD,YAAM,CAAC,SAAS,SAAS,IAAI,aAAa,aAAa;AACvD,aAAO,QAAQ,WAAW,oBAAoB,OAAO,SAAS;AAAA,IAChE,CAAC;AAAA,EACH,CAAC;AACH;AAEA,SAAS,cAAc,OAA+C;AACpE,SAAO,OAAQ,OAAmD,SAAS;AAC7E;AAEA,SAAS,wBAAwB,SAAyB;AACxD,aAAW,YAAY,CAAC,GAAG,aAAa,CAAC,GAAG;AAC1C,QAAI;AACF,YAAM,SAAS,SAAS,OAAO;AAC/B,UAAI,cAAc,MAAM,GAAG;AAKzB,gBAAQ,QAAQ,MAAM,EAAE,MAAM,CAAC,QAAQ;AACrC,iBAAO,MAAM,yCAAyC,EAAE,IAAI,CAAC;AAAA,QAC/D,CAAC;AAAA,MACH;AAAA,IACF,SAAS,KAAK;AACZ,aAAO,MAAM,uCAAuC,EAAE,IAAI,CAAC;AAAA,IAC7D;AAAA,EACF;AACF;AAEA,SAAS,oBAAoB,OAAwB;AACnD,SAAO,OAAO,KAAK,KAAK,EAAE,KAAK,CAAC,QAAQ,QAAQ,QAAQ,QAAQ,cAAc;AAChF;AAEA,SAAS,uBAAuB,SAA4B;AAC1D,SAAO,QAAQ,SAAS,KAAK,QAAQ,MAAM,CAAC,UAAU,CAAC,oBAAoB,KAAK,CAAC;AACnF;AAEA,SAAS,iBAAiB,UAAoB,UAA8B;AAC1E,QAAM,eAAe,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACvE,QAAM,cAAc,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,MAAM,EAAE,CAAC;AAC7D,QAAM,SAAS,SAAS,IAAI,CAAC,UAAU;AACrC,UAAM,aAAa,aAAa,IAAI,MAAM,EAAE;AAC5C,QAAI,CAAC,YAAY,aAAc,QAAO;AACtC,WAAO;AAAA,MACL,GAAG;AAAA,MACH,cAAc;AAAA,QACZ,GAAI,MAAM,gBAAgB,CAAC;AAAA,QAC3B,GAAG,WAAW;AAAA,MAChB;AAAA,IACF;AAAA,EACF,CAAC;AAED,aAAW,SAAS,UAAU;AAC5B,QAAI,CAAC,YAAY,IAAI,MAAM,EAAE,EAAG,QAAO,KAAK,KAAK;AAAA,EACnD;AAEA,SAAO;AACT;AAEA,SAAS,sBAAsB,SAA6B;AAC1D,QAAM,UAAU,oBAAI,IAAY;AAChC,aAAW,SAAS,SAAS;AAC3B,eAAW,UAAU,OAAO,KAAK,MAAM,gBAAgB,CAAC,CAAC,GAAG;AAC1D,cAAQ,IAAI,MAAgB;AAAA,IAC9B;AAAA,EACF;AACA,SAAO,CAAC,GAAG,OAAO;AACpB;AAEA,SAAS,6BAA6B,UAAoB,UAA8B;AACtF,QAAM,eAAe,IAAI,IAAI,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACvE,SAAO,SAAS,IAAI,CAAC,UAAU;AAC7B,QAAI,MAAM,aAAc,QAAO;AAC/B,UAAM,eAAe,aAAa,IAAI,MAAM,EAAE,GAAG;AACjD,WAAO,eAAe,EAAE,GAAG,OAAO,aAAa,IAAI;AAAA,EACrD,CAAC;AACH;AAEO,SAAS,gBAAgB,SAAmB;AACjD,QAAM,WAAW,iBAAiB;AAClC,MAAI,aAAa,QAAQ,QAAQ,IAAI,aAAa,eAAe;AAC/D,WAAO,MAAM,mDAAmD;AAAA,EAClE;AACA,QAAM,cAAc,8BAA8B,OAAO;AACzD,QAAM,uBAAuB,uBAAuB,WAAW;AAC/D,QAAM,sBAAsB,aAAa,QAAQ;AACjD,QAAM,oBAAoB,sBACtB,iBAAiB,UAAU,WAAW,IACtC,6BAA6B,YAAY,CAAC,GAAG,WAAW;AAC5D,mBAAiB,iBAAiB;AAClC,MAAI,sBAAsB;AACxB,qCAAiC,sBAAsB,WAAW,CAAC;AAAA,EACrE,OAAO;AACL,8BAA0B;AAAA,EAC5B;AACA,QAAM,cAAc,gBAAgB;AACpC,QAAM,mBAAmB,YAAY,mBAAmB,KAAK;AAC7D,QAAM,eAAe,gBAAgB,iBAAiB;AACtD,cAAY,mBAAmB,IAAI;AACnC,MAAI,CAAC,eAAe,kBAAkB,YAAY,GAAG;AACnD,4BAAwB,iBAAiB;AAAA,EAC3C;AACF;AAEO,SAAS,aAAuB;AACrC,QAAM,UAAU,iBAAiB;AACjC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,0EAA0E;AAAA,EAC5F;AACA,SAAO;AACT;AAQO,SAAS,gBAAiC;AAC/C,SAAO,iBAAiB;AAC1B;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.6977.1.5041da373e";
+const APP_VERSION = "0.6.8-develop.6981.1.5c7cff2f3b";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6977.1.5041da373e';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6981.1.5c7cff2f3b';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6977.1.5041da373e",
+  "version": "0.6.8-develop.6981.1.5c7cff2f3b",
   "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.8-develop.6977.1.5041da373e",
+    "@open-mercato/cache": "0.6.8-develop.6981.1.5c7cff2f3b",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/modules/__tests__/registry.test.ts

@@ -13,12 +13,17 @@ jest.mock('@open-mercato/shared/lib/logger', () => {
   return { createLogger: jest.fn(() => mocked) }
 })
 const loggerDebug = createLogger('shared').debug as jest.Mock
+const loggerError = createLogger('shared').error as jest.Mock
 
 
 const GLOBAL_KEY = '__openMercatoModulesRegistry__'
+const LISTENERS_GLOBAL_KEY = '__openMercatoModulesRegistryListeners__'
+const SNAPSHOT_GLOBAL_KEY = '__openMercatoModulesRegistrySnapshot__'
 
 function clearGlobalRegistry(): void {
   delete (globalThis as any)[GLOBAL_KEY]
+  delete (globalThis as any)[LISTENERS_GLOBAL_KEY]
+  delete (globalThis as any)[SNAPSHOT_GLOBAL_KEY]
 }
 
 function clearRegistryModuleCache(): void {
@@ -171,4 +176,129 @@ describe('shared modules registry', () => {
       }),
     ])
   })
+
+  describe('onModulesRegistered (#5103)', () => {
+    it('notifies subscribers with the reconciled module list on first registration', () => {
+      const registry = loadRegistry()
+      const listener = jest.fn()
+      registry.onModulesRegistered(listener)
+
+      registry.registerModules(sampleModules)
+
+      expect(listener).toHaveBeenCalledTimes(1)
+      expect((listener.mock.calls[0][0] as Module[]).map((m) => m.id)).toEqual(['auth', 'customers'])
+    })
+
+    it('notifies subscribers when an i18n-only registration is merged with the full module list', () => {
+      const registry = loadRegistry()
+      const listener = jest.fn()
+      registry.registerModules([{ id: 'checkout', translations: { pl: { title: 'Kasa' } } } as Module])
+      registry.onModulesRegistered(listener)
+
+      registry.registerModules([
+        { id: 'checkout', dashboardWidgets: [] } as unknown as Module,
+        { id: 'reports', dashboardWidgets: [] } as unknown as Module,
+      ])
+
+      expect(listener).toHaveBeenCalledTimes(1)
+      expect((listener.mock.calls[0][0] as Module[]).map((m) => m.id)).toEqual(['checkout', 'reports'])
+    })
+
+    it('does not notify subscribers when the identical module set is re-registered', () => {
+      const registry = loadRegistry()
+      const listener = jest.fn()
+      registry.registerModules(sampleModules)
+      registry.onModulesRegistered(listener)
+
+      registry.registerModules(sampleModules)
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('stops notifying after the returned unsubscribe is called', () => {
+      const registry = loadRegistry()
+      const listener = jest.fn()
+      const unsubscribe = registry.onModulesRegistered(listener)
+
+      registry.registerModules(sampleModules)
+      unsubscribe()
+      registry.registerModules([{ id: 'auth', dashboardWidgets: [] } as unknown as Module])
+
+      expect(listener).toHaveBeenCalledTimes(1)
+    })
+
+    it('notifies subscribers when a re-registered module object was mutated in place', () => {
+      const registry = loadRegistry()
+      const mutated = { id: 'dashboards', dashboardWidgets: [] } as unknown as Module
+      const modules = [mutated]
+      registry.registerModules(modules)
+      const listener = jest.fn()
+      registry.onModulesRegistered(listener)
+
+      ;(mutated as unknown as { dashboardWidgets: unknown[] }).dashboardWidgets = [{ key: 'sales-kpi' }]
+      registry.registerModules(modules)
+
+      expect(listener).toHaveBeenCalledTimes(1)
+    })
+
+    it('notifies subscribers when an array-valued contract is mutated in place', () => {
+      const registry = loadRegistry()
+      const widgets: unknown[] = []
+      const mutated = { id: 'dashboards', dashboardWidgets: widgets } as unknown as Module
+      const modules = [mutated]
+      registry.registerModules(modules)
+      const listener = jest.fn()
+      registry.onModulesRegistered(listener)
+
+      widgets.push({ key: 'sales-kpi' })
+      registry.registerModules(modules)
+
+      expect(listener).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not notify subscribers when a semantically identical fresh module list is registered', () => {
+      const registry = loadRegistry()
+      const widget = { key: 'sales-kpi' }
+      registry.registerModules([{ id: 'dashboards', dashboardWidgets: [widget] } as unknown as Module])
+      const listener = jest.fn()
+      registry.onModulesRegistered(listener)
+
+      registry.registerModules([{ id: 'dashboards', dashboardWidgets: [widget] } as unknown as Module])
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('observes and logs a rejected async subscriber instead of leaking an unhandled rejection', async () => {
+      const registry = loadRegistry()
+      const rejection = new Error('async listener boom')
+      const failing = jest.fn(async () => {
+        await Promise.resolve()
+        throw rejection
+      })
+      const healthy = jest.fn()
+      registry.onModulesRegistered(failing)
+      registry.onModulesRegistered(healthy)
+      loggerError.mockClear()
+
+      expect(() => registry.registerModules(sampleModules)).not.toThrow()
+      expect(healthy).toHaveBeenCalledTimes(1)
+      await new Promise((resolve) => setImmediate(resolve))
+
+      expect(loggerError).toHaveBeenCalledWith('Module registration listener rejected', { err: rejection })
+    })
+
+    it('keeps registering modules when a subscriber throws', () => {
+      const registry = loadRegistry()
+      const failing = jest.fn(() => {
+        throw new Error('listener boom')
+      })
+      const healthy = jest.fn()
+      registry.onModulesRegistered(failing)
+      registry.onModulesRegistered(healthy)
+
+      expect(() => registry.registerModules(sampleModules)).not.toThrow()
+      expect(healthy).toHaveBeenCalledTimes(1)
+      expect(registry.getModules().map((m) => m.id)).toEqual(['auth', 'customers'])
+    })
+  })
 })

package/src/lib/modules/registry.ts

@@ -14,13 +14,144 @@ const logger = createLogger('shared').child({ component: 'modules-registry' })
 // node_modules/@open-mercato/shared/dist/. Mirrors the same workaround used
 // by `getDiRegistrars()` in `../di/container.ts`.
 const GLOBAL_KEY = '__openMercatoModulesRegistry__'
+const LISTENERS_GLOBAL_KEY = '__openMercatoModulesRegistryListeners__'
+const SNAPSHOT_GLOBAL_KEY = '__openMercatoModulesRegistrySnapshot__'
+
+/**
+ * A listener may return a promise; `registerModules()` stays synchronous and
+ * never awaits it, so the contract is fire-and-forget on both paths — a
+ * synchronous throw and an asynchronous rejection are both observed and logged
+ * rather than escaping into the bootstrap frame as an unhandled rejection.
+ */
+export type ModulesRegisteredListener = (modules: Module[]) => void | PromiseLike<void>
+
+const UNREADABLE_CONTRACT_ENTRY = Symbol('open-mercato.modules.unreadable-contract-entry')
+
+type RegistrationSnapshotEntry = readonly [id: string, contract: ReadonlyArray<readonly [string, unknown]>]
+type RegistrationSnapshot = ReadonlyArray<RegistrationSnapshotEntry>
+
+type ModulesRegistryGlobalScope = typeof globalThis & {
+  [GLOBAL_KEY]?: Module[] | null
+  [LISTENERS_GLOBAL_KEY]?: Set<ModulesRegisteredListener>
+  [SNAPSHOT_GLOBAL_KEY]?: RegistrationSnapshot | null
+}
+
+function registryGlobals(): ModulesRegistryGlobalScope {
+  return globalThis as ModulesRegistryGlobalScope
+}
 
 function getGlobalModules(): Module[] | null {
-  return (globalThis as any)[GLOBAL_KEY] ?? null
+  return registryGlobals()[GLOBAL_KEY] ?? null
 }
 
 function setGlobalModules(modules: Module[]): void {
-  ;(globalThis as any)[GLOBAL_KEY] = modules
+  registryGlobals()[GLOBAL_KEY] = modules
+}
+
+function getListeners(): Set<ModulesRegisteredListener> {
+  const globalScope = registryGlobals()
+  const listeners = globalScope[LISTENERS_GLOBAL_KEY] ?? new Set<ModulesRegisteredListener>()
+  globalScope[LISTENERS_GLOBAL_KEY] = listeners
+  return listeners
+}
+
+/**
+ * Subscribe to module-registry (re-)registrations so caches derived from the
+ * module list can drop what they built from an incomplete one. Bootstrap can
+ * register modules more than once — an i18n-only registration is reconciled
+ * with the full module list by `mergeI18nModules()` — and a consumer that
+ * memoized its resolution in between would otherwise serve the pre-merge view
+ * for the lifetime of the process (issue #5103).
+ *
+ * Listeners live on `globalThis` for the same module-duplication reason the
+ * registry itself does, and they are notified only when the registered set
+ * actually changed, so repeated identical bootstraps and HMR re-registrations
+ * do not needlessly drop warm caches. Returns an unsubscribe function.
+ *
+ * Contract (`.ai/specs/2026-08-12-module-registry-registration-listeners.md`):
+ * listeners run synchronously at the end of `registerModules()`, after the new
+ * module list is readable through `getModules()`; a returned promise is never
+ * awaited; neither a throw nor a rejection can break bootstrap; "changed" is
+ * decided by the registration snapshot below, which sees module ids, their
+ * top-level contract keys and the elements of array-valued ones — a mutation
+ * deeper than that is invisible and its owner must invalidate its own cache.
+ */
+export function onModulesRegistered(listener: ModulesRegisteredListener): () => void {
+  const listeners = getListeners()
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+/**
+ * Freeze what the registered list declares, so a later in-place mutation of a
+ * module object cannot retroactively rewrite what the previous registration
+ * looked like. Comparing live `Module` references (the obvious cheap check)
+ * cannot see an HMR bootstrap that reassigns `dashboardWidgets` on an existing
+ * object and re-registers the same array — both sides are then the same
+ * reference and the stale widget catalog survives until restart.
+ */
+function snapshotModules(modules: Module[]): RegistrationSnapshot {
+  return modules.map((entry) => {
+    const contract = Object.keys(entry)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+      .map((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(entry, key)
+        // An accessor is never invoked here: a module may declare a contract as a
+        // lazy getter that is expensive, side-effectful, or throws until the rest
+        // of bootstrap has run. It is recorded as unreadable instead, which never
+        // compares equal — erring toward dropping a warm cache rather than
+        // serving a stale one.
+        if (!descriptor || !('value' in descriptor)) return [key, UNREADABLE_CONTRACT_ENTRY] as const
+        const value = descriptor.value
+        return [key, Array.isArray(value) ? [...value] : value] as const
+      })
+    return [entry.id, contract] as const
+  })
+}
+
+function contractValuesMatch(previous: unknown, next: unknown): boolean {
+  if (previous === UNREADABLE_CONTRACT_ENTRY || next === UNREADABLE_CONTRACT_ENTRY) return false
+  if (Array.isArray(previous) && Array.isArray(next)) {
+    return previous.length === next.length && previous.every((item, index) => item === next[index])
+  }
+  return previous === next
+}
+
+function snapshotsMatch(previous: RegistrationSnapshot | null, next: RegistrationSnapshot): boolean {
+  if (previous === null || previous.length !== next.length) return false
+  return previous.every(([id, contract], index) => {
+    const [nextId, nextContract] = next[index]
+    if (id !== nextId || contract.length !== nextContract.length) return false
+    return contract.every(([key, value], contractIndex) => {
+      const [nextKey, nextValue] = nextContract[contractIndex]
+      return key === nextKey && contractValuesMatch(value, nextValue)
+    })
+  })
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return typeof (value as PromiseLike<unknown> | null | undefined)?.then === 'function'
+}
+
+function notifyModulesRegistered(modules: Module[]): void {
+  for (const listener of [...getListeners()]) {
+    try {
+      const result = listener(modules)
+      if (isPromiseLike(result)) {
+        // The listener contract is fire-and-forget: registerModules() keeps its
+        // synchronous signature, so an async subscriber's rejection would land
+        // as an unhandled rejection (fatal under Node's default policy) unless
+        // it is observed here.
+        Promise.resolve(result).catch((err) => {
+          logger.error('Module registration listener rejected', { err })
+        })
+      }
+    } catch (err) {
+      logger.error('Module registration listener failed', { err })
+    }
+  }
 }
 
 function hasRuntimeContracts(entry: Module): boolean {
@@ -89,6 +220,13 @@ export function registerModules(modules: Module[]) {
   } else {
     invalidateDictionaryCache()
   }
+  const globalScope = registryGlobals()
+  const previousSnapshot = globalScope[SNAPSHOT_GLOBAL_KEY] ?? null
+  const nextSnapshot = snapshotModules(registeredModules)
+  globalScope[SNAPSHOT_GLOBAL_KEY] = nextSnapshot
+  if (!snapshotsMatch(previousSnapshot, nextSnapshot)) {
+    notifyModulesRegistered(registeredModules)
+  }
 }
 
 export function getModules(): Module[] {