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

package/src/lib/generators/module-extension-facts.ts

@@ -9,12 +9,20 @@ import {
 import type {
   ExtensionHostCapability,
   ExtensionHostFamily,
+  ModuleContributionResolution,
+  ModuleExtensionActivation,
+  ModuleExtensionActivationKind,
   ModuleExtensionContributionFact,
   ModuleExtensionContributionBase,
+  ModuleExtensionContributionKind,
   ModuleExtensionHostFact,
+  ModuleExtensionResolution,
   ModuleExtensionSurfaceFacts,
   ModuleExtensionTargetFact,
+  ModuleExtensionTargetRef,
   ModuleExtensionUnresolvedFact,
+  ModuleFactSourceRef,
+  ModuleIncomingExtensionRef,
 } from '@open-mercato/shared/modules/widgets/extension-points'
 import { extractCommandIdsFromSource } from './module-registry'
 import { scanModuleDir, SCAN_CONFIGS } from './scanner'
@@ -71,6 +79,8 @@ type StaticContext = {
 
 type ApiExtensionHostIds = {
   entityIds: string[]
+  /** Declaring `api/**` file per entity host id, so the host links to a real source. */
+  entitySourceFiles: Record<string, string>
   commandIds: string[]
   routeIds: string[]
 }
@@ -651,6 +661,8 @@ function factRefHost(options: {
   family: ExtensionHostFamily
   capabilities: ExtensionHostCapability[]
   factSection: string
+  /** Key inside `factSection`; defaults to the host id when the two coincide. */
+  factKey?: string
   phases?: string[]
   activation?: ModuleExtensionHostFact['activation']
   scopeContract?: string
@@ -667,7 +679,7 @@ function factRefHost(options: {
     ...(options.scopeContract ? { scopeContract: options.scopeContract } : {}),
     bound: true,
     stability: 'stable',
-    source: { kind: 'fact-ref', factSection: options.factSection, factKey: options.id },
+    source: { kind: 'fact-ref', factSection: options.factSection, factKey: options.factKey ?? options.id },
   }
 }
 
@@ -704,6 +716,7 @@ function apiExtensionHostIds(moduleId: string, moduleRoot: string): ApiExtension
   const cached = activeExtractionCache?.apiExtensionHostIds.get(cacheKey)
   if (cached) return cached
   const entityIds = new Set<string>()
+  const entitySourceFiles: Record<string, string> = {}
   const commandIds = new Set<string>()
   const routeIds = new Set<string>()
   for (const filePath of sourceFilesBelow(path.join(moduleRoot, 'api'))) {
@@ -722,7 +735,10 @@ function apiExtensionHostIds(moduleId: string, moduleRoot: string): ApiExtension
         if (name === 'enrichers') {
           const config = staticValue(node.initializer, context)
           const entityId = isStaticObject(config) ? stringValue(config.entityId) : undefined
-          if (entityId) entityIds.add(entityId)
+          if (entityId) {
+            entityIds.add(entityId)
+            if (!entitySourceFiles[entityId]) entitySourceFiles[entityId] = filePath
+          }
         }
       }
       if (
@@ -732,7 +748,10 @@ function apiExtensionHostIds(moduleId: string, moduleRoot: string): ApiExtension
       ) {
         const input = node.arguments[1] ? staticValue(node.arguments[1], context) : undefined
         const entityId = isStaticObject(input) ? stringValue(input.resourceKind) : undefined
-        if (entityId) entityIds.add(entityId)
+        if (entityId) {
+          entityIds.add(entityId)
+          if (!entitySourceFiles[entityId]) entitySourceFiles[entityId] = filePath
+        }
       }
       node.forEachChild(visit)
     }
@@ -740,6 +759,7 @@ function apiExtensionHostIds(moduleId: string, moduleRoot: string): ApiExtension
   }
   const result = {
     entityIds: [...entityIds].sort((left, right) => left.localeCompare(right)),
+    entitySourceFiles,
     commandIds: [...commandIds].sort((left, right) => left.localeCompare(right)),
     routeIds: [...routeIds].sort((left, right) => left.localeCompare(right)),
   }
@@ -765,6 +785,142 @@ export function extractKnownCommandIds(moduleId: string, moduleRoot: string): st
   return moduleCommandIds(moduleRoot, apiHosts.commandIds)
 }
 
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+export type ApiInterceptorPhase = 'before' | 'after'
+export type ApiRouteInterceptorBridge = {
+  method: (typeof HTTP_METHODS)[number]
+  phases: ApiInterceptorPhase[]
+}
+
+const API_INTERCEPTOR_BRIDGE_CALLS: Record<string, ApiInterceptorPhase> = {
+  runApiInterceptorsBefore: 'before',
+  runApiInterceptorsAfter: 'after',
+}
+
+function isHttpMethodName(value: string): value is (typeof HTTP_METHODS)[number] {
+  return (HTTP_METHODS as readonly string[]).includes(value)
+}
+
+/** HTTP method handlers a route file actually exports. */
+function exportedHttpMethods(file: ts.SourceFile): Array<(typeof HTTP_METHODS)[number]> {
+  const methods = new Set<(typeof HTTP_METHODS)[number]>()
+  const consider = (name: string | undefined): void => {
+    if (name && isHttpMethodName(name)) methods.add(name)
+  }
+  const considerBindingName = (name: ts.BindingName): void => {
+    if (ts.isIdentifier(name)) {
+      consider(name.text)
+      return
+    }
+    for (const element of name.elements) {
+      if (ts.isBindingElement(element)) considerBindingName(element.name)
+    }
+  }
+  const visit = (node: ts.Node): void => {
+    if (ts.isVariableStatement(node) && node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      for (const declaration of node.declarationList.declarations) {
+        considerBindingName(declaration.name)
+      }
+    }
+    if (
+      ts.isFunctionDeclaration(node)
+      && node.name
+      && node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      consider(node.name.text)
+    }
+    if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+      for (const element of node.exportClause.elements) consider(element.name.text)
+    }
+    node.forEachChild(visit)
+  }
+  file.forEachChild(visit)
+  return [...methods].sort((left, right) => left.localeCompare(right))
+}
+
+/**
+ * The interceptor pipeline runs only where a route wires it: `makeCrudRoute` runs
+ * both phases for every method it handles, and a hand-written route runs whichever
+ * of `runApiInterceptorsBefore` / `runApiInterceptorsAfter` it calls. A custom route
+ * that calls neither has no bridge, so an interceptor targeting it is never bound.
+ */
+function extractApiRouteInterceptorBridges(file: ts.SourceFile, context: StaticContext): ApiRouteInterceptorBridge[] {
+  const exportedMethods = exportedHttpMethods(file)
+  const phasesByMethod = new Map<(typeof HTTP_METHODS)[number], Set<ApiInterceptorPhase>>()
+  const addPhase = (method: (typeof HTTP_METHODS)[number], phase: ApiInterceptorPhase): void => {
+    const phases = phasesByMethod.get(method) ?? new Set<ApiInterceptorPhase>()
+    phases.add(phase)
+    phasesByMethod.set(method, phases)
+  }
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const calleeName = node.expression.text
+      if (calleeName === 'makeCrudRoute') {
+        for (const method of exportedMethods) {
+          addPhase(method, 'before')
+          addPhase(method, 'after')
+        }
+      }
+      const phase = API_INTERCEPTOR_BRIDGE_CALLS[calleeName]
+      if (phase) {
+        const callOptions = node.arguments[0] ? staticValue(node.arguments[0], context) : undefined
+        const declaredMethod = isStaticObject(callOptions) ? stringValue(callOptions.method) : undefined
+        const methods = declaredMethod && isHttpMethodName(declaredMethod) ? [declaredMethod] : exportedMethods
+        for (const method of methods) addPhase(method, phase)
+      }
+    }
+    node.forEachChild(visit)
+  }
+  file.forEachChild(visit)
+  return [...phasesByMethod.entries()]
+    .map(([method, phases]) => ({
+      method,
+      phases: [...phases].sort((left, right) => left.localeCompare(right)),
+    }))
+    .sort((left, right) => left.method.localeCompare(right.method))
+}
+
+/**
+ * Concrete runtime-id owners a module contributes as activation targets: its real
+ * `api/**` route ids (with the interceptor bridges each route actually wires) and
+ * its `commands/**` command ids (dispatched through the command bus). Used
+ * post-selection to synthesize `host-reference`/`owner-reference` bindings with a
+ * portable source.
+ */
+export function extractActivationTargetOwners(options: {
+  moduleId: string
+  moduleRoot: string
+  sourceRoot: string
+}): {
+  apiRoutes: Array<{ id: string; source: ModuleFactSourceRef; bridges: ApiRouteInterceptorBridge[] }>
+  commands: Array<{ id: string; source: ModuleFactSourceRef }>
+} {
+  const apiRoutes: Array<{ id: string; source: ModuleFactSourceRef; bridges: ApiRouteInterceptorBridge[] }> = []
+  for (const filePath of sourceFilesBelow(path.join(options.moduleRoot, 'api'))) {
+    const routeId = apiRouteId(options.moduleId, options.moduleRoot, filePath)
+    if (!routeId) continue
+    const file = sourceFile(filePath)
+    const bridges = file ? extractApiRouteInterceptorBridges(file, buildStaticContext(file)) : []
+    apiRoutes.push({
+      id: routeId,
+      source: { sourcePath: portablePath(options.moduleRoot, options.sourceRoot, filePath) },
+      bridges,
+    })
+  }
+  const commands: Array<{ id: string; source: ModuleFactSourceRef }> = []
+  const seenCommands = new Set<string>()
+  for (const filePath of sourceFilesBelow(path.join(options.moduleRoot, 'commands'))) {
+    if (path.basename(filePath).replace(/\.(?:ts|tsx)$/, '') === 'interceptors') continue
+    const source: ModuleFactSourceRef = { sourcePath: portablePath(options.moduleRoot, options.sourceRoot, filePath) }
+    for (const id of extractCommandIdsFromSource(filePath)) {
+      if (seenCommands.has(id)) continue
+      seenCommands.add(id)
+      commands.push({ id, source })
+    }
+  }
+  return { apiRoutes, commands }
+}
+
 function extractFactRefHosts(options: ExtractModuleExtensionFactsOptions): ModuleExtensionHostFact[] {
   const hosts: ModuleExtensionHostFact[] = []
   for (const entity of options.entities) {
@@ -816,6 +972,7 @@ function extractFactRefHosts(options: ExtractModuleExtensionFactsOptions): Modul
         family: 'query-lifecycle',
         capabilities: ['sync-subscriber'],
         factSection: 'searchEntities',
+        factKey: entityId,
         phases: phase === 'querying' ? ['block', 'query-transform'] : ['result-transform', 'scope-reapply'],
         activation: 'caller-opt-in',
         scopeContract: 'tenant-and-organization-reapplied-after-result',
@@ -824,7 +981,8 @@ function extractFactRefHosts(options: ExtractModuleExtensionFactsOptions): Modul
   }
   const apiHosts = apiExtensionHostIds(options.moduleId, options.moduleRoot)
   for (const entityId of apiHosts.entityIds) {
-    hosts.push(factRefHost({
+    const declaringFile = apiHosts.entitySourceFiles[entityId]
+    const host = factRefHost({
       key: `api-entity.${entityId}`,
       id: entityId,
       moduleId: options.moduleId,
@@ -833,7 +991,17 @@ function extractFactRefHosts(options: ExtractModuleExtensionFactsOptions): Modul
       factSection: 'apiRoutes',
       activation: 'host-opt-in',
       scopeContract: 'tenant-and-organization',
-    }))
+    })
+    hosts.push(declaringFile
+      ? {
+          ...host,
+          source: {
+            kind: 'declaration',
+            path: portablePath(options.moduleRoot, options.sourceRoot, declaringFile),
+            symbol: entityId,
+          },
+        }
+      : host)
   }
   return sortHosts([...new Map(hosts.map((host) => [`${host.family}:${host.id}`, host])).values()])
 }
