modular

type AppRegistry interface {
	// SvcRegistry retrieves the service registry.
	// The service registry contains all services registered by modules
	// and the application, providing a central location for service lookup.
	SvcRegistry() ServiceRegistry
}

type Application interface {
	// ConfigProvider retrieves the application's main configuration provider.
	// This provides access to application-level configuration that isn't
	// specific to any particular module.
	ConfigProvider() ConfigProvider

	// SvcRegistry retrieves the service registry.
	// Modules use this to register services they provide and lookup
	// services they need from other modules.
	SvcRegistry() ServiceRegistry

	// RegisterModule adds a module to the application.
	// Modules must be registered before calling Init(). The framework
	// will handle initialization order based on declared dependencies.
	//
	// Example:
	//   app.RegisterModule(&DatabaseModule{})
	//   app.RegisterModule(&WebServerModule{})
	RegisterModule(module Module)

	// RegisterConfigSection registers a configuration section with the application.
	// This allows modules to register their configuration requirements,
	// making them available for loading from configuration sources.
	//
	// Example:
	//   cfg := &MyModuleConfig{}
	//   provider := modular.NewStdConfigProvider(cfg)
	//   app.RegisterConfigSection("mymodule", provider)
	RegisterConfigSection(section string, cp ConfigProvider)

	// ConfigSections retrieves all registered configuration sections.
	// Returns a map of section names to their configuration providers.
	// Useful for debugging and introspection.
	ConfigSections() map[string]ConfigProvider

	// GetConfigSection retrieves a specific configuration section.
	// Returns an error if the section doesn't exist.
	//
	// Example:
	//   provider, err := app.GetConfigSection("database")
	//   if err != nil {
	//       return err
	//   }
	//   cfg := provider.GetConfig().(*DatabaseConfig)
	GetConfigSection(section string) (ConfigProvider, error)

	// RegisterService adds a service to the service registry with type checking.
	// Services registered here become available to all modules that declare
	// them as dependencies.
	//
	// Returns an error if a service with the same name is already registered.
	//
	// Example:
	//   db := &DatabaseConnection{}
	//   err := app.RegisterService("database", db)
	RegisterService(name string, service any) error

	// GetService retrieves a service from the registry with type assertion.
	// The target parameter must be a pointer to the expected type.
	// The framework will perform type checking and assignment.
	//
	// Example:
	//   var db *DatabaseConnection
	//   err := app.GetService("database", &db)
	GetService(name string, target any) error

	// Init initializes the application and all registered modules.
	// This method:
	//   - Calls RegisterConfig on all configurable modules
	//   - Loads configuration from all registered sources
	//   - Resolves module dependencies
	//   - Initializes modules in dependency order
	//   - Registers services provided by modules
	//
	// Must be called before Start() or Run().
	Init() error

	// Start starts the application and all startable modules.
	// Modules implementing the Startable interface will have their
	// Start method called in dependency order.
	//
	// This is typically used when you want to start the application
	// but handle the shutdown logic yourself (rather than using Run()).
	Start() error

	// Stop stops the application and all stoppable modules.
	// Modules implementing the Stoppable interface will have their
	// Stop method called in reverse dependency order.
	//
	// Provides a timeout context for graceful shutdown.
	Stop() error

	// Run starts the application and blocks until termination.
	// This is equivalent to calling Init(), Start(), and then waiting
	// for a termination signal (SIGINT, SIGTERM) before calling Stop().
	//
	// This is the most common way to run a modular application:
	//   if err := app.Run(); err != nil {
	//       log.Fatal(err)
	//   }
	Run() error

	// Logger retrieves the application's logger.
	// This logger is used by the framework and can be used by modules
	// for consistent logging throughout the application.
	Logger() Logger

	// SetLogger sets the application's logger.
	// Should be called before module registration to ensure
	// all framework operations use the new logger.
	SetLogger(logger Logger)

	// SetVerboseConfig enables or disables verbose configuration debugging.
	// When enabled, DEBUG level logging will be performed during configuration
	// processing to show which config is being processed, which key is being
	// evaluated, and which attribute or key is being searched for.
	SetVerboseConfig(enabled bool)

	// IsVerboseConfig returns whether verbose configuration debugging is enabled.
	IsVerboseConfig() bool

	// ServiceIntrospector groups advanced service registry introspection helpers.
	// Use this instead of adding new methods directly to Application.
	ServiceIntrospector() ServiceIntrospector
}

