composition

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

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

type CellModule interface {
	// ID returns a stable identifier used in error messages and logs.
	ID() string

	// Provide resolves Cell-specific dependencies from the shared context and
	// returns a [ModuleResult] (the constructed Cell + non-resource opts +
	// the single-source ManagedResource list) or an error.
	//
	// Resource lifecycle is single-source: the module lists every external
	// connection it opened (PG pool, vault client, …) in ModuleResult.Resources,
	// and [Builder.Build] derives BOTH the happy-path bootstrap.WithManagedResource
	// registration AND the pre-Run rollback from that one slice. The module MUST
	// NOT call bootstrap.WithManagedResource itself.
	//
	// Cross-module value handoff via the former ModuleExports type has been
	// removed (Wave-1 #1423). Cell modules are now fully self-contained; cross-cell
	// communication happens via events (contract-based), not via in-process
	// Go handle passing at composition time.
	//
	// MODULE-PROVIDE-NO-VALUE-HANDOFF-01 (tools/archtest/module_provide_signature_frozen_test.go)
	// enforces that this signature has exactly two inputs (context.Context, *SharedDeps)
	// and two outputs (ModuleResult, error), and that ModuleResult has exactly the
	// fields {Cell, Opts, Resources} with no cross-module value-handoff channel.
	Provide(ctx context.Context, shared *SharedDeps) (ModuleResult, error)
}

type MigrationRegistration struct {
	// Namespace identifies the migration lineage; its tracking table is
	// schema_migrations_<namespace> (derived adapter-side). The reserved
	// "platform" namespace is the platform's own migrations and is seeded by the
	// ops entry point (adapters/postgres.NewMigrationSetWithPlatform), not here.
	Namespace migration.Namespace
	// FS is the embed.FS (or any fs.FS) of goose-native NNN_desc.sql files for
	// this namespace, with its own independent 001..N sequence.
	FS fs.FS
}

type ModuleResult struct {
	// Cell is the constructed Cell. Must be non-nil on success.
	Cell cell.Cell

	// Opts are non-resource bootstrap options the Cell needs (e.g.
	// bootstrap.WithRelay). Resources MUST NOT be registered here via
	// bootstrap.WithManagedResource — use the Resources field; the Builder
	// derives the WithManagedResource registration from it.
	Opts []bootstrap.Option

	// Resources are the ManagedResources opened during Provide. The Builder
	// derives both steady-state registration and pre-Run rollback from this one
	// slice (single source). Entries MUST be non-nil.
	Resources []kernellifecycle.ManagedResource
}

type RuntimeOptionsFunc func(cells []cell.Cell) ([]bootstrap.Option, error)