@@ -944,7 +1112,12 @@ function extractEnrichers(options: ExtractModuleExtensionFactsOptions): ModuleEx
       const targetEntity = stringValue(entry.targetEntity)
       if (!targetEntity) return null
       const timeoutMs = numberValue(entry.timeout) ?? 2000
-      const queryEngine = isStaticObject(entry.queryEngine) ? entry.queryEngine : null
+      const queryEngineConfig = isStaticObject(entry.queryEngine) ? entry.queryEngine : null
+      // `enricher-registry` selects query-engine enrichers by `queryEngine.enabled === true`,
+      // so a config object that omits it (or sets it false) is NOT query-enabled.
+      const queryEngine = queryEngineConfig && booleanValue(queryEngineConfig.enabled) === true
+        ? queryEngineConfig
+        : null
       const surfaces = [entry.enrichMany === true ? 'list' : null, entry.enrichOne === true ? 'detail' : null]
         .filter((value): value is 'list' | 'detail' => value !== null)
       const base = contributionBase(id, sourcePath, id)
@@ -1097,14 +1270,13 @@ function extractSubscribers(options: ExtractModuleExtensionFactsOptions): Module
   const directory = path.join(options.moduleRoot, 'subscribers')
   if (!fs.existsSync(directory)) return []
   const facts: ModuleExtensionContributionFact[] = []
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-    if (!entry.isFile() || !/\.(?:ts|tsx)$/.test(entry.name) || /\.(?:test|spec)\./.test(entry.name)) continue
-    const filePath = path.join(directory, entry.name)
+  for (const filePath of sourceFilesBelow(directory)) {
     const metadata = readRootObject(filePath, 'metadata')
     if (!metadata) continue
     const event = stringValue(metadata.event)
     if (!event) continue
-    const subscriberId = stringValue(metadata.id) ?? `${options.moduleId}:${entry.name.replace(/\.tsx?$/, '')}`
+    const relativeStem = path.relative(directory, filePath).replace(/\.tsx?$/, '').split(path.sep).join('/')
+    const subscriberId = stringValue(metadata.id) ?? `${options.moduleId}:${relativeStem}`
     const persistent = booleanValue(metadata.persistent) ?? false
     const sync = booleanValue(metadata.sync) ?? !persistent
     const contribution = contributionBase(subscriberId, portablePath(options.moduleRoot, options.sourceRoot, filePath), 'metadata')
@@ -1152,7 +1324,8 @@ function extractNotificationReactions(options: ExtractModuleExtensionFactsOption
     build(entry, sourcePath, index) {
       const notificationType = stringValue(entry.notificationType)
       if (!notificationType) return null
-      const id = stringValue(entry.id) ?? `${options.moduleId}.notification-handler.${index}`
+      const declaredId = stringValue(entry.id)
+      const id = declaredId ?? `${options.moduleId}.notification-handler.${index}`
       const contribution = contributionBase(id, sourcePath, 'notificationHandlers')
       return {
         ...contribution,
@@ -1164,6 +1337,7 @@ function extractNotificationReactions(options: ExtractModuleExtensionFactsOption
           transports: ['notification-effect'],
           hooks: ['useNotificationEffect'],
           audienceScopeContract: 'tenant-organization-user-role-and-customer',
+          ...(declaredId ? { overrideKey: declaredId } : {}),
         },
       }
     },
@@ -1238,21 +1412,37 @@ function extractSpecializedRegistries(options: ExtractModuleExtensionFactsOption
 
   const integrationPath = conventionPath(options.moduleRoot, 'integration.ts')
   if (integrationPath) {
-    const integration = readRootObject(integrationPath, 'integration')
     const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, integrationPath)
-    const integrationId = integration ? stringValue(integration.id) : undefined
-    if (integrationId) add(integrationId, 'integration', sourcePath, 'integrations', 'integration')
-    const providerKey = integration ? stringValue(integration.providerKey) : undefined
-    const category = integration ? stringValue(integration.category) : undefined
-    const categoryRegistry = category === 'payment' ? 'payment'
-      : category === 'shipping' ? 'shipping'
-        : category === 'currency' ? 'currency'
-          : null
-    if (providerKey && categoryRegistry) {
-      const specialistRoute = categoryRegistry === 'payment' ? 'paymentGateways'
-        : categoryRegistry === 'shipping' ? 'shippingCarriers'
-          : 'currencies'
-      add(providerKey, categoryRegistry, sourcePath, specialistRoute, 'integration.providerKey')
+    const addIntegration = (integration: StaticObject, symbol: string, bundleId?: string): void => {
+      const integrationId = stringValue(integration.id)
+      if (integrationId) {
+        add(integrationId, 'integration', sourcePath, 'integrations', bundleId ? `${symbol}[${bundleId}]` : symbol)
+      }
+      const providerKey = stringValue(integration.providerKey)
+      const category = stringValue(integration.category)
+      const categoryRegistry = category === 'payment' ? 'payment'
+        : category === 'shipping' ? 'shipping'
+          : category === 'currency' ? 'currency'
+            : null
+      if (providerKey && categoryRegistry) {
+        const specialistRoute = categoryRegistry === 'payment' ? 'paymentGateways'
+          : categoryRegistry === 'shipping' ? 'shippingCarriers'
+            : 'currencies'
+        add(providerKey, categoryRegistry, sourcePath, specialistRoute, `${symbol}.providerKey`)
+      }
+    }
+    const singular = readRootObject(integrationPath, 'integration')
+    if (singular) addIntegration(singular, 'integration')
+    for (const integration of readConventionObjectArray(integrationPath, 'integrations')) {
+      addIntegration(integration, 'integrations')
+    }
+    const bundle = readRootObject(integrationPath, 'integrationBundle') ?? readRootObject(integrationPath, 'bundle')
+    if (bundle) {
+      const bundleId = stringValue(bundle.id) ?? 'bundle'
+      const members = Array.isArray(bundle.integrations) ? bundle.integrations : []
+      for (const member of members) {
+        if (isStaticObject(member)) addIntegration(member, 'integrationBundle', bundleId)
+      }
     }
   }
 
@@ -1317,6 +1507,241 @@ function extractSpecializedRegistries(options: ExtractModuleExtensionFactsOption
   return facts
 }
 
+/**
+ * Closed activation-adapter registry (Spec 2). Each `ModuleExtensionActivationKind`
+ * maps to the contribution kinds it can bind and to the mode by which a `bound`
+ * resolution is proven:
+ *
+ * - `call-site-object` — the host module owns a distinct opt-in call site (a
+ *   `makeCrudRoute` option or a mutation-guard bridge). Presence of the option —
+ *   NOT mere entity/route existence — produces an emitted `ModuleExtensionActivation`
+ *   object. This is what makes "the entity could host X" (capability-only) different
+ *   from "this route actually activates X" (bound).
+ * - `host-reference` — the runtime bridge is universal for any matching host
+ *   (every api route runs the interceptor pipeline; a bound widget/component host
+ *   proves consumption). No object is duplicated; `bound` is derived from the
+ *   existing bound host fact and the incoming row carries no `activationId`.
+ * - `owner-reference` — like host-reference but proven by the target module owning
+ *   the concrete runtime id (command ids have no host fact of their own).
+ *
+ * The registry is exhaustive by construction: the `Record` key set is the full
+ * `ModuleExtensionActivationKind` union, so adding a kind fails the typecheck until
+ * it is classified. `activation-adapter-coverage.test.ts` re-checks this at runtime.
+ */
+type ActivationAdapterMode = 'call-site-object' | 'host-reference' | 'owner-reference'
+
+export const ACTIVATION_ADAPTERS: Record<ModuleExtensionActivationKind, {
+  contributionKinds: ModuleExtensionContributionKind[]
+  mode: ActivationAdapterMode
+}> = {
+  'crud-response-enricher': { contributionKinds: ['response-enricher'], mode: 'call-site-object' },
+  'query-enricher': { contributionKinds: ['response-enricher'], mode: 'call-site-object' },
+  'mutation-guard': { contributionKinds: ['mutation-guard'], mode: 'call-site-object' },
+  'api-interceptor-bridge': { contributionKinds: ['api-interceptor'], mode: 'host-reference' },
+  'command-interceptor-bridge': { contributionKinds: ['command-interceptor'], mode: 'owner-reference' },
+  'widget-injection-consumer': { contributionKinds: ['widget', 'data-table', 'crud-form'], mode: 'host-reference' },
+  'component-extension-consumer': { contributionKinds: ['component-override'], mode: 'host-reference' },
+  'dashboard-host-consumer': { contributionKinds: ['widget'], mode: 'host-reference' },
+}
+
+/**
+ * Every UMES contribution kind classified against the activation registry: either
+ * the ordered set of activation kinds that can bind it, or `capability-only` for
+ * contributions that are always active by declaration/registration and never gain
+ * a route/entity activation. Exhaustive by `Record` construction — a new kind fails
+ * the typecheck until classified.
+ */
+export const CONTRIBUTION_ACTIVATION_CLASSIFICATION: Record<
+  ModuleExtensionContributionKind,
+  ModuleExtensionActivationKind[] | 'capability-only'
+> = {
+  'response-enricher': ['crud-response-enricher', 'query-enricher'],
+  'mutation-guard': ['mutation-guard'],
+  'api-interceptor': ['api-interceptor-bridge'],
+  'command-interceptor': ['command-interceptor-bridge'],
+  'widget': ['widget-injection-consumer', 'dashboard-host-consumer'],
+  'data-table': ['widget-injection-consumer'],
+  'crud-form': ['widget-injection-consumer'],
+  'component-override': ['component-extension-consumer'],
+  'entity-extension': 'capability-only',
+  'subscriber': 'capability-only',
+  'browser-reaction': 'capability-only',
+  'specialized-registry': 'capability-only',
+  'module-override': 'capability-only',
+}
+
+export const ALL_ACTIVATION_KINDS = Object.keys(ACTIVATION_ADAPTERS) as ModuleExtensionActivationKind[]
+export const ALL_CONTRIBUTION_KINDS = Object.keys(CONTRIBUTION_ACTIVATION_CLASSIFICATION) as ModuleExtensionContributionKind[]
+
+/**
+ * Verified mutation-guard bridge shapes. The canonical route helper nests the
+ * resource under `input` (`runRouteMutationGuards({ …, input: { resourceKind } })`),
+ * while the legacy helpers take the resource object directly. Module wrappers around
+ * the canonical helper live under `lib/` as often as under `api/`, so both trees are
+ * scanned.
+ */
+const MUTATION_GUARD_BRIDGE_ADAPTERS: Record<string, { resourceArgument: 'input-property' | 'any-argument' }> = {
+  runRouteMutationGuards: { resourceArgument: 'input-property' },
+  validateCrudMutationGuard: { resourceArgument: 'any-argument' },
+  runMutationGuards: { resourceArgument: 'any-argument' },
+}
+
+const MUTATION_GUARD_SOURCE_DIRECTORIES = ['api', 'lib'] as const
+
+const MUTATION_GUARD_OPERATIONS = new Set(['create', 'update', 'delete', 'custom'])
+
+/**
+ * `'custom'` action endpoints are mapped by `toRegistryMutationOperation` onto the
+ * closest registry operation, `'update'`.
+ */
+function toRegistryGuardOperation(operation: string): string {
+  return operation === 'custom' ? 'update' : operation
+}
+
+function readMutationGuardBridge(
+  node: ts.CallExpression,
+  context: StaticContext,
+): { entityId: string; operations: string[] } | null {
+  const callee = node.expression
+  const calleeName = ts.isIdentifier(callee)
+    ? callee.text
+    : ts.isPropertyAccessExpression(callee)
+      ? callee.name.text
+      : null
+  const adapter = calleeName ? MUTATION_GUARD_BRIDGE_ADAPTERS[calleeName] : undefined
+  if (!adapter) return null
+
+  const argumentObjects = node.arguments
+    .map((argument) => staticValue(argument, context))
+    .filter(isStaticObject)
+  const resourceObjects = adapter.resourceArgument === 'input-property'
+    ? argumentObjects.flatMap((argumentObject) => (isStaticObject(argumentObject.input) ? [argumentObject.input] : []))
+    : argumentObjects
+  for (const resourceObject of resourceObjects) {
+    const entityId = stringValue(resourceObject.resourceKind) ?? stringValue(resourceObject.entityId)
+    if (!entityId) continue
+    const declaredOperation = stringValue(resourceObject.operation)
+    const operations = declaredOperation && MUTATION_GUARD_OPERATIONS.has(declaredOperation)
+      ? [toRegistryGuardOperation(declaredOperation)]
+      : []
+    return { entityId, operations }
+  }
+  return null
+}
+
+function nodeLine(file: ts.SourceFile, node: ts.Node): number {
+  return file.getLineAndCharacterOfPosition(node.getStart(file)).line + 1
+}
+
+function activationId(host: ModuleExtensionTargetRef, kind: ModuleExtensionActivationKind): string {
+  const method = host.method ? `:${host.method}` : ''
+  return `${host.kind}:${host.id}${method}:${kind}`
+}
+
+function sortActivations(activations: ModuleExtensionActivation[]): ModuleExtensionActivation[] {
+  return [...activations].sort((left, right) => left.id.localeCompare(right.id))
+}
+
+/**
+ * Extract the `call-site-object` activations (CRUD response/query enrichers and
+ * mutation guards) from a module's real `api/**` opt-in sites. Entity or route
+ * presence alone never lands here — only a literal `enrichers: { entityId }`
+ * option or a mutation-guard bridge call with a static `resourceKind`/`entityId`.
+ */
+/**
+ * `<engine>.query(entityId, { …, extensions })` — the only call shape that enables the
+ * query-engine enricher and sync query-lifecycle stages.
+ */
+function isQueryWithExtensionsCall(node: ts.Node, context: StaticContext): node is ts.CallExpression {
+  if (!ts.isCallExpression(node)) return false
+  const callee = node.expression
+  const calleeName = ts.isPropertyAccessExpression(callee)
+    ? callee.name.text
+    : ts.isIdentifier(callee)
+      ? callee.text
+      : null
+  if (calleeName !== 'query') return false
+  const queryOptions = node.arguments[1] ? staticValue(node.arguments[1], context) : undefined
+  return isStaticObject(queryOptions) && queryOptions.extensions !== undefined
+}
+
+function extractCallSiteActivations(options: ExtractModuleExtensionFactsOptions): ModuleExtensionActivation[] {
+  const activations: ModuleExtensionActivation[] = []
+  const byId = new Map<string, ModuleExtensionActivation>()
+  const push = (activation: ModuleExtensionActivation): void => {
+    const existing = byId.get(activation.id)
+    if (existing) {
+      if (!existing.operations || !activation.operations) {
+        delete existing.operations
+      } else {
+        existing.operations = [...new Set([...existing.operations, ...activation.operations])]
+          .sort((left, right) => left.localeCompare(right))
+      }
+      return
+    }
+    byId.set(activation.id, activation)
+    activations.push(activation)
+  }
+  const scannedFiles = MUTATION_GUARD_SOURCE_DIRECTORIES
+    .flatMap((directory) => sourceFilesBelow(path.join(options.moduleRoot, directory)))
+  for (const filePath of scannedFiles) {
+    const file = sourceFile(filePath)
+    if (!file) continue
+    const context = buildStaticContext(file)
+    const sourcePath = portablePath(options.moduleRoot, options.sourceRoot, filePath)
+    const visit = (node: ts.Node): void => {
+      // `enrichers: { entityId }` on a CRUD route runs `applyResponseEnrichers` after the
+      // list/detail hook. It does NOT enable the query-engine enricher stage.
+      if (ts.isPropertyAssignment(node) && propertyName(node.name) === 'enrichers') {
+        const config = staticValue(node.initializer, context)
+        const entityId = isStaticObject(config) ? stringValue(config.entityId) : undefined
+        if (entityId) {
+          const host: ModuleExtensionTargetRef = { kind: 'entity', id: entityId, moduleId: options.moduleId }
+          push({
+            id: activationId(host, 'crud-response-enricher'),
+            kind: 'crud-response-enricher',
+            host,
+            contributionKinds: ['response-enricher'],
+            source: { sourcePath, line: nodeLine(file, node) },
+          })
+        }
+      }
+      // The query-engine enricher stage runs only for a query that passes `extensions`,
+      // so the bound call site is `queryEngine.query('<entityId>', { …, extensions })`.
+      if (isQueryWithExtensionsCall(node, context)) {
+        const entityId = stringValue(staticValue(node.arguments[0], context))
+        if (entityId) {
+          const host: ModuleExtensionTargetRef = { kind: 'entity', id: entityId, moduleId: options.moduleId }
+          push({
+            id: activationId(host, 'query-enricher'),
+            kind: 'query-enricher',
+            host,
+            contributionKinds: ['response-enricher'],
+            source: { sourcePath, line: nodeLine(file, node) },
+          })
+        }
+      }
+      if (ts.isCallExpression(node)) {
+        const bridge = readMutationGuardBridge(node, context)
+        if (bridge) {
+          const host: ModuleExtensionTargetRef = { kind: 'entity', id: bridge.entityId, moduleId: options.moduleId }
+          push({
+            id: activationId(host, 'mutation-guard'),
+            kind: 'mutation-guard',
+            host,
+            contributionKinds: ['mutation-guard'],
+            ...(bridge.operations.length > 0 ? { operations: bridge.operations } : {}),
+            source: { sourcePath, line: nodeLine(file, node) },
+          })
+        }
+      }
+      node.forEachChild(visit)
+    }
+    file.forEachChild(visit)
+  }
+  return sortActivations(activations)
+}
+
 export function extractModuleExtensionFacts(options: ExtractModuleExtensionFactsOptions): ModuleExtensionSurfaceFacts {
   const declared = extractDeclaredHosts(options)
   const hosts = sortHosts([...declared.hosts, ...extractFactRefHosts(options)])
@@ -1333,7 +1758,12 @@ export function extractModuleExtensionFacts(options: ExtractModuleExtensionFacts
     ...extractComponentOverrides(options),
     ...extractSpecializedRegistries(options),
   ])
-  return { hosts, contributions, unresolved: declared.unresolved }
+  return {
+    hosts,
+    contributions,
+    unresolved: declared.unresolved,
+    activations: extractCallSiteActivations(options),
+  }
 }
 
 function patternMatches(pattern: string, targetId: string): boolean {
@@ -1390,7 +1820,7 @@ export function correlateExtensionTarget(
     return { id: targetFact.id, resolution: 'fact-ref', factRef: { factSection: 'events', factKey: targetFact.id } }
   }
   if (options.commandIds?.has(targetFact.id)) {
-    return factTarget(targetFact.id, 'commands')
+    return factTarget(targetFact.id, 'ownedContracts.command')
   }
   const route = [...options.apiRoutes].find((apiRoute) => apiRoute === targetFact.id || apiRoute.endsWith(`/${targetFact.id}`))
   if (route) return { id: targetFact.id, resolution: 'fact-ref', factRef: { factSection: 'apiRoutes', factKey: route } }
@@ -1428,11 +1858,460 @@ export function correlateModuleExtensionFacts(options: CorrelateExtensionFactsOp
       hosts: sortHosts([...surface.hosts]),
       contributions: sortContributions(contributions),
       unresolved: unresolved.sort((left, right) => left.key.localeCompare(right.key)),
+      activations: sortActivations([...(surface.activations ?? [])]),
     }
   }
   return result
 }
 
+type IncomingTargetOwner = {
+  moduleId: string
+  source: ModuleFactSourceRef
+  /** Interceptor bridges the owning api route wires (api-route owners only). */
+  bridges?: ApiRouteInterceptorBridge[]
+}
+
+export interface CorrelateIncomingExtensionsOptions {
+  surfacesByModule: Readonly<Record<string, ModuleExtensionSurfaceFacts>>
+  /** Concrete runtime-id owner maps derived from the fully-selected module set. */
+  apiRouteOwners?: ReadonlyMap<string, IncomingTargetOwner>
+  commandOwners?: ReadonlyMap<string, IncomingTargetOwner>
+}
+
+function normalizeRouteId(routeId: string): string {
+  return routeId.replace(/^\//, '')
+}
+
+/**
+ * Owner marker for a contribution bound to a framework host (dashboard, menus,
+ * notifications, …). Framework hosts have no module surface of their own, so the
+ * activation is recorded on the contributor and never produces an incoming row.
+ */
+const FRAMEWORK_HOST_OWNER = 'framework'
+
+/**
+ * Framework host families each host-reference adapter may bind, so a dashboard
+ * contribution resolves through `dashboard-host-consumer` rather than being claimed
+ * by the generic widget-injection adapter that runs first.
+ */
+const FRAMEWORK_HOST_FAMILIES_BY_ACTIVATION: Partial<Record<ModuleExtensionActivationKind, ExtensionHostFamily[]>> = {
+  'dashboard-host-consumer': ['dashboard'],
+  'widget-injection-consumer': ['menu', 'generic', 'crud-form', 'data-table', 'notification', 'integration'],
+  'component-extension-consumer': ['component-handle'],
+}
+
+/**
+ * Resolves a target id against the framework host catalog — exact ids first, then
+ * the patterned entries (`dashboard:*`, `crud-form:*`, `integrations.detail:{id}`),
+ * so a concrete `dashboard:<widget>` contribution reaches `framework.dashboard`.
+ */
+function findFrameworkHost(
+  targetId: string,
+  activationKind: ModuleExtensionActivationKind,
+): ModuleExtensionHostFact | null {
+  const families = FRAMEWORK_HOST_FAMILIES_BY_ACTIVATION[activationKind]
+  if (!families) return null
+  const candidates = FRAMEWORK_HOSTS.filter((host) => families.includes(host.family))
+  const exact = candidates.find((host) => host.id === targetId)
+  if (exact) return exact
+  return candidates.find((host) => host.resolution === 'pattern' && patternMatches(host.id, targetId)) ?? null
+}
+
+/**
+ * A call site that guards only some operations does not activate a contribution
+ * declaring none of them. Either side leaving operations undeclared means "any".
+ */
+function operationsIntersect(
+  activationOperations: readonly string[] | undefined,
+  contributionOperations: readonly string[] | undefined,
+): boolean {
+  if (!activationOperations || activationOperations.length === 0) return true
+  if (!contributionOperations || contributionOperations.length === 0) return true
+  return contributionOperations.some((operation) => activationOperations.includes(operation))
+}
+
+function contributionSourceRef(contribution: ModuleExtensionContributionFact): ModuleFactSourceRef {
+  return {
+    sourcePath: contribution.source.path,
+    ...(contribution.source.symbol ? { exportName: contribution.source.symbol } : {}),
+  }
+}
+
+function targetRefKindFor(
+  contribution: ModuleExtensionContributionFact,
+  targetId: string,
+): ModuleExtensionTargetRef['kind'] {
+  if (targetId === '*' || targetId.includes('*') || targetId.includes('{')) return 'wildcard'
+  switch (contribution.kind) {
+    case 'response-enricher':
+    case 'mutation-guard':
+    case 'entity-extension':
+      return 'entity'
+    case 'api-interceptor':
+      return 'api-route'
+    case 'command-interceptor':
+      return 'command'
+    case 'component-override':
+      return 'component'
+    case 'subscriber':
+      return 'event'
+    case 'browser-reaction':
+      return contribution.details.transports.includes('notification-effect') ? 'notification' : 'event'
+    case 'widget':
+    case 'data-table':
+    case 'crud-form':
+      return 'widget-spot'
+    case 'specialized-registry':
+    case 'module-override':
+      return 'module'
+    default:
+      return 'module'
+  }
+}
+
+/**
+ * Builds the bidirectional incoming/resolution index after every module fact is
+ * extracted and target-correlated. For each contribution target it records one
+ * contributor-owned `ModuleContributionResolution` and, when a concrete target
+ * owner exists, one target-owned `ModuleIncomingExtensionRef` per matching
+ * activation. It never duplicates contribution behavior metadata — incoming rows
+ * point back to the source-owned contribution by `contributorModuleId + contributionId`.
+ */
+export function correlateIncomingExtensions(
+  options: CorrelateIncomingExtensionsOptions,
+): Record<string, ModuleExtensionSurfaceFacts> {
+  const moduleIds = Object.keys(options.surfacesByModule).sort((left, right) => left.localeCompare(right))
+  const apiRouteOwners = options.apiRouteOwners ?? new Map<string, IncomingTargetOwner>()
+  const commandOwners = options.commandOwners ?? new Map<string, IncomingTargetOwner>()
+
+  // Index call-site activations by (kind, normalized host id).
+  const activationIndex = new Map<string, Array<{ moduleId: string; activation: ModuleExtensionActivation }>>()
+  const activationKey = (kind: ModuleExtensionActivationKind, hostKind: ModuleExtensionTargetRef['kind'], id: string): string => {
+    const normId = hostKind === 'api-route' ? normalizeRouteId(id) : id
+    return JSON.stringify([kind, hostKind, normId])
+  }
+  // Index bound hosts by their runtime id for host-reference resolution.
+  const boundHostIndex = new Map<string, { moduleId: string; host: ModuleExtensionHostFact }>()
+
+  for (const moduleId of moduleIds) {
+    const surface = options.surfacesByModule[moduleId]
+    for (const activation of surface.activations ?? []) {
+      const key = activationKey(activation.kind, activation.host.kind, activation.host.id)
+      const bucket = activationIndex.get(key)
+      if (bucket) bucket.push({ moduleId, activation })
+      else activationIndex.set(key, [{ moduleId, activation }])
+    }
+    for (const host of surface.hosts) {
+      if (!host.bound) continue
+      if (!boundHostIndex.has(host.id)) boundHostIndex.set(host.id, { moduleId, host })
+    }
+  }
+
+  const incomingByModule: Record<string, ModuleIncomingExtensionRef[]> = {}
+  const resolutionsByModule: Record<string, ModuleContributionResolution[]> = {}
+  const syntheticActivations: Record<string, ModuleExtensionActivation[]> = {}
+  for (const moduleId of moduleIds) {
+    incomingByModule[moduleId] = []
+    resolutionsByModule[moduleId] = []
+    syntheticActivations[moduleId] = []
+  }
+  const registerSyntheticActivation = (ownerModule: string, activation: ModuleExtensionActivation): void => {
+    if (!syntheticActivations[ownerModule]) syntheticActivations[ownerModule] = []
+    if (!syntheticActivations[ownerModule].some((entry) => entry.id === activation.id)) {
+      syntheticActivations[ownerModule].push(activation)
+    }
+  }
+
+  const findCallSiteActivations = (
+    contributionKind: ModuleExtensionContributionKind,
+    activationKinds: ModuleExtensionActivationKind[],
+    targetRef: ModuleExtensionTargetRef,
+    contributionOperations: readonly string[] | undefined,
+  ): Array<{ moduleId: string; activation: ModuleExtensionActivation }> => {
+    const matches: Array<{ moduleId: string; activation: ModuleExtensionActivation }> = []
+    for (const kind of activationKinds) {
+      if (ACTIVATION_ADAPTERS[kind].mode !== 'call-site-object') continue
+      const bucket = activationIndex.get(activationKey(kind, targetRef.kind, targetRef.id)) ?? []
+      for (const entry of bucket) {
+        if (!entry.activation.contributionKinds.includes(contributionKind)) continue
+        if (!operationsIntersect(entry.activation.operations, contributionOperations)) continue
+        matches.push(entry)
+      }
+    }
+    return matches.sort((left, right) => left.activation.id.localeCompare(right.activation.id))
+  }
+
+  for (const contributorModuleId of moduleIds) {
+    const surface = options.surfacesByModule[contributorModuleId]
+    for (const contribution of surface.contributions) {
+      const classification = CONTRIBUTION_ACTIVATION_CLASSIFICATION[contribution.kind]
+      for (const resolvedTarget of contribution.targets) {
+        const targetKind = targetRefKindFor(contribution, resolvedTarget.id)
+        const baseTarget: ModuleExtensionTargetRef = { kind: targetKind, id: resolvedTarget.id }
+
+        let resolution: ModuleExtensionResolution
+        let ownerModule: string | null = null
+        let boundActivationIds: string[] = []
+
+        if (targetKind === 'wildcard' || resolvedTarget.resolution === 'pattern') {
+          resolution = 'wildcard'
+        } else if (resolvedTarget.resolution === 'optional-external') {
+          resolution = 'optional-target-missing'
+        } else if (resolvedTarget.resolution === 'unresolved') {
+          resolution = 'unresolved'
+        } else {
+          const activationKinds = classification === 'capability-only' ? [] : classification
+          const callSiteMatches = findCallSiteActivations(
+            contribution.kind,
+            activationKinds,
+            baseTarget,
+            contribution.operations,
+          )
+          if (callSiteMatches.length > 0) {
+            resolution = 'bound'
+            ownerModule = callSiteMatches[0].moduleId
+            boundActivationIds = callSiteMatches.map((entry) => entry.activation.id)
+          } else {
+            const referenceBinding = resolveReferenceBinding({
+              contribution,
+              activationKinds,
+              targetRef: baseTarget,
+              boundHostIndex,
+              apiRouteOwners,
+              commandOwners,
+            })
+            if (referenceBinding) {
+              resolution = 'bound'
+              // A framework host owns no module surface: record the activation on the
+              // contributor and leave `ownerModule` unset so no incoming row is emitted.
+              const isFrameworkHost = referenceBinding.ownerModule === FRAMEWORK_HOST_OWNER
+              ownerModule = isFrameworkHost ? null : referenceBinding.ownerModule
+              const activationOwner = isFrameworkHost ? contributorModuleId : referenceBinding.ownerModule
+              for (const activation of referenceBinding.activations) {
+                registerSyntheticActivation(activationOwner, activation)
+              }
+              boundActivationIds = referenceBinding.activations.map((activation) => activation.id)
+            } else {
+              const hostOwner = boundHostIndex.get(resolvedTarget.id)
+              if (hostOwner) {
+                resolution = 'capability-only'
+                ownerModule = hostOwner.moduleId
+              } else {
+                resolution = 'capability-only'
+                ownerModule = null
+              }
+            }
+          }
+        }
+
+        const resolutionTarget: ModuleExtensionTargetRef = ownerModule
+          ? { ...baseTarget, moduleId: ownerModule }
+          : baseTarget
+        resolutionsByModule[contributorModuleId].push({
+          contributionId: contribution.id,
+          target: resolutionTarget,
+          resolution,
+          activationIds: [...boundActivationIds].sort((left, right) => left.localeCompare(right)),
+        })
+
+        // Incoming rows document contributions installed by OTHER modules onto a
+        // target module's surface (cross-module discovery). Same-module targets are
+        // already fully covered by the contributor-owned resolution row above, so
+        // emitting a self-incoming row would only duplicate that fact and bloat the
+        // generated context.
+        if (ownerModule && ownerModule !== contributorModuleId && (resolution === 'bound' || resolution === 'capability-only')) {
+          const source = contributionSourceRef(contribution)
+          const incomingTarget: ModuleExtensionTargetRef = { ...baseTarget, moduleId: ownerModule }
+          if (resolution === 'bound' && boundActivationIds.length > 0) {
+            for (const activationRefId of boundActivationIds) {
+              incomingByModule[ownerModule].push({
+                contributionId: contribution.id,
+                contributionKind: contribution.kind,
+                contributorModuleId,
+                target: incomingTarget,
+                activationId: activationRefId,
+                resolution: 'bound',
+                source,
+              })
+            }
+          } else {
+            incomingByModule[ownerModule].push({
+              contributionId: contribution.id,
+              contributionKind: contribution.kind,
+              contributorModuleId,
+              target: incomingTarget,
+              resolution,
+              source,
+            })
+          }
+        }
+      }
+    }
+  }
+
+  const result: Record<string, ModuleExtensionSurfaceFacts> = {}
+  for (const moduleId of moduleIds) {
+    const surface = options.surfacesByModule[moduleId]
+    result[moduleId] = {
+      ...surface,
+      activations: sortActivations([...(surface.activations ?? []), ...syntheticActivations[moduleId]]),
+      incoming: dedupeIncoming(incomingByModule[moduleId]),
+      contributionResolutions: sortResolutions(resolutionsByModule[moduleId]),
+    }
+  }
+  return result
+}
+
+/**
+ * Intersects an api-interceptor contribution's declared methods and phases with the
+ * bridges its target route actually wires. A route with no bridge, a phase the route
+ * never runs, or a method the route does not handle yields no binding, so the
+ * contribution stays `capability-only` instead of being reported as active.
+ */
+function matchApiInterceptorBridges(
+  contribution: ModuleExtensionContributionFact,
+  owner: IncomingTargetOwner,
+): ApiRouteInterceptorBridge[] {
+  if (contribution.kind !== 'api-interceptor') return []
+  const bridges = owner.bridges ?? []
+  const declaredMethods = contribution.details.methods ?? []
+  const declaredPhases = contribution.phases ?? []
+  const matched: ApiRouteInterceptorBridge[] = []
+  for (const bridge of bridges) {
+    if (declaredMethods.length > 0 && !declaredMethods.includes(bridge.method)) continue
+    const phases = declaredPhases.length > 0
+      ? bridge.phases.filter((phase) => declaredPhases.includes(phase))
+      : bridge.phases
+    if (phases.length === 0) continue
+    matched.push({ method: bridge.method, phases })
+  }
+  return matched
+}
+
+function resolveReferenceBinding(input: {
+  contribution: ModuleExtensionContributionFact
+  activationKinds: ModuleExtensionActivationKind[]
+  targetRef: ModuleExtensionTargetRef
+  boundHostIndex: ReadonlyMap<string, { moduleId: string; host: ModuleExtensionHostFact }>
+  apiRouteOwners: ReadonlyMap<string, IncomingTargetOwner>
+  commandOwners: ReadonlyMap<string, IncomingTargetOwner>
+}): { ownerModule: string; activations: ModuleExtensionActivation[] } | null {
+  for (const kind of input.activationKinds) {
+    const adapter = ACTIVATION_ADAPTERS[kind]
+    if (adapter.mode === 'call-site-object') continue
+    if (!adapter.contributionKinds.includes(input.contribution.kind)) continue
+
+    if (adapter.mode === 'host-reference' && kind === 'api-interceptor-bridge') {
+      const routeId = normalizeRouteId(input.targetRef.id)
+      const owner = input.apiRouteOwners.get(routeId)
+      if (!owner) continue
+      const matchedBridges = matchApiInterceptorBridges(input.contribution, owner)
+      if (matchedBridges.length === 0) continue
+      return {
+        ownerModule: owner.moduleId,
+        activations: matchedBridges.map((bridge) => {
+          const host: ModuleExtensionTargetRef = {
+            kind: 'api-route',
+            id: routeId,
+            moduleId: owner.moduleId,
+            method: bridge.method,
+          }
+          return {
+            id: activationId(host, kind),
+            kind,
+            host,
+            contributionKinds: ['api-interceptor'],
+            phases: bridge.phases,
+            source: owner.source,
+            bridge: { factSection: 'apiRoutes', factKey: `/${routeId}` },
+          }
+        }),
+      }
+    }
+
+    if (adapter.mode === 'owner-reference' && kind === 'command-interceptor-bridge') {
+      const owner = input.commandOwners.get(input.targetRef.id)
+      if (!owner) continue
+      const host: ModuleExtensionTargetRef = { kind: 'command', id: input.targetRef.id, moduleId: owner.moduleId }
+      return {
+        ownerModule: owner.moduleId,
+        activations: [{
+          id: activationId(host, kind),
+          kind,
+          host,
+          contributionKinds: ['command-interceptor'],
+          source: owner.source,
+          bridge: { factSection: 'ownedContracts.command', factKey: input.targetRef.id },
+        }],
+      }
+    }
+
+    if (adapter.mode === 'host-reference' && (kind === 'widget-injection-consumer' || kind === 'component-extension-consumer' || kind === 'dashboard-host-consumer')) {
+      const frameworkHostFact = input.boundHostIndex.has(input.targetRef.id)
+        ? null
+        : findFrameworkHost(input.targetRef.id, kind)
+      const hostEntry = input.boundHostIndex.get(input.targetRef.id)
+        ?? (frameworkHostFact ? { moduleId: FRAMEWORK_HOST_OWNER, host: frameworkHostFact } : undefined)
+      if (!hostEntry) continue
+      const hostSource = hostReferenceSource(hostEntry.host)
+      if (!hostSource) continue
+      const host: ModuleExtensionTargetRef = { ...input.targetRef, moduleId: hostEntry.moduleId }
+      return {
+        ownerModule: hostEntry.moduleId,
+        activations: [{
+          id: activationId(host, kind),
+          kind,
+          host,
+          contributionKinds: adapter.contributionKinds,
+          source: hostSource,
+          bridge: { factSection: 'hosts', factKey: hostEntry.host.key },
+        }],
+      }
+    }
+  }
+  return null
+}
+
+function hostReferenceSource(host: ModuleExtensionHostFact): ModuleFactSourceRef | null {
+  if (host.source.kind === 'declaration' || host.source.kind === 'framework') {
+    return { sourcePath: host.source.path, exportName: host.source.symbol }
+  }
+  return null
+}
+
+function incomingIdentity(entry: ModuleIncomingExtensionRef): string {
+  const target = JSON.stringify([entry.target.kind, entry.target.id])
+  return JSON.stringify([entry.contributorModuleId, entry.contributionId, target, entry.activationId ?? entry.resolution])
+}
+
+function dedupeIncoming(entries: ModuleIncomingExtensionRef[]): ModuleIncomingExtensionRef[] {
+  const seen = new Set<string>()
+  const unique: ModuleIncomingExtensionRef[] = []
+  for (const entry of entries) {
+    const identity = incomingIdentity(entry)
+    if (seen.has(identity)) continue
+    seen.add(identity)
+    unique.push(entry)
+  }
+  return unique.sort((left, right) => incomingIdentity(left).localeCompare(incomingIdentity(right)))
+}
+
+function resolutionIdentity(entry: ModuleContributionResolution): string {
+  return JSON.stringify([entry.contributionId, entry.target.kind, entry.target.id, entry.resolution])
+}
+
+function sortResolutions(entries: ModuleContributionResolution[]): ModuleContributionResolution[] {
+  const seen = new Set<string>()
+  const unique: ModuleContributionResolution[] = []
+  for (const entry of entries) {
+    const identity = resolutionIdentity(entry)
+    if (seen.has(identity)) continue
+    seen.add(identity)
+    unique.push(entry)
+  }
+  return unique.sort((left, right) => resolutionIdentity(left).localeCompare(resolutionIdentity(right)))
+}
+
 export function assertNoUnresolvedExtensionTargets(
   surfacesByModule: Readonly<Record<string, ModuleExtensionSurfaceFacts>>,
 ): void {
@@ -1446,6 +2325,23 @@ export function assertNoUnresolvedExtensionTargets(
   }
 }
 
+/**
+ * Supported merge/replace/disable modes for each dotted unified-override host,
+ * derived from {@link FRAMEWORK_OVERRIDE_HOSTS} (the framework catalog authority
+ * — spec 2026-08-02-module-facts-exact-override-targets). Keyed by the dotted
+ * host id (e.g. `routes.api`, `ai.extensions`, `nav.groupOrder`) so the module
+ * override-target adapters share one mode source of truth with the catalog.
+ */
+export function getFrameworkOverrideModes(): Record<string, 'disable-replace' | 'replace' | 'additive'> {
+  const modes: Record<string, 'disable-replace' | 'replace' | 'additive'> = {}
+  for (const host of FRAMEWORK_OVERRIDE_HOSTS) {
+    const dotted = host.key.replace(/^framework\.module-override\./, '')
+    const mode = host.operations?.[0]
+    if (mode === 'disable-replace' || mode === 'replace' || mode === 'additive') modes[dotted] = mode
+  }
+  return modes
+}
+
 export function getFrameworkExtensionHosts(): ModuleExtensionHostFact[] {
   return sortHosts(allFrameworkHosts().map((host) => ({
     ...host,