type ApplicationBuilder struct {
	// contains filtered or unexported fields
}

type ApplicationDecorator interface {
	Application

	// GetInnerApplication returns the wrapped application
	GetInnerApplication() Application
}

type BaseApplicationDecorator struct {
	// contains filtered or unexported fields
}

type BaseConfigOptions struct {
	// ConfigDir is the root directory containing base/ and environments/ subdirectories
	ConfigDir string
	// Environment specifies which environment overrides to apply (e.g., "prod", "staging", "dev")
	Environment string
	// Enabled determines whether base config support is active
	Enabled bool
}

type BaseLoggerDecorator struct {
	// contains filtered or unexported fields
}

type CloudEvent = cloudevents.Event

type ComplexFeeder interface {
	Feeder
	FeedKey(string, interface{}) error
}

type Config struct {
	// Feeders contains all the registered configuration feeders
	Feeders []Feeder
	// StructKeys maps struct identifiers to their configuration objects.
	// Used internally to track which configuration structures have been processed.
	StructKeys map[string]interface{}
	// VerboseDebug enables detailed logging during configuration processing
	VerboseDebug bool
	// Logger is used for verbose debug logging
	Logger Logger
	// FieldTracker tracks which fields are populated by which feeders
	FieldTracker FieldTracker
}

type ConfigDecorator interface {
	// DecorateConfig takes a base config provider and returns a decorated one
	DecorateConfig(base ConfigProvider) ConfigProvider

	// Name returns the decorator name for debugging
	Name() string
}

type ConfigProvider interface {
	// GetConfig returns the configuration object.
	// The returned value should be a pointer to a struct that represents
	// the configuration schema. Modules typically type-assert this to
	// their expected configuration type.
	//
	// Example:
	//   cfg := provider.GetConfig().(*MyModuleConfig)
	GetConfig() any
}

type ConfigSetup interface {
	Setup() error
}

type ConfigValidator interface {
	// Validate validates the configuration and returns an error if invalid.
	// This method is called automatically by the framework after configuration
	// loading and default value processing. It should return a descriptive
	// error if the configuration is invalid.
	Validate() error
}

type Configurable interface {
	// RegisterConfig registers configuration requirements with the application.
	// This method is called during application initialization before Init().
	//
	// Implementation should:
	//   - Define the configuration structure
	//   - Register the configuration section with app.RegisterConfigSection()
	//   - Set up any configuration validation rules
	//
	// Example:
	//   func (m *MyModule) RegisterConfig(app Application) error {
	//       cfg := &MyModuleConfig{}
	//       provider := modular.NewStdConfigProvider(cfg)
	//       app.RegisterConfigSection(m.Name(), provider)
	//       return nil
	//   }
	RegisterConfig(app Application) error
}

type Constructable interface {
	// Constructor returns a function to construct this module with dependency injection.
	// The returned function should have the signature:
	//   func(app Application, services map[string]any) (Module, error)
	//
	// The services map contains all services that this module declared as requirements.
	// The constructor can also accept individual service types as parameters, and
	// the framework will automatically provide them based on type matching.
	//
	// Example:
	//   func (m *WebModule) Constructor() ModuleConstructor {
	//       return func(app Application, services map[string]any) (Module, error) {
	//           db := services["database"].(Database)
	//           return NewWebModule(db), nil
	//       }
	//   }
	Constructor() ModuleConstructor
}

type DefaultFieldTracker struct {
	FieldPopulations []FieldPopulation
	// contains filtered or unexported fields
}

type DependencyAware interface {
	// Dependencies returns names of other modules this module depends on.
	// The returned slice should contain the exact names returned by
	// the Name() method of the dependency modules.
	//
	// Dependencies are initialized before this module during application startup.
	// If any dependency is missing, application initialization will fail.
	//
	// Example:
	//   func (m *WebModule) Dependencies() []string {
	//       return []string{"database", "auth", "cache"}
	//   }
	Dependencies() []string
}

type DependencyEdge struct {
	From string
	To   string
	Type EdgeType
	// For interface-based dependencies, show which interface is involved
	InterfaceType reflect.Type
	ServiceName   string
}

type DualWriterLoggerDecorator struct {
	*BaseLoggerDecorator
	// contains filtered or unexported fields
}

type EdgeType int

type EnhancedServiceRegistry struct {
	// contains filtered or unexported fields
}

type EventValidationObserver struct {
	// contains filtered or unexported fields
}

type Feeder interface {
	// Feed gets a struct and feeds it using configuration data.
	Feed(structure interface{}) error
}

type FieldPopulation struct {
	FieldPath   string      // Full path to the field (e.g., "Connections.primary.DSN")
	FieldName   string      // Name of the field
	FieldType   string      // Type of the field
	FeederType  string      // Type of feeder that populated it
	SourceType  string      // Type of source (env, yaml, etc.)
	SourceKey   string      // Source key that was used (e.g., "DB_PRIMARY_DSN")
	Value       interface{} // Value that was set
	InstanceKey string      // Instance key for instance-aware fields
	SearchKeys  []string    // All keys that were searched for this field
	FoundKey    string      // The key that was actually found
}

type FieldTracker interface {
	// RecordFieldPopulation records that a field was populated by a feeder
	RecordFieldPopulation(fp FieldPopulation)

	// SetLogger sets the logger for the tracker
	SetLogger(logger Logger)
}

type FieldTrackerBridge struct {
	// contains filtered or unexported fields
}

type FieldTrackingFeeder interface {
	// SetFieldTracker sets the field tracker for this feeder
	SetFieldTracker(tracker FieldTracker)
}

type FileBasedTenantConfigLoader struct {
	// contains filtered or unexported fields
}

type FilterLoggerDecorator struct {
	*BaseLoggerDecorator
	// contains filtered or unexported fields
}

type FunctionalObserver struct {
	// contains filtered or unexported fields
}

type InstanceAwareConfigProvider struct {
	// contains filtered or unexported fields
}

type InstanceAwareConfigSupport interface {
	// GetInstanceConfigs returns a map of instance configurations that should be fed with instance-aware feeders
	GetInstanceConfigs() map[string]interface{}
}

type InstanceAwareFeeder interface {
	ComplexFeeder
	// FeedInstances feeds multiple instances from a map[string]ConfigType
	FeedInstances(instances interface{}) error
}

type InstancePrefixFunc = feeders.InstancePrefixFunc

type InterfaceMatch struct {
	Consumer      string
	Provider      string
	InterfaceType reflect.Type
	ServiceName   string
	Required      bool
}

type LevelModifierLoggerDecorator struct {
	*BaseLoggerDecorator
	// contains filtered or unexported fields
}

type LoadAppConfigFunc func(*StdApplication) error

type Logger interface {
	// Info logs an informational message with optional key-value pairs.
	// Used for normal application events like module startup, service registration, etc.
	//
	// Example:
	//   logger.Info("Module initialized", "module", "database", "version", "1.2.3")
	Info(msg string, args ...any)

	// Error logs an error message with optional key-value pairs.
	// Used for errors that don't prevent application startup but should be noted.
	//
	// Example:
	//   logger.Error("Failed to connect to service", "service", "cache", "error", err)
	Error(msg string, args ...any)

	// Warn logs a warning message with optional key-value pairs.
	// Used for conditions that are unusual but don't prevent normal operation.
	//
	// Example:
	//   logger.Warn("Service unavailable, using fallback", "service", "external-api")
	Warn(msg string, args ...any)

	// Debug logs a debug message with optional key-value pairs.
	// Used for detailed diagnostic information, typically disabled in production.
	//
	// Example:
	//   logger.Debug("Dependency resolved", "from", "module1", "to", "module2")
	Debug(msg string, args ...any)
}

type LoggerDecorator interface {
	Logger

	// GetInnerLogger returns the wrapped logger
	GetInnerLogger() Logger
}

type Module interface {
	// Name returns the unique identifier for this module.
	// The name is used for dependency resolution and service registration.
	// It must be unique within the application and should be descriptive
	// of the module's purpose.
	//
	// Example: "database", "auth", "httpserver", "cache"
	Name() string

	// Init initializes the module with the application context.
	// This method is called during application initialization after
	// all modules have been registered and their configurations loaded.
	//
	// The Init method should:
	//   - Validate any required configuration
	//   - Initialize internal state
	//   - Register any services this module provides
	//   - Prepare for Start() to be called
	//
	// Init is called in dependency order - modules that depend on others
	// are initialized after their dependencies.
	Init(app Application) error
}

type ModuleAwareFeeder interface {
	Feeder
	// FeedWithModuleContext feeds configuration with module context information.
	// The moduleName parameter provides the name of the module whose configuration
	// is being processed, allowing the feeder to customize its behavior accordingly.
	FeedWithModuleContext(structure interface{}, moduleName string) error
}

type ModuleConstructor func(app Application, services map[string]any) (Module, error)

type ModuleLifecyclePayload struct {
	// Subject indicates whether this is a module or application lifecycle event (e.g., "module", "application").
	Subject string `json:"subject"`
	// Name is the module/application name.
	Name string `json:"name"`
	// Action is the lifecycle action (e.g., start|stop|init|register|fail|initialize|initialized).
	Action string `json:"action"`
	// Version optionally records the module version if available.
	Version string `json:"version,omitempty"`
	// Timestamp is when the lifecycle action occurred (RFC3339 in JSON output).
	Timestamp time.Time `json:"timestamp"`
	// Additional arbitrary metadata (kept minimal; prefer evolving the struct if fields become first-class).
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ModuleRegistry map[string]Module

type ModuleWithConstructor interface {
	Module
	Constructable
}

type ObservableApplication struct {
	*StdApplication
	// contains filtered or unexported fields
}

type ObservableDecorator struct {
	*BaseApplicationDecorator
	// contains filtered or unexported fields
}

type ObservableModule interface {
	Module

	// RegisterObservers is called during module initialization to allow
	// the module to register as an observer for events it's interested in.
	// The subject parameter is typically the application itself.
	RegisterObservers(subject Subject) error

	// EmitEvent allows modules to emit their own CloudEvents.
	// This should typically delegate to the application's NotifyObservers method.
	EmitEvent(ctx context.Context, event cloudevents.Event) error

	// GetRegisteredEventTypes returns a list of all event types this module
	// can emit. This is used for validation in testing to ensure all events
	// are properly tested and emitted during execution.
	GetRegisteredEventTypes() []string
}

type Observer interface {
	// OnEvent is called when an event occurs that the observer is interested in.
	// The context can be used for cancellation and timeouts.
	// Observers should handle events quickly to avoid blocking other observers.
	OnEvent(ctx context.Context, event cloudevents.Event) error

	// ObserverID returns a unique identifier for this observer.
	// This ID is used for registration tracking and debugging.
	ObserverID() string
}

type ObserverFunc func(ctx context.Context, event cloudevents.Event) error

type ObserverInfo struct {
	// ID is the unique identifier of the observer
	ID string `json:"id"`

	// EventTypes are the event types this observer is subscribed to.
	// Empty slice means all events.
	EventTypes []string `json:"eventTypes"`

	// RegisteredAt indicates when the observer was registered
	RegisteredAt time.Time `json:"registeredAt"`
}

type Option func(*ApplicationBuilder) error

type PrefixLoggerDecorator struct {
	*BaseLoggerDecorator
	// contains filtered or unexported fields
}

type ServiceAware interface {
	// ProvidesServices returns a list of services provided by this module.
	// These services will be registered in the application's service registry
	// after the module is initialized, making them available to other modules.
	//
	// Each ServiceProvider should specify:
	//   - Name: unique identifier for the service
	//   - Instance: the actual service implementation
	//
	// Example:
	//   func (m *DatabaseModule) ProvidesServices() []ServiceProvider {
	//       return []ServiceProvider{
	//           {Name: "database", Instance: m.db},
	//           {Name: "migrator", Instance: m.migrator},
	//       }
	//   }
	ProvidesServices() []ServiceProvider

	// RequiresServices returns a list of services required by this module.
	// These services must be provided by other modules or the application
	// for this module to function correctly.
	//
	// Services can be matched by name or by interface. When using interface
	// matching, the framework will find any service that implements the
	// specified interface.
	//
	// Example:
	//   func (m *WebModule) RequiresServices() []ServiceDependency {
	//       return []ServiceDependency{
	//           {Name: "database", Required: true},
	//           {Name: "logger", SatisfiesInterface: reflect.TypeOf((*Logger)(nil)).Elem(), MatchByInterface: true},
	//       }
	//   }
	RequiresServices() []ServiceDependency
}

type ServiceDependency struct {
	// Name is the service identifier to lookup.
	// For interface-based matching, this is used as the key in the
	// injected services map but may not correspond to a registered service name.
	Name string

	// Required indicates whether the application should fail to start
	// if this service is not available. Optional services (Required: false)
	// will be silently ignored if not found.
	Required bool

	// Type specifies the concrete type expected for this service.
	// Used for additional type checking during dependency resolution.
	// Optional - if nil, no concrete type checking is performed.
	Type reflect.Type

	// SatisfiesInterface specifies an interface that the service must implement.
	// Used with MatchByInterface to find services by interface rather than name.
	// Obtain with: reflect.TypeOf((*InterfaceName)(nil)).Elem()
	SatisfiesInterface reflect.Type

	// MatchByInterface enables interface-based service lookup.
	// When true, the framework will search for any service that implements
	// SatisfiesInterface rather than looking up by exact name.
	// Useful for loose coupling where modules depend on interfaces rather than specific implementations.
	MatchByInterface bool
}

type ServiceIntrospector interface {
	GetServicesByModule(moduleName string) []string
	GetServiceEntry(serviceName string) (*ServiceRegistryEntry, bool)
	GetServicesByInterface(interfaceType reflect.Type) []*ServiceRegistryEntry
}

type ServiceIntrospectorImpl struct {
	// contains filtered or unexported fields
}

type ServiceProvider struct {
	// Name is the unique identifier for this service.
	// Other modules reference this service by this exact name.
	// Should be descriptive and follow naming conventions like "database", "logger", "cache".
	Name string

	// Description provides human-readable documentation for this service.
	// Used for debugging and documentation purposes.
	// Example: "PostgreSQL database connection pool"
	Description string

	// Instance is the actual service implementation.
	// Can be any type - struct, interface implementation, function, etc.
	// Consuming modules are responsible for type assertion.
	Instance any
}

type ServiceRegistry map[string]any

type ServiceRegistryEntry struct {
	// Service is the actual service instance
	Service any

	// ModuleName is the name of the module that provided this service
	ModuleName string

	// ModuleType is the reflect.Type of the module that provided this service
	ModuleType reflect.Type

	// OriginalName is the original name requested when registering the service
	OriginalName string

	// ActualName is the final name used in the registry (may be modified for uniqueness)
	ActualName string
}

type StandardTenantService struct {
	// contains filtered or unexported fields
}

type Startable interface {
	// Start begins the module's runtime operations.
	// This method is called after Init() and after all modules have been initialized.
	// Start is called in dependency order - dependencies start before dependents.
	//
	// The provided context is the application's lifecycle context. When this
	// context is cancelled, the module should stop its operations gracefully.
	//
	// Start should be non-blocking for short-running initialization, but may
	// spawn goroutines for long-running operations. Use the provided context
	// to handle graceful shutdown.
	//
	// Example:
	//   func (m *HTTPServerModule) Start(ctx context.Context) error {
	//       go func() {
	//           <-ctx.Done()
	//           m.server.Shutdown(context.Background())
	//       }()
	//       return m.server.ListenAndServe()
	//   }
	Start(ctx context.Context) error
}

type StdApplication struct {
	// contains filtered or unexported fields
}

type StdConfigProvider struct {
	// contains filtered or unexported fields
}

type Stoppable interface {
	// Stop performs graceful shutdown of the module.
	// This method is called during application shutdown, in reverse dependency
	// order (dependents stop before their dependencies).
	//
	// The provided context includes a timeout for the shutdown process.
	// Modules should respect this timeout and return promptly when it expires.
	//
	// Stop should:
	//   - Stop accepting new work
	//   - Complete or cancel existing work
	//   - Close resources and connections
	//   - Return any critical errors that occurred during shutdown
	//
	// Example:
	//   func (m *DatabaseModule) Stop(ctx context.Context) error {
	//       return m.db.Close()
	//   }
	Stop(ctx context.Context) error
}

type StructStateDiffer struct {
	// contains filtered or unexported fields
}

type Subject interface {
	// RegisterObserver adds an observer to receive notifications.
	// Observers can optionally filter events by type using the eventTypes parameter.
	// If eventTypes is empty, the observer receives all events.
	RegisterObserver(observer Observer, eventTypes ...string) error

	// UnregisterObserver removes an observer from receiving notifications.
	// This method should be idempotent and not error if the observer
	// wasn't registered.
	UnregisterObserver(observer Observer) error

	// NotifyObservers sends an event to all registered observers.
	// The notification process should be non-blocking for the caller
	// and handle observer errors gracefully.
	NotifyObservers(ctx context.Context, event cloudevents.Event) error

	// GetObservers returns information about currently registered observers.
	// This is useful for debugging and monitoring.
	GetObservers() []ObserverInfo
}

type Tenant struct {
	ID   TenantID `json:"id"`
	Name string   `json:"name"`
}

type TenantApplication interface {
	Application

	// GetTenantService returns the application's tenant service if available.
	// The tenant service manages tenant registration, lookup, and lifecycle.
	// Returns an error if no tenant service has been registered.
	//
	// Example:
	//   tenantSvc, err := app.GetTenantService()
	//   if err != nil {
	//       return fmt.Errorf("multi-tenancy not configured: %w", err)
	//   }
	GetTenantService() (TenantService, error)

	// WithTenant creates a tenant context from the application context.
	// Tenant contexts provide scoped access to tenant-specific configurations
	// and services, enabling isolation between different tenants.
	//
	// The returned context can be used for tenant-specific operations
	// and will carry tenant identification through the call chain.
	//
	// Example:
	//   tenantCtx, err := app.WithTenant("customer-456")
	//   if err != nil {
	//       return err
	//   }
	//   // Use tenantCtx for tenant-specific operations
	WithTenant(tenantID TenantID) (*TenantContext, error)

	// GetTenantConfig retrieves configuration for a specific tenant and section.
	// This allows modules to access tenant-specific configuration that may
	// override or extend the default application configuration.
	//
	// The section parameter specifies which configuration section to retrieve
	// (e.g., "database", "cache", etc.), and the framework will return the
	// tenant-specific version if available, falling back to defaults otherwise.
	//
	// Example:
	//   cfg, err := app.GetTenantConfig("tenant-789", "database")
	//   if err != nil {
	//       return err
	//   }
	//   dbConfig := cfg.GetConfig().(*DatabaseConfig)
	GetTenantConfig(tenantID TenantID, section string) (ConfigProvider, error)
}

type TenantAwareConfig struct {
	// contains filtered or unexported fields
}

type TenantAwareDecorator struct {
	*BaseApplicationDecorator
	// contains filtered or unexported fields
}

type TenantAwareModule interface {
	Module

	// OnTenantRegistered is called when a new tenant is registered.
	// This method should be used to initialize any tenant-specific resources,
	// such as database connections, caches, or configuration.
	//
	// The method should be non-blocking and handle errors gracefully.
	// If initialization fails, the module should log the error but not
	// prevent the tenant registration from completing.
	OnTenantRegistered(tenantID TenantID)

	// OnTenantRemoved is called when a tenant is removed.
	// This method should be used to clean up any tenant-specific resources
	// to prevent memory leaks or resource exhaustion.
	//
	// The method should be non-blocking and handle cleanup failures gracefully.
	// Even if cleanup fails, the tenant removal should proceed.
	OnTenantRemoved(tenantID TenantID)
}

type TenantAwareRegistry interface {
	// GetServiceForTenant returns a service instance for a specific tenant
	GetServiceForTenant(name string, tenantID TenantID, target any) error
}

type TenantConfigLoader interface {
	// LoadTenantConfigurations loads configurations for all tenants
	LoadTenantConfigurations(app Application, tenantService TenantService) error
}

type TenantConfigParams struct {
	// ConfigNameRegex is a regex pattern for the config file names (e.g. "^tenant[0-9]+\\.json$").
	ConfigNameRegex *regexp.Regexp
	// ConfigDir is the directory where tenant config files are located.
	ConfigDir string
	// ConfigFeeders are the feeders to use for loading tenant configs.
	ConfigFeeders []Feeder
}

type TenantConfigProvider struct {
	// contains filtered or unexported fields
}

type TenantContext struct {
	context.Context
	// contains filtered or unexported fields
}

type TenantID string

type TenantLoader interface {
	// LoadTenants loads and returns all available tenants
	LoadTenants() ([]Tenant, error)
}

type TenantService interface {
	// GetTenantConfig returns tenant-specific configuration for the given tenant and section.
	// This method looks up configuration that has been specifically registered for
	// the tenant, falling back to default configuration if tenant-specific config
	// is not available.
	//
	// The section parameter identifies which configuration section to retrieve
	// (e.g., "database", "cache", "api").
	//
	// Example:
	//   cfg, err := tenantSvc.GetTenantConfig("tenant-123", "database")
	//   if err != nil {
	//       return err
	//   }
	//   dbConfig := cfg.GetConfig().(*DatabaseConfig)
	GetTenantConfig(tenantID TenantID, section string) (ConfigProvider, error)

	// GetTenants returns all registered tenant IDs.
	// This is useful for operations that need to iterate over all tenants,
	// such as maintenance tasks, reporting, or health checks.
	//
	// Example:
	//   for _, tenantID := range tenantSvc.GetTenants() {
	//       // Perform operation for each tenant
	//       err := performMaintenanceForTenant(tenantID)
	//   }
	GetTenants() []TenantID

	// RegisterTenant registers a new tenant with optional initial configurations.
	// The configs map provides tenant-specific configuration for different sections.
	// If a section is not provided in the configs map, the tenant will use the
	// default application configuration for that section.
	//
	// Example:
	//   tenantConfigs := map[string]ConfigProvider{
	//       "database": modular.NewStdConfigProvider(&DatabaseConfig{
	//           Host: "tenant-specific-db.example.com",
	//       }),
	//       "cache": modular.NewStdConfigProvider(&CacheConfig{
	//           Prefix: "tenant-123:",
	//       }),
	//   }
	//   err := tenantSvc.RegisterTenant("tenant-123", tenantConfigs)
	RegisterTenant(tenantID TenantID, configs map[string]ConfigProvider) error

	// RegisterTenantAwareModule registers a module that wants to be notified about tenant lifecycle events.
	// Modules implementing the TenantAwareModule interface can register to receive
	// notifications when tenants are added or removed, allowing them to perform
	// tenant-specific initialization or cleanup.
	//
	// This is typically called automatically by the application framework during
	// module initialization, but can also be called directly if needed.
	//
	// Example:
	//   module := &MyTenantAwareModule{}
	//   err := tenantSvc.RegisterTenantAwareModule(module)
	RegisterTenantAwareModule(module TenantAwareModule) error
}

type ValueInjectionLoggerDecorator struct {
	*BaseLoggerDecorator
	// contains filtered or unexported fields
}

type VerboseAwareFeeder interface {
	// SetVerboseDebug enables or disables verbose debug logging
	SetVerboseDebug(enabled bool, logger interface{ Debug(msg string, args ...any) })
}

type VerboseLogger interface {
	Debug(msg string, args ...any)
}