type SharedDeps struct {

	// Clock is the single root clock instance threaded through every adapter,
	// service, and middleware. Tests inject clockmock.FakeClock; production
	// wires clock.Real() exactly once at the entry point.
	Clock clock.Clock

	// Topology is the resolved adapter-mode / storage-backend combination. It
	// must be obtained from bootstrap.NewTopology / TopologyFromEnv (it is a
	// sealed type); a zero Topology fails validation.
	Topology bootstrap.Topology

	// JWTIssuer signs access tokens for the accesscore cell.
	// Source: runtime/auth.NewJWTIssuer (via authconfig.NewJWTIssuerFromRegistry).
	JWTIssuer *auth.JWTIssuer

	// JWTVerifier validates inbound access tokens.
	// Source: runtime/auth.NewJWTVerifier (via authconfig.NewJWTVerifierFromRegistry).
	JWTVerifier *auth.JWTVerifier

	// MetricsProvider is the kernel-neutral metrics backend. Production
	// callers assign a *promadapter.MetricProvider (which satisfies
	// kernelmetrics.Provider); tests may use kernelmetrics.NopProvider{}.
	//
	// The field type is intentionally the interface — this package must not
	// import adapters/prometheus or github.com/prometheus/client_golang.
	MetricsProvider kernelmetrics.Provider

	// EventBus is the in-process event bus for publish and subscribe.
	EventBus *eventbus.InMemoryEventBus

	// ConfigEventCollector records config consumer process and settlement
	// metrics. It is genuinely cross-cell — consumed by accesscore, configcore,
	// AND the corebundle config-event consumer middleware — so it stays on the
	// shared bag (registered once against MetricsProvider, injected into all
	// consumers). It is NOT a configcore-specific field.
	ConfigEventCollector obmetrics.ConfigEventCollector

	// ConsumerClaimer coordinates outbox consumer idempotency.
	ConsumerClaimer idempotency.Claimer

	// PG is the assembly's single postgres capability provider. Nil in
	// non-postgres modes; cell modules take their in-memory path.
	PG capability.PGProvider

	// Redis is the assembly's shared redis capability provider. Nil in modes
	// without redis.
	Redis capability.RedisProvider

	// InternalHMACRing is the HMAC key ring for /internal/v1/* service-token
	// signing and verification. Promoted from cmd/corebundle's private
	// internalGuard struct so cell modules can sign outbound requests without
	// coupling to the cmd-private type.
	InternalHMACRing *auth.HMACKeyRing

	// NonceStore is the replay-defense store backing the /internal/v1/*
	// service-token guard. Promoted from cmd/corebundle's private internalGuard
	// struct (alongside InternalHMACRing) so that production control-plane
	// validation can introspect Kind() at the composition boundary: in adapter
	// mode "real" a NoopNonceStore is rejected, and an in-memory store requires
	// the single-pod acknowledgement. Nil is permitted in dev/test adapter
	// modes (the Kind checks are real-mode-only); see validateProductionControlPlane.
	//
	// Note: although validate() only checks NonceStore in real adapter mode, any
	// consumer that wires the internal-listener auth chain via
	// auth.NewAuthServiceToken must supply a non-nil NonceStore — that constructor
	// fail-fasts on nil regardless of adapter mode. In dev/test supply
	// auth.NewInMemoryNonceStore(...).
	NonceStore kauth.NonceStore

	// PrimaryHTTPAddr is the bind address for the public HTTP listener.
	PrimaryHTTPAddr string

	// InternalHTTPAddr is the bind address for the internal HTTP listener.
	InternalHTTPAddr string

	// HealthHTTPAddr is the bind address for the health+metrics listener.
	HealthHTTPAddr string

	// MetricsToken guards /metrics (X-Metrics-Token header).
	MetricsToken string

	// VerboseToken guards /readyz?verbose (X-Readyz-Token header).
	VerboseToken string

	// VerboseDisabled declares that /readyz?verbose must not be served.
	VerboseDisabled bool

	// HealthLocalOnly explicitly waives the loopback-only HealthHTTPAddr guard.
	// Must be false in production; set true only in tests or single-node
	// deployments where the health listener is deliberately bound to a
	// non-loopback address.
	HealthLocalOnly bool

	// ProjectRoot is the directory used by the devtools catalog endpoint.
	// Empty means devtools catalog is disabled; external callers that do not
	// need devtools functionality should leave this field unset.
	ProjectRoot string

	// ConfigKeyProvider is the configcore value-encryption key provider.
	//
	// This is the LAST configcore-specific field on the shared bag. It remains
	// here (rather than being self-built inside cellmodules/configcore like the
	// stale-cipher and eventbus-cache collectors) because the vault-transit
	// provider needs adapters/vault.TransitMetrics, which is built from a raw
	// github.com/prometheus/client_golang registry — and the
	// adapterPromCallerAllowlist governance posture (archtest
	// observability_metrics_test.go, #1085 Batch 4 Part A) keeps raw-prometheus
	// construction in cmd/ so cellmodules/configcore never imports client_golang.
	// configcore self-building the key provider is gated on #885 (migrating vault
	// TransitMetrics to the kernel MetricsProvider); once #885 lands this field
	// moves into configcore too and SharedDeps becomes fully cell-agnostic.
	// Refs #1413 / #885.
	//
	// Built in cmd/corebundle, passed to cellmodules/configcore.Module. Nil means
	// no key provider; in real adapter mode configcore rejects nil (NoopTransformer
	// is dev-only).
	ConfigKeyProvider kcrypto.KeyProvider
	// contains filtered or unexported fields
}