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

	// DeploymentTopology is the codegen-derived deployment placement spec for
	// this assembly (single-sourced from assembly.yaml topology, derived via
	// SpecForRole(generatedTopologyGroups(), role)). It is a bootstrap.DeploymentTopologySpec
	// (plain codegen input, no methods); phase0 seals it into a
	// bootstrap.DeploymentTopology (with IsColocated/RemoteEndpoint); US4
	// consumers query the SEALED value (via Bootstrap.DeploymentTopology()), not
	// this spec. Empty spec means all cells are co-located in the same process
	// (zero-migration default). Build injects it via bootstrap.WithDeploymentTopology
	// so phase0 can seal+validate the spec into a runtime DeploymentTopology and
	// enforce cell-placement routing. Genuinely cross-cutting: consumed by the
	// composition root (Builder.Build) and bootstrap phase0 across all cell modules.
	DeploymentTopology bootstrap.DeploymentTopologySpec

	// 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

	// Publisher is the outbox event publisher — the sink the relay publishes
	// already-persisted outbox entries to. In demo topology it is the in-process
	// eventbus; in postgres topology a real broker (RabbitMQ). The type is the
	// kernel/outbox interface so this package never imports runtime/eventbus or
	// adapters/* (same layering reason as MetricsProvider). The composition root
	// resolves it via cellmodules/eventtransport.Resolve, which gates the choice
	// on Topology and fail-closes postgres mode onto a real broker (#1940).
	Publisher outbox.Publisher

	// Subscriber is the outbox event subscriber — the source consumers read from.
	// In demo topology it is the SAME in-process eventbus instance as Publisher
	// (so in-process publish is visible to in-process subscribers); in postgres
	// topology the same broker's subscriber. Interface-typed for the same layering
	// reason as Publisher.
	Subscriber outbox.Subscriber

	// 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 per-cell postgres provider resolver (#2341). Each cell
	// module resolves ITS pool's provider via PG.ForCell(cellID): colocated
	// assemblies map every cell to one shared provider (one pool); split assemblies
	// map each cell to its own pool's provider (N pools, each driven by its own
	// relay). Assembly-wide consumers with no "cell" dimension (the CQRS projection
	// harness) use PG.Sole(), which fails closed in split topology. Nil in
	// non-postgres modes; cell modules take their in-memory path.
	PG capability.PGSet

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

	// InternalServiceKeyring supplies per-cell HMAC subkeys for /internal/v1/*
	// service-token signing and verification (#2153). It is an interface so the
	// composition root can inject either a master-derived keyring (monolith) or a
	// master-absent ProvisionedKeyring (split, per-cell). Promoted from
	// cmd/corebundle's private internalGuard struct so cell modules can sign
	// outbound requests without coupling to the cmd-private type.
	InternalServiceKeyring kauth.ServiceKeyring

	// NonceStore is the replay-defense store backing the /internal/v1/*
	// service-token guard. Promoted from cmd/corebundle's private internalGuard
	// struct (alongside InternalServiceKeyring) 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

	// InProcessTransport is the shared, empty-on-construction in-process
	// CellTransport holder (Epic #1423 US4 #1963). Genuinely cross-cutting: the
	// composition root mints ONE holder and hands the SAME pointer to both the
	// consumer cell (which dispatches co-located cross-cell http calls through it)
	// and bootstrap (WithInProcessTransport), which binds the built
	// internal-listener handler into it at phase5. Build always populates it.
	InProcessTransport *transport.InProcessTransport

	// Tracer is the OPTIONAL cross-cell tracing backend (input). It is the SINGLE
	// source for distributed tracing: when non-nil, Build threads it into BOTH the
	// bootstrap tracer (router + in-process transport late-bind + event router, via
	// bootstrap.WithTracer) AND the remote transport (via TransportObs below), so a
	// split-topology remote call gets the SAME tracer as in-process calls — closing
	// the ADR D4 span half (#2251 P1.3). Nil = no tracing configured (remote and
	// in-process both degrade to wrapper.NoopTracer{}); production currently leaves
	// it nil (seam-only) until a composition root wires a real otel tracer. Adding
	// it here (rather than a per-call argument) makes "wired metrics but forgot the
	// tracer" unrepresentable at the celltransport.Resolve boundary.
	Tracer wrapper.Tracer

	// TransportObs is the SHARED cross-cell observability bundle (transport metrics
	// + Tracer) minted ONCE by Build and consumed by both the in-process transport
	// and any remote transport a module resolves via celltransport.Resolve — so
	// split-topology remote calls emit cell_transport_requests_total{transport_mode=
	// remote} and produce spans instead of dropping them (#1966 review P1.3 / #2251,
	// ADR D4). The metrics instance is reused (not re-registered) to avoid a
	// duplicate-counter error. Build-populated (derived), not a caller input.
	TransportObs transport.CrossCellObs

	// RemoteClientTLS is the cell's client-side mTLS identity for dialing remote
	// peer cells over https (#2263). The composition root resolves it once via
	// cellmodules/celltls.Resolve and hands it to celltransport.Resolve, which
	// mints a per-target-cell *tls.Config (peer authenticated by SPIFFE cell ID).
	// The zero value means "no client mTLS" (demo / loopback / all-colocated):
	// celltransport.Resolve then fails closed only for a non-loopback https peer.
	// Caller input (composition root); zero is the valid no-mTLS state.
	RemoteClientTLS tlsutil.ClientIdentity

	// InternalListenerServerTLS is the cell's server-side mTLS config for the
	// internal listener (#2263), resolved alongside RemoteClientTLS by
	// cellmodules/celltls.Resolve. When non-nil the composition root wires it via
	// celltls.InternalListenerSecurity (prepends kauth.AuthMTLS{} +
	// bootstrap.WithListenerTLS). Nil = no server mTLS (service-token-only, demo /
	// loopback). Caller input; nil is the valid no-mTLS state. A *tls.Config (not
	// a celltls type) keeps this package free of a cellmodules import (layer rule).
	InternalListenerServerTLS *tls.Config

	// 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
	// contains filtered or unexported fields
}