app

type App struct {
	Config     *Config
	Logger     *slog.Logger
	Router     *router.Router
	DB         *db.DB
	DBs        map[string]*db.DB
	Mailer     mail.Sender
	Session    *auth.SessionManager
	JWT        *auth.JWTManager
	Models     *model.Registry
	Authorizer *authz.Enforcer
	Storage    storage.Store
	// AuthChain is the ordered authentication chain built from
	// auth_backends. Nil when the list is empty — an application with
	// nothing to authenticate against says so by leaving it unset rather
	// than carrying an empty chain that always rejects.
	AuthChain *auth.Chain

	// AuthFederated is the configured browser-redirect identity providers,
	// or nil when none are declared. It is separate from AuthChain because
	// a federated flow has no credentials to hand to a chain: the user
	// leaves, comes back, and only then is there an identity.
	AuthFederated *auth.FederatedSet
	Outbox        *outbox.ManagedOutbox
	Templates     *template.Template

	// I18n resolves message keys against the compiled catalogs found under
	// `locales_path` (the JSON bundles `nucleus compilemessages` writes),
	// with `default_locale` as the fallback. Non-nil only when at least one
	// compiled catalog was found at startup; in that case the Accept-Language
	// negotiation middleware is mounted on the Router and handlers can
	// translate via c.T(...) / i18n.T(ctx, ...). See pkg/i18n.
	I18n *i18n.Translator

	// Observability is the in-process event bus for HTTP, SQL, session and
	// custom events. It is always non-nil after app.New returns.
	// Subscribers (such as the orbit admin module) attach to it directly.
	// See pkg/observability for the full ownership model.
	Observability *observability.Bus

	// SessionRecorder produces session-change events on the Observability
	// bus. It is used by the session manager middleware below.
	SessionRecorder *hooks.SessionRecorder
	// contains filtered or unexported fields
}

type AzureStorageSpec struct {
	AccountName     storage.CredentialSource `koanf:"account_name"`
	AccountKey      storage.CredentialSource `koanf:"account_key"`
	Container       string                   `koanf:"container"`
	PublicContainer string                   `koanf:"public_container"`
}

type BridgeConfig struct {
	Name   string                 `koanf:"name"`
	Type   string                 `koanf:"type"` // kafka, webhook, rabbitmq
	Config map[string]interface{} `koanf:"config"`
}

type CircuitBreakerSpec struct {
	// Enabled turns on circuit-breaker wrapping for the package.
	Enabled bool `koanf:"enabled"`

	// FailureThreshold is the number of consecutive failures required
	// to trip the breaker open.
	FailureThreshold int `koanf:"failure_threshold"`

	// Cooldown is the duration the breaker stays open before admitting
	// half-open probes.
	Cooldown time.Duration `koanf:"cooldown"`

	// HalfOpenMaxConcurrent caps in-flight probes in the half-open
	// state.
	HalfOpenMaxConcurrent int `koanf:"half_open_max_concurrent"`
}

type CleanupStorageSpec struct {
	Enabled  bool   `koanf:"enabled"`
	Interval string `koanf:"interval"`
	Prefix   string `koanf:"prefix"`
	MaxAge   string `koanf:"max_age"`
}

type Config struct {
	// Server
	Host         string        `koanf:"host"`
	Port         int           `koanf:"port"`
	ReadTimeout  time.Duration `koanf:"read_timeout"`
	WriteTimeout time.Duration `koanf:"write_timeout"`
	IdleTimeout  time.Duration `koanf:"idle_timeout"`
	// RequestTimeout bounds a handler: past it the client gets a 503 and the
	// handler's context is cancelled. Zero means the default (30s); a
	// negative value disables the timeout for every route. Until 1.24 the
	// request timeout silently reused read_timeout and could not be turned
	// off (NU-6). Streaming routes are better served by TimeoutExemptPaths.
	RequestTimeout time.Duration `koanf:"request_timeout"`
	// TimeoutExemptPaths are URL path prefixes served without the request
	// timeout and with the raw response writer (Flush and Hijack work):
	// server-sent events, long polls, large downloads. Requests whose
	// Accept header asks for text/event-stream are exempt without listing.
	TimeoutExemptPaths []string `koanf:"timeout_exempt_paths"`

	// TLS configuration (optional — empty disables HTTPS)
	TLSCertFile string `koanf:"tls_cert_file"`
	TLSKeyFile  string `koanf:"tls_key_file"`

	// Database
	DatabaseDefault string                    `koanf:"database_default"`
	Databases       map[string]DatabaseConfig `koanf:"databases"`

	// Multi-site and multi-tenant routing.
	MultiSite   MultiSiteConfig   `koanf:"multisite"`
	MultiTenant MultiTenantConfig `koanf:"multitenant"`

	// Redis (optional — empty disables Redis-backed features)
	RedisURL string `koanf:"redis_url"`

	// Auth
	// AuthBackends is the ORDERED list of authentication backends the
	// login path consults, by registered name (auth.RegisterBackend).
	//
	// Order is the feature, not a detail: `[ldap, local]` means the
	// directory answers first and the application's own user table is what
	// still works the morning the directory does not. A backend that
	// cannot reach its source is skipped rather than treated as a
	// rejection, which is what makes that break-glass account usable.
	//
	// Empty means the chain is not built. An application with no user
	// provider and no directory has nothing to authenticate against, and
	// saying so with an empty list is clearer than inventing a default.
	AuthBackends []string `koanf:"auth_backends"`

	// AuthFederated declares the browser-redirect identity providers —
	// OIDC, SAML — an operator wants sign-in buttons for.
	//
	// Each entry names an INSTANCE and the registered provider type that
	// implements it, and reads its settings from `auth.<name>.*`, the same
	// subtree a credential backend uses:
	//
	//	public_base_url: https://app.example.com
	//	auth_federated:
	//	  - name: corp
	//	    provider: oidc
	//	    display_name: Corp SSO
	//	  - name: partners
	//	    provider: oidc
	//	auth:
	//	  corp:
	//	    issuer: https://login.corp.example/
	//	  partners:
	//	    issuer: https://idp.partners.example/
	//
	// Instance and type are separate names because two identity providers
	// of the same protocol is the ordinary case, and a registry keyed by
	// type alone would have made the second one impossible to express.
	//
	// This list is independent of AuthBackends: a federated flow has no
	// credentials to hand to a chain, so it is not a link in one. An
	// application usually wants both — a directory or local table for
	// break-glass, and an identity provider for everyone else.
	AuthFederated []auth.FederatedInstance `koanf:"auth_federated"`

	// PublicBaseURL is the address the BROWSER reaches this application
	// at, without a trailing slash. Federated sign-in needs it because the
	// callback URL an operator registers with their identity provider has
	// to be the one this application will be listening on, and the address
	// the process binds is frequently not it (a reverse proxy, a
	// container port). Required only when AuthFederated is non-empty.
	PublicBaseURL string `koanf:"public_base_url"`

	// HTTPInterceptors is the ORDERED list of registered request
	// interceptors to wrap the router in, outermost first.
	//
	// Order is the behaviour rather than a detail — authentication before
	// rate limiting and rate limiting before authentication are different
	// systems — so an interceptor is not merely enabled here, it is
	// placed, the same way auth_backends places a backend.
	//
	// Settings live under `interceptors.<name>.*`, mirroring how
	// auth_backends pairs with auth.<name>.*: the list orders, the
	// subtree configures.
	//
	//	http_interceptors: [audit, tenant-guard]
	//	interceptors:
	//	  audit:
	//	    sink: stdout
	//
	// A name nobody registered fails at BOOT, naming what is registered: a
	// typo in a list of request interceptors must not resolve to one fewer
	// protection, quietly.
	HTTPInterceptors []string `koanf:"http_interceptors"`

	// InterceptorConfig maps a registered interceptor name to its
	// `interceptors.<name>.*` subtree. Populated by the loader; not a
	// key an operator writes.
	InterceptorConfig map[string]map[string]any `koanf:"-"`

	JWTSecret string        `koanf:"jwt_secret"`
	JWTExpiry time.Duration `koanf:"jwt_expiry"`
	JWTIssuer string        `koanf:"jwt_issuer"`
	// JWTAudience, when set, is stamped into every token Generate mints and
	// required of every token Validate accepts; empty leaves aud unchecked.
	JWTAudience     string        `koanf:"jwt_audience"`
	JWTKeys         []JWTKeySpec  `koanf:"jwt_keys"`
	JWTCurrentKID   string        `koanf:"jwt_current_kid"`
	SessionLifetime time.Duration `koanf:"session_lifetime"`
	SessionStore    string        `koanf:"session_store"`
	SessionRedisURL string        `koanf:"session_redis_url"`
	SessionTable    string        `koanf:"session_table"`

	// Session cookies
	//
	// SessionCookieName supports the "__Host-" / "__Secure-" cookie
	// prefixes (recommended over HTTPS): App.New validates the prefix
	// preconditions at startup — __Host- requires session_cookie_secure,
	// path "/" and no domain; __Secure- requires session_cookie_secure —
	// and fails loud instead of issuing a cookie every browser would
	// silently drop.
	SessionCookieName   string `koanf:"session_cookie_name"`
	SessionCookieDomain string `koanf:"session_cookie_domain"`
	SessionCookiePath   string `koanf:"session_cookie_path"`
	// SessionCookieSecure sets the session cookie's Secure attribute.
	// Default true (secure-by-default, SPEC §2.4): the session cookie
	// refuses to ride over plain HTTP. Local development over http:// must
	// opt out with `session_cookie_secure: false`. Mirrors the CSRF cookie
	// posture (ADR-008: Secure by default, explicit opt-out).
	SessionCookieSecure   bool          `koanf:"session_cookie_secure"`
	SessionCookieSameSite string        `koanf:"session_cookie_samesite"`
	SessionIdleTimeout    time.Duration `koanf:"session_idle_timeout"`
	// SessionMemcachedServers is the host:port list for `session_store:
	// memcached`.
	SessionMemcachedServers []string `koanf:"session_memcached_servers"`
	SessionRedisPrefix      string   `koanf:"session_redis_prefix"`

	// RBAC
	//
	// RBACPolicyFile is the path to the Casbin RBAC CSV policy file. The
	// deprecated admin_rbac_policy_file alias was removed in v0.12.0
	// (DEP-2026-004; see MA-2026-004 for the one-line rename).
	RBACPolicyFile string `koanf:"rbac_policy_file"`

	// Mail
	MailDriver string `koanf:"mail_driver"`
	SMTPHost   string `koanf:"smtp_host"`
	SMTPPort   int    `koanf:"smtp_port"`
	SMTPUser   string `koanf:"smtp_user"`
	SMTPPass   string `koanf:"smtp_pass"`
	MailFrom   string `koanf:"mail_from"`

	// MailCircuitBreaker, when Enabled, wraps mail.Sender.Send calls
	// with a pkg/circuit breaker. Healthy (the SMTP HELO probe used by
	// /healthz) bypasses the breaker so a recovering dependency can
	// still be observed while Send is short-circuited.
	MailCircuitBreaker CircuitBreakerSpec `koanf:"mail_circuit_breaker"`

	// Observability
	LogLevel     string `koanf:"log_level"`
	LogFormat    string `koanf:"log_format"`
	OTLPEndpoint string `koanf:"otlp_endpoint"`
	MetricsPath  string `koanf:"metrics_path"`

	// SQLDriverInstrumentation wraps the database/sql driver so that direct
	// db.QueryContext/ExecContext statements — the ones that bypass
	// model.CRUD (outbox dispatch, SQL session stores, migrations, schema
	// drift, and any raw SQL an app runs) — also reach the observability
	// bus's live SQL feed. Statements issued through model.CRUD are already
	// on the feed and are not double-recorded. Default false: without it the
	// feed shows only CRUD traffic (the historical behaviour) and the driver
	// is not wrapped, so there is zero hot-path cost. Enabling it adds a
	// small per-direct-statement cost; the expensive work (sanitize + emit)
	// still runs only when a subscriber is attached.
	SQLDriverInstrumentation bool `koanf:"sql_driver_instrumentation"`

	// MetricsPath is seeded into the bootstrap allow-list (ADR-004) and so
	// answers without authorization. Default true — the historical
	// behaviour, matching the common "scraper on a private network" setup.
	// Set false to put /metrics behind the default-deny RBAC enforcer:
	// grant your scraper access with a policy on the metrics path (e.g.
	// `p, metrics-scraper, /metrics, *` plus JWT auth), or keep the
	// endpoint private at the network layer instead. Note that metric
	// VALUES are operational data; if your metrics carry anything
	// sensitive, flip this off or firewall the path.
	MetricsPublic bool `koanf:"metrics_public"`

	// LogRedactExtraKeys are additional log attribute keys whose values
	// the structured logger redacts, on top of the built-in denylist
	// (observe.DefaultRedactedKeys). Use it for app-specific sensitive
	// fields. There is intentionally no config key to *disable*
	// redaction — that requires an explicit code-level opt-out via
	// observe.NewLoggerWithRedaction. See ADR-007.
	LogRedactExtraKeys []string `koanf:"log_redact_extra_keys"`

	// Security — CSRF
	//
	// CSRFEnabled mounts the router's CSRF middleware (router.WithCSRF) on
	// the default stack: origin verification via Sec-Fetch-Site with the
	// double-submit token as fallback. Default false — CSRF protection is
	// opt-in because it only makes sense for cookie/session-authenticated
	// HTML apps; a pure Bearer-token API does not need it. The mvc scaffold
	// enables it; enable it in any app that authenticates browsers with the
	// session cookie.
	CSRFEnabled bool `koanf:"csrf_enabled"`
	// CSRFExemptPaths are URL path prefixes excluded from CSRF validation
	// (e.g. "/api/" for Bearer-only subtrees, or webhook receivers that
	// authenticate by signature).
	CSRFExemptPaths []string `koanf:"csrf_exempt_paths"`

	// CSRFInsecureCookie disables the Secure attribute on the CSRF cookies —
	// a development-only opt-out mirroring session_cookie_secure: false. The
	// default (Secure) makes the double-submit flow unreachable for plain
	// HTTP non-browser clients (Go's cookiejar over http://127.0.0.1), while
	// browsers special-case localhost. Never enable it in production.
	CSRFInsecureCookie bool `koanf:"csrf_insecure_cookie"`

	// Security
	RateLimitRequests int           `koanf:"rate_limit_requests"`
	RateLimitWindow   time.Duration `koanf:"rate_limit_window"`
	RateLimitBurst    int           `koanf:"rate_limit_burst"`
	RateLimitByRoute  bool          `koanf:"rate_limit_by_route"`
	RateLimitByRole   bool          `koanf:"rate_limit_by_role"`

	// TrustedProxies is the allow-list of upstream proxy addresses (IPs or
	// CIDR ranges) whose X-Forwarded-For / X-Real-IP headers are honored. An
	// empty list (the default) DENIES all forwarding headers: r.RemoteAddr —
	// the immediate peer — is used as the client IP for logging and rate
	// limiting. This prevents header-spoofed rate-limit evasion and audit-log
	// poisoning. Set it to your load balancer / reverse-proxy addresses (e.g.
	// ["10.0.0.0/8"]) when Nucleus runs behind one.
	TrustedProxies []string `koanf:"trusted_proxies"`

	// StorageProviderConfig carries the `storage.<provider>.*` subtree of a
	// REGISTERED third-party provider. It is not part of the schema — the
	// framework cannot know the shape of a backend it has never seen — so
	// it is captured raw at load time and handed to the provider, which
	// binds it into its own typed struct with Config.BindProvider.
	//
	// Without this a registry that let you plug a backend in did not let
	// you configure it, which is one step short of useful.
	StorageProviderConfig map[string]any `koanf:"-" json:"-" yaml:"-"`

	// AuthBackendConfig carries the `auth.<backend>.*` subtree of each
	// REGISTERED authentication backend named in AuthBackends, keyed by
	// backend name. Same reason and same shape as StorageProviderConfig:
	// the framework cannot know what a directory backend needs to reach
	// its directory, so the subtree is captured raw at load time and the
	// backend binds it into its own typed struct with
	// auth.BackendConfig.Bind.
	//
	// It is a map and not one subtree because the chain is ORDERED and can
	// hold several backends at once — `[ldap, local]` configures two.
	AuthBackendConfig map[string]map[string]any `koanf:"-" json:"-" yaml:"-"`

	// CORSOrigins is the allow-list of origins permitted by the CORS
	// middleware. An empty list (the default) DENIES cross-origin requests —
	// no CORS headers are emitted (security-by-default, completed at v1.0.0
	// per ADR-013 R4 / DEP-2026-007). A non-empty list restricts CORS to
	// exactly these origins; the historical allow-all behavior is the
	// explicit opt-in `["*"]` (`Access-Control-Allow-Origin: *` for
	// credential-less requests). Key reference:
	// `docs/reference/CONFIG_KEY_REGISTRY.md`.
	CORSOrigins []string `koanf:"cors_origins"`
	// CORSAllowCredentials controls whether the CORS middleware emits
	// `Access-Control-Allow-Credentials: true`. It is only honored when
	// CORSOrigins is non-empty: per the Fetch standard, credentials cannot be
	// combined with the `*` wildcard, so the allow-all default never sets it.
	CORSAllowCredentials bool `koanf:"cors_allow_credentials"`

	// i18n
	DefaultLocale string `koanf:"default_locale"`
	LocalesPath   string `koanf:"locales_path"`

	// Static files
	StaticPrefix string `koanf:"static_prefix"`
	StaticRoot   string `koanf:"static_root"`

	// Storage (unified config; the legacy flat storage_driver/storage_path
	// keys were removed in v0.12.0 — DEP-2026-005, MA-2026-005)
	Storage StorageConfig `koanf:"storage"`

	// Outbox (transactional outbox pattern)
	// When enabled, the outbox provides reliable message delivery through
	// a SQL-backed table with support for external bridges (Kafka, webhooks, etc.)
	Outbox OutboxConfig `koanf:"outbox"`

	// Jobs — module background jobs (pkg/nucleus ModuleSpec.Jobs).
	//
	// JobsProvider selects the pkg/tasks provider that executes them:
	// "memory" (default; in-process scheduler and workers, jobs are lost on
	// restart) or "asynq" (Redis-backed, durable, requires JobsRedisURL).
	JobsProvider string `koanf:"jobs_provider"`
	// JobsRedisURL is the Redis connection URL for the asynq jobs provider
	// (e.g. "redis://localhost:6379/0"). Required when jobs_provider is
	// "asynq"; ignored by the memory provider.
	JobsRedisURL string `koanf:"jobs_redis_url"`
	// JobsConcurrency is the number of concurrent job workers. 0 uses the
	// provider default.
	JobsConcurrency int `koanf:"jobs_concurrency"`
	// JobsSchedulerLock (default true) runs the asynq scheduler under
	// leader election over a Redis lock (SET NX + TTL), so that with
	// multiple replicas exactly ONE process ticks the cron entries — each
	// replica used to start its own scheduler and every job fired once per
	// replica (NF-1). Workers run on every replica either way; only the
	// scheduler is elected. Set false to opt out (single-replica
	// deployments that prefer zero extra Redis traffic, or an external
	// scheduler of record) — the boot log then WARNs about the
	// duplication. Ignored by the memory provider (in-process by nature).
	JobsSchedulerLock bool `koanf:"jobs_scheduler_lock"`

	// WebhooksPrefix is the URL prefix under which module webhook routes
	// (pkg/nucleus ModuleSpec.Webhooks) are mounted:
	// <prefix>/<module-name><path>. Default "/webhooks". When CSRF
	// protection is enabled the framework exempts this prefix
	// automatically — webhooks authenticate by signature, not CSRF token.
	WebhooksPrefix string `koanf:"webhooks_prefix"`

	// Templates
	TemplatesDir string `koanf:"templates_dir"`

	// Environment
	Env   string `koanf:"env"`
	Debug bool   `koanf:"debug"`

	// Profile applies a named preset over the loaded configuration (DX-23).
	// Supported: "dev" — swap every backing-service selection for its
	// no-dependency counterpart (SQLite database, in-memory sessions and
	// jobs, local filesystem storage, no-op mailer) so the SAME config file
	// boots with zero external services. Empty means no preset. Unknown
	// values fail config load.
	Profile string `koanf:"profile"`

	// StateDir is the local directory under which the framework persists
	// machine-local artefacts. Default: "./.nucleus-state". Override with the
	// NUCLEUS_STATE_DIR environment variable.
	StateDir string `koanf:"state_dir"`
}

type DatabaseConfig struct {
	URL         string        `koanf:"url"`
	MaxOpen     int           `koanf:"max_open"`
	MaxIdle     int           `koanf:"max_idle"`
	MaxLifetime time.Duration `koanf:"max_lifetime"`
}

type Extension interface {
	// Name returns a human-readable identifier for this extension (e.g. "admin", "storage").
	Name() string

	// Attach initializes the extension and wires it into the App.
	//
	// It receives the fully constructed core App and may:
	//   - READ the framework services it needs (Config, Logger, Router, DB,
	//     DBs, Models, Session, JWT, Authorizer, Mailer, Storage,
	//     Observability);
	//   - mount HTTP routes and register middleware through Router;
	//   - hold on to whatever it needs for its own lifetime.
	//
	// It may NOT reassign the framework's own fields on App. That used to
	// be documented as permitted — "or set fields on App" — and it was a
	// blank cheque: whatever an extension reached for became API in
	// practice while being covered by no contract, so nothing could be
	// promised about it from one version to the next. No extension ever
	// used it (the one in-tree consumer reads five fields and writes
	// none), so the permission cost stability and bought nothing.
	//
	// What an extension may rely on is frozen in
	// contracts/baseline/extension_surface.txt: adding or removing a field
	// there is a deliberate, reviewed act, which is what makes it possible
	// to promise anything to a plugin author at all.
	Attach(a *App) error

	// Shutdown releases resources held by this extension.
	// Called in reverse registration order during App.Shutdown.
	Shutdown(ctx context.Context) error
}

type GCSStorageSpec struct {
	Bucket            string                   `koanf:"bucket"`
	CredentialsSource storage.CredentialSource `koanf:"credentials"`
	PublicBucket      string                   `koanf:"public_bucket"`
}

type HealthzCheck struct {
	Name      string `json:"name"`
	Status    string `json:"status"`
	Message   string `json:"message,omitempty"`
	LatencyMS int64  `json:"latency_ms,omitempty"`
}

type HealthzResponse struct {
	Status    string         `json:"status"`
	CheckedAt string         `json:"checked_at"`
	Checks    []HealthzCheck `json:"checks"`
}

type JWTKeySpec struct {
	KID       string `koanf:"kid"`
	Algorithm string `koanf:"algorithm"`
	SecretEnv string `koanf:"secret_env"`
	PemPath   string `koanf:"pem_path"`
	PemEnv    string `koanf:"pem_env"`
}

type LocalStorageSpec struct {
	Path string `koanf:"path"`
}

type MultiSiteConfig struct {
	Enabled     bool                  `koanf:"enabled"`
	DefaultSite string                `koanf:"default_site"`
	Sites       map[string]SiteConfig `koanf:"sites"`
}

type MultiTenantConfig struct {
	Enabled               bool                    `koanf:"enabled"`
	Resolver              string                  `koanf:"resolver"` // subdomain|header
	Header                string                  `koanf:"header"`
	DefaultTenant         string                  `koanf:"default_tenant"`
	RequireIsolatedDB     bool                    `koanf:"require_isolated_db"`
	DatabaseAliasTemplate string                  `koanf:"database_alias_template"`
	Tenants               map[string]TenantConfig `koanf:"tenants"`

	// RequireTenantStorage makes storage operations FAIL when the context
	// carries no tenant, instead of silently degrading to the shared
	// (unprefixed) key space — the trap a background job without request
	// scope falls into (NF-12). Off by default for compatibility: without
	// it, a multi-tenant application still gets a one-shot WARN the first
	// time an operation degrades.
	RequireTenantStorage bool `koanf:"require_tenant_storage"`
}

type OpError struct {
	Op  string
	Err error
}

type Option func(*appOptions)

type OutboxConfig struct {
	Enabled       bool           `koanf:"enabled"`
	TableName     string         `koanf:"table_name"`
	LeaseDuration time.Duration  `koanf:"lease_duration"`
	MaxRetries    int            `koanf:"max_retries"`
	RetryBackoff  time.Duration  `koanf:"retry_backoff"`
	Bridges       []BridgeConfig `koanf:"bridges"`

	// LeaseOwner identifies THIS instance in the outbox lease rows
	// (QCD-FW-5). Empty (the default) derives a per-instance identifier
	// from the hostname and pid — every process used to share the literal
	// "nucleus-app", which made lease rows untraceable and let co-tenant
	// processes lease messages interchangeably. Set it explicitly for a
	// stable identity (e.g. a k8s pod name).
	LeaseOwner string `koanf:"lease_owner"`

	// MissingRoutePolicy controls what a dispatcher does with a leased
	// message whose topic has no registered bridge (QCD-FW-5):
	// "error" (default) fails the message; "ignore" releases it for the
	// instance that can deliver it — required in a deliberately
	// heterogeneous fleet where not every process registers every bridge.
	MissingRoutePolicy string `koanf:"missing_route_policy"`
}

type RequestScope struct {
	Host          string
	Site          string
	Tenant        string
	DatabaseAlias string
}

type S3StorageSpec struct {
	Endpoint        string                   `koanf:"endpoint"`
	Bucket          string                   `koanf:"bucket"`
	Region          string                   `koanf:"region"`
	AccessKeyID     storage.CredentialSource `koanf:"access_key_id"`
	SecretAccessKey storage.CredentialSource `koanf:"secret_access_key"`
	SessionToken    storage.CredentialSource `koanf:"session_token"`
	UsePathStyle    bool                     `koanf:"use_path_style"`
	PublicBucket    string                   `koanf:"public_bucket"`
	// CreateBucketIfMissing provisions the bucket(s) at startup when they
	// do not exist yet (QCD-FW-2). Opt-in; without it a missing bucket
	// still fails app.New loudly.
	CreateBucketIfMissing bool `koanf:"create_bucket_if_missing"`
}

type SiteConfig struct {
	Hosts                       []string `koanf:"hosts"`
	Database                    string   `koanf:"database"`
	TenantDatabaseAliasTemplate string   `koanf:"tenant_database_alias_template"`
}

type StorageConfig struct {
	// Default visibility for new objects (private|public).
	DefaultVisibility string `koanf:"default"`

	// Provider selects the storage backend (s3|gcs|azure|local).
	Provider string `koanf:"provider"`

	// PublicPaths maps public URL paths to storage key prefixes.
	PublicPaths map[string]string `koanf:"public_paths"`

	// PublicURLBase is the base URL for public objects (CDN or direct provider).
	PublicURLBase string `koanf:"public_url_base"`

	// S3 configuration
	S3 S3StorageSpec `koanf:"s3"`

	// GCS configuration
	GCS GCSStorageSpec `koanf:"gcs"`

	// Azure configuration
	Azure AzureStorageSpec `koanf:"azure"`

	// Local configuration (development only)
	Local LocalStorageSpec `koanf:"local"`

	// Cleanup config
	Cleanup CleanupStorageSpec `koanf:"cleanup"`

	// CircuitBreaker, when Enabled, wraps remote storage operations
	// (Put/Get/Delete/Exists/List/SignedURL/Copy) with a pkg/circuit
	// breaker. The local provider is never wrapped. PublicURL is
	// pass-through (pure string composition).
	CircuitBreaker CircuitBreakerSpec `koanf:"circuit_breaker"`
}

type TenantConfig struct {
	Site     string `koanf:"site"`
	Database string `koanf:"database"`
}