cell

type AfterStarter interface {
	AfterStart(ctx context.Context) error
}

type AfterStopper interface {
	AfterStop(ctx context.Context) error
}

type Assembly interface {
	// Register adds a Cell to the assembly. Subsequent Register calls before
	// Start are accumulated; calls after Start return an error.
	Register(cell Cell) error
	// Start initializes and starts every registered cell in dependency order.
	// On any cell's failure, previously-started cells are Stopped in reverse.
	Start(ctx context.Context) error
	// Stop drives graceful shutdown of every started cell in reverse order.
	Stop(ctx context.Context) error
	// Health returns each cell's current health snapshot, keyed by cell ID.
	Health() map[string]HealthStatus
}

type AuthRouteDeclarer interface {
	DeclareAuthMeta(meta AuthRouteMeta) error
}

type AuthRouteMeta struct {
	Method              string
	Path                string
	Public              bool
	PasswordResetExempt bool
	// Bootstrap marks the route as protected by HTTP Basic Auth (env credentials).
	// The listener-level JWT middleware skips Bootstrap routes, just like Public
	// routes — the per-route bootstrap middleware authenticates instead. Bootstrap,
	// Public, and PasswordResetExempt are mutually exclusive.
	Bootstrap bool
	// IdempotencyExempt marks the route as opt-out from the HTTP idempotency
	// middleware. When true, the middleware never claims or records this route's
	// responses. The route still executes normally; clients sending Idempotency-Key
	// get no replay guarantee.
	IdempotencyExempt bool
}

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

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

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

type BeforeStarter interface {
	BeforeStart(ctx context.Context) error
}

type BeforeStopper interface {
	BeforeStop(ctx context.Context) error
}

type Cell interface {
	CellIdentity
	CellLifecycle
	CellStatus
	CellInventory
}

type CellIdentity interface {
	// ID returns the cell's stable identifier (matches cell.yaml id).
	ID() string
	// Type classifies the cell's architectural role (core / edge / support).
	Type() cellvocab.CellType
	// ConsistencyLevel reports the cell's declared consistency tier (cellvocab.L0–cellvocab.L4).
	ConsistencyLevel() cellvocab.Level
	// Lifecycle reports the cell's declared governance maturity lifecycle
	// (experimental → candidate → asset → maintenance → retired); empty in
	// cell.yaml defaults to experimental. The YAML / wire key is `lifecycle`.
	// Consumers: runtime/lifecycle.LifecycleAggregator (startup maturity log),
	// runtime/devtools/catalog (catalog wire).
	Lifecycle() cellvocab.CellLifecycle
}

type CellInventory interface {
	// Metadata returns an independent deep copy of the cell's declarative
	// metadata; callers may freely read and modify the returned value.
	Metadata() *metadata.CellMeta
	// OwnedSlices returns the slices this cell registered.
	OwnedSlices() []Slice
	// ProducedContracts returns contracts whose authoritative source is this cell.
	ProducedContracts() []Contract
	// ConsumedContracts returns contracts this cell calls or subscribes to.
	ConsumedContracts() []Contract
}

type CellLifecycle interface {
	// Init registers cell capabilities via the provided Registrar; called once
	// before Start. Init failure aborts assembly start without invoking Stop.
	// Init may validate config, build in-memory state, and register slices.
	Init(ctx context.Context, reg Registrar) error
	// Start brings the cell to a running state. Returns nil only when the cell
	// is fully ready to serve traffic. Canceling ctx must abort startup.
	// Resources acquired here must be released by the matching Stop call.
	Start(ctx context.Context) error
	// Stop performs graceful shutdown. The assembly invokes Stop with the
	// caller-supplied ctx; no per-cell stop timeout is enforced by the kernel,
	// so implementations are solely responsible for honoring ctx deadlines
	// and returning promptly when ctx is canceled.
	Stop(ctx context.Context) error
}

type CellStatus interface {
	// Health returns the current health snapshot for diagnostic surfaces.
	Health() HealthStatus
	// Ready reports whether the cell is currently serving (post-Start, pre-Stop).
	Ready() bool
}

type ConfigChangeEvent struct {
	Added      []string
	Updated    []string
	Removed    []string
	Config     map[string]any
	Generation int64
}

type ConfigReloadRequest struct {
	Prefixes []string
	Fn       func(context.Context, ConfigChangeEvent) error
}

type Contract interface {
	// ID returns the contract's stable identifier (matches contract.yaml id).
	ID() string
	// Kind classifies the communication pattern (http / event / command / projection).
	Kind() cellvocab.ContractKind
	// OwnerCell returns the cell ID that owns the contract's authoritative side.
	OwnerCell() string
	// ConsistencyLevel reports the contract's consistency tier (cellvocab.L0–cellvocab.L4).
	ConsistencyLevel() cellvocab.Level
	// Lifecycle returns the contract's wire-stability governance state (draft / active / deprecated).
	Lifecycle() cellvocab.ContractLifecycle
}

type GRPCServiceRegistrar interface {
	// Register invokes the spec.Register callback on a cellScopedRegistrar
	// interceptor, recording method→cellID attribution for each service.
	// The canonical implementation (runtime/grpc.ServiceRegistrar) always returns
	// nil; contract violations (bad callback type, duplicate ServiceName) panic
	// via panicregister.Approved.
	Register(spec GRPCServiceSpec) error
}

type GRPCServiceSpec struct {
	// ContractID is the stable contract identifier (matches contract.yaml id).
	// Used for deduplication: a cell may not register the same ContractID twice.
	ContractID string

	// CellID is the cell that owns this service. bootstrap asserts spec.CellID
	// equals the snapshot key when draining (mirrors the subscription drain check).
	CellID string

	// Listener identifies the target gRPC listener (must match a ref passed to
	// WithGRPCListener). Symmetric with RouteGroup.Listener for HTTP.
	Listener ListenerRef

	// Register holds a func(grpc.ServiceRegistrar) callback. Kernel stores it as
	// any to avoid a grpc import dependency. The runtime layer type-asserts it.
	// A nil value fails Validate; a non-func value panics in runtime/grpc at
	// registration time (panicregister.Approved("grpc-registrar-bad-register-fn",…)).
	Register any
}

type HTTPContractDeclarer interface {
	DeclareHTTPContract(spec contractspec.ContractSpec) error
}

type HealthStatus struct {
	Status  string // "healthy" | "degraded" | "unhealthy"
	Details map[string]string
}

type HookEvent struct {
	CellID   string
	Hook     HookPhase
	Outcome  HookOutcome
	Duration time.Duration
	Err      error
}

type HookOutcome string

type HookPhase string

type LifecycleHook struct {
	// Name is a diagnostic identifier used in slog fields. Must be non-empty
	// when passed to Registrar.Lifecycle.
	Name string

	// OnStart is called by bootstrap during lifecycle.Start. The ctx parameter
	// is the long-lived owner ctx (controller-runtime Runnable.Start semantics):
	// it remains live for the entire assembly run and is canceled only when the
	// assembly begins shutdown. This supersedes ADR 202605102000 §D1, which
	// described ctx as a startup-deadline ctx.
	//
	// Expected OnStart shape:
	//   1. Spawn the long-running worker goroutine passing the owner ctx.
	//   2. Run a fast synchronous readiness probe (e.g. 50 ms timer).
	//   3. Return nil on success or a non-nil error to abort startup and trigger
	//      LIFO rollback. The failed hook's OnStop is NOT called by rollback.
	//
	// Returning without spawning a goroutine is fine for hooks that do all their
	// work synchronously. Blocking indefinitely in OnStart is not allowed — the
	// hook must return promptly so the startup sequence can continue.
	//
	// StartTimeout is no longer enforced as an OnStart runner deadline; it is
	// retained as a hook self-declared probe window budget (informational only).
	// Supersedes ADR 202605102000 §D1.
	//
	// ref: kubernetes-sigs/controller-runtime pkg/manager/internal.go — Runnable.Start
	//      receives the manager context (long-lived owner ctx); returns when ctx done.
	OnStart func(ctx context.Context) error

	// OnStop is called by bootstrap during lifecycle.Stop, with a context that
	// carries StopTimeout as deadline. OnStop cancels the worker (if not already
	// canceled via owner ctx) and waits for it to exit.
	OnStop       func(ctx context.Context) error
	StartTimeout time.Duration
	StopTimeout  time.Duration
}

type LifecycleHookObserver interface {
	OnHookEvent(HookEvent)
}

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

type NopHookObserver struct{}

type Prefixer interface {
	Prefix() string
}

type ProjectionApply = cellvocab.ProjectionApply

type ProjectionRequest struct {
	// Source selects the input transport (EPIC #1609 PR-05). The zero value ("")
	// and ProjectionSourceOutbox are equivalent: the outbox path, where Spec is
	// the event-kind contract the projection consumes. ProjectionSourceSagaJournal
	// is the global saga journal: Spec MUST be the zero value (no event topic).
	// Set only by the sanctioned constructors — the generated NewProjectionRequest
	// (outbox) and NewSagaJournalProjectionRequest (saga-journal).
	Source cellvocab.ProjectionSource
	// Spec is the event-kind contract the projection consumes (its input stream).
	// Required when Source is outbox (Spec.Kind must be "event"); MUST be the zero
	// value when Source is saga-journal.
	Spec contractspec.ContractSpec
	// ProjectionID names the projection within its cell. It is half of the
	// checkpoint key (cellID, projectionID); the consumer group is derived as
	// cellID + "-" + projectionID, and the rebuild HTTP endpoint (PR-04e) keys
	// the Coordinator by cellID + "/" + projectionID. Must be a snake_case
	// probe-name identifier (NewCoordinator rejects "/" etc. via the probe-name
	// validator), so neither derived key is ambiguous.
	ProjectionID string
	// CellID is the owning cell — observability owner and checkpoint-key half.
	// Injected from cell metadata at code-generation time (same provenance as
	// SubscriptionRequest.CellID); the bootstrap drain cross-checks it against
	// the snapshot owner and fails fast on drift.
	CellID string
	// SliceID is the slice that owns this projection — the observability owner
	// at slice granularity, one level below CellID. Semantically mirrors
	// SubscriptionRequest.SliceID (see that field's godoc). Typically equal to
	// ProjectionID; injected from slice metadata at code-generation time in
	// PR-04b. During this PR-04a record-only seam there is no production fill
	// path, so SliceID may be empty — bootstrap falls back to ProjectionID
	// when SliceID is the empty string.
	SliceID string
	// Apply is the business event→state hook. Required (non-nil).
	Apply ProjectionApply
	// OnReset is the optional rebuild Reset-phase hook. May be nil. Ignored on the
	// saga-journal path (rebuild is not supported there — NewSagaJournalProjectionRequest
	// never sets it, and governance forbids onReset on a saga-journal subscribe CU).
	OnReset ProjectionResetHook
}

type ProjectionResetHook = cellvocab.ProjectionResetHook

type Registrar interface {
	// Config returns the per-cell config snapshot provided by the assembly.
	Config() map[string]any
	// DurabilityMode returns the assembly-level durability mode.
	DurabilityMode() outbox.DurabilityMode

	// RouteGroup declares an HTTP route group. Groups accumulate in
	// declaration order and are mounted by bootstrap during phase5.
	RouteGroup(g RouteGroup)

	// Subscribe registers an event subscription. Returns a non-nil error when:
	//   - handler is nil
	//   - consumerGroup is empty
	//   - cellID is empty
	//   - spec.Kind != "event"
	//
	// cellID is the cell that owns this subscription — distinct from
	// consumerGroup (which may include a role suffix like
	// "accesscore-rbac-session-sync"). It is a positional, mandatory string
	// parameter rather than a SubscriptionOption: codegen (contractgen
	// NewSubscription + cellgen cell.tmpl) injects it from cell metadata at
	// compile time, so a missing cellID is a compile failure at the
	// reg.Subscribe call site (HARD contract). This is the AI-robust gate for
	// "metric/log owner must trace to cell metadata, not to consumerGroup
	// drift" — making cellID an option would silently demote the contract
	// from compile-time to opt-in.
	//
	// Typical usage (consumerGroup == cellID):
	//
	//	reg.Subscribe(spec, handler, c.ID(), c.ID())
	//
	// Role-suffix usage (fanout consumer with sub-group, cellID stays the cell):
	//
	//	reg.Subscribe(spec, handler, "accesscore-rbac-session-sync", c.ID())
	//
	// Cell.Init should propagate the error via `if err := ...; err != nil { return err }`.
	//
	// The handler type outbox.EntryHandler is the canonical event handler in
	// kernel/; cell.Registrar consumes it directly rather than wrapping it in a
	// cell-local alias. This mirrors the industry pattern where a registry/router
	// depends on its event primitive's handler signature:
	//   ref: ThreeDotsLabs/watermill message/router.go AddHandler — handler func type
	//        defined in message/, consumed directly by router.AddHandler.
	//   ref: k8s.io/client-go/tools/cache SharedInformer.AddEventHandler — cache.ResourceEventHandler
	//        defined in cache/, passed directly to informer.AddEventHandler.
	//
	// The subscription is not started here; Bootstrap drains all registered
	// SubscriptionRequests in phase6 and hands them to the event router.
	// This two-phase pattern (register intent in Init, start goroutines in
	// bootstrap) mirrors ThreeDotsLabs/watermill router.AddHandler — handler
	// registration and router.Run are separate lifecycle steps.
	//
	// ref: ThreeDotsLabs/watermill message/router.go AddHandler (handler
	// registration decoupled from goroutine start).
	// ref: ADR docs/architecture/202605111000-adr-subscription-cellid-mandatory.md
	//
	// Hand-written external cells should prefer the fluent [Registrar.Subscription]
	// builder, which makes the cellID red line a compile error rather than relying
	// on getting the positional argument order right.
	Subscribe(
		spec contractspec.ContractSpec,
		handler outbox.EntryHandler,
		consumerGroup string,
		cellID string,
		opts ...SubscriptionOption,
	) error

	// Subscription begins a fluent, compile-checked subscription registration —
	// the hand-written counterpart to the positional Subscribe (which codegen
	// emits as NewSubscription(...).Mount(reg)). It exists so an external Cell
	// that does NOT run the monorepo codegen can register subscriptions without
	// hand-writing the easy-to-transpose positional Subscribe call.
	//
	// The returned draft exposes only CellID; the terminal Register lives on the
	// builder that CellID returns, so the owning cell id is a COMPILE-TIME red
	// line — omitting it leaves no path to Register (the same compile-HARD
	// guarantee codegen gets from the positional cellID parameter, not a runtime
	// fallback). Both step types are unexported (sealed construction), so an
	// external cell can chain but neither name nor forge them:
	//
	//	reg.Subscription(spec).
	//	    CellID(c.ID()).
	//	    ConsumerGroup("payment-charge"). // optional; defaults to CellID
	//	    Handler(c.svc.HandleCharge).
	//	    Register()
	//
	// Register routes through the same RegistryRecorder.Subscribe validation
	// funnel as the positional form (nil handler / empty consumerGroup→defaulted
	// to cellID / empty cellID / non-event spec / empty topic), so the two
	// registration forms are two producers of one validated path, not a
	// backward-compat dual path.
	//
	// ref: ADR docs/architecture/202605111000-adr-subscription-cellid-mandatory.md
	Subscription(spec contractspec.ContractSpec) *subscriptionDraft

	// RegisterWebhookReceiver records an inbound-webhook receiver declaration.
	// Returns a non-nil error when handler is nil or spec.Validate() fails.
	//
	// RECORD-ONLY semantics (PR-2): like Subscribe, this method only appends a
	// WebhookReceiverRequest to the recorder's accumulator — it does NOT mount
	// an HTTP route, resolve a signing secret, or start any goroutine. The
	// receiver runtime drain (bootstrap reading RegistrySnapshot.WebhookReceivers
	// and wiring the HTTP receive endpoint + Claimer) lands in PR-3. This keeps
	// the same two-phase pattern as Subscribe (declare intent in Init, wire in
	// bootstrap) so the generated reg.RegisterWebhookReceiver(...) call compiles
	// today against a stable seam.
	//
	// The call is emitted by cellgen from slice.yaml
	// contractUsages[role=webhook-receive]; the [webhook.ReceiverSpec] literal
	// carries identifiers known at code-generation time (ContractID / SourceID /
	// CellID, the last injected from cell metadata exactly like Subscribe's
	// positional cellID). The handler type is [webhook.WebhookReceiveHandler],
	// defined in kernel/webhook alongside ReceiverSpec and consumed directly here
	// (same pattern as Subscribe consuming outbox.EntryHandler).
	//
	// Cell.Init should propagate the error via `if err := ...; err != nil { return err }`.
	RegisterWebhookReceiver(spec webhook.ReceiverSpec, handler webhook.WebhookReceiveHandler) error

	// RegisterWebhookDispatch records an outbound-webhook dispatcher declaration.
	// Returns a non-nil error when selector is nil or spec.Validate() fails.
	//
	// RECORD-ONLY semantics (PR-2): the dispatch counterpart of
	// RegisterWebhookReceiver. It only appends a WebhookDispatchRequest to the
	// recorder's accumulator — no dispatcher consumer is started and no signing
	// secret is resolved. The dispatcher runtime drain (bootstrap reading
	// RegistrySnapshot.WebhookDispatchers and wiring the outbound dispatcher
	// consumer) lands in PR-5.
	//
	// The call is emitted by cellgen from slice.yaml
	// contractUsages[role=webhook-dispatch]; the [webhook.DispatchSpec] literal
	// carries ContractID / SourceID / CellID. The selector type is
	// [webhook.WebhookDispatchSelector], defined in kernel/webhook alongside
	// DispatchSpec.
	//
	// Cell.Init should propagate the error via `if err := ...; err != nil { return err }`.
	RegisterWebhookDispatch(spec webhook.DispatchSpec, selector webhook.WebhookDispatchSelector) error

	// RegisterProjection records an L3 CQRS-projection declaration. Returns a
	// non-nil error when req fails validation (nil Apply, empty ProjectionID /
	// CellID, or a non-event Spec).
	//
	// RECORD-ONLY semantics: like Subscribe and RegisterWebhookReceiver, this
	// method only appends a ProjectionRequest to the recorder's accumulator. It
	// does NOT construct a projection.Coordinator, open a transaction, or start
	// consuming. The bootstrap projection drain reads
	// RegistrySnapshot.Projections, constructs one projection.Coordinator per
	// request from framework-owned dependencies (checkpoint store / tx runner /
	// cursor / replay source — wired via bootstrap options, never reachable by
	// cell code), and calls Coordinator.Subscribe. This two-phase split (declare
	// intent in Init, wire in bootstrap) is the same pattern as Subscribe and is
	// what keeps the raw framework infrastructure out of the cell package: a cell
	// could not call projection.NewCoordinator even if it wanted to, because it
	// holds no checkpoint store / tx runner.
	//
	// The call is emitted by cellgen from slice.yaml contractUsages (kind:projection
	// derivation, PR-04b #1367 / #834 landed); the first production callsite is
	// examples/todoorder/cells/ordercell/cell_gen.go. RegisterProjection is otherwise
	// only called from test files — PROJECTION-REGISTER-FUNNEL-01 confines every call
	// to cell_gen.go + _test.go. ProjectionRequest carries identifiers known at
	// code-generation time (CellID injected from cell metadata exactly like
	// Subscribe's positional cellID). The Apply / OnReset function types
	// ([ProjectionApply] / [ProjectionResetHook]) are aliases of the cellvocab
	// leaf types (which kernel/projection.Apply / OnReset also alias), so the
	// bootstrap drain passes a recorded hook straight to Coordinator.Subscribe
	// with NO named-type conversion. The carrier and hook types live in the
	// cellvocab leaf because kernel/projection imports kernel/cell (its
	// Coordinator's SubscribeRegistrar references cell.SubscriptionOption), so a
	// reverse import here would be a compile-time cycle (EPIC #1609 PR-01).
	//
	// Cell.Init should propagate the error via `if err := ...; err != nil { return err }`.
	//
	// AI-robust: callers of RegisterProjection are locked to cellgen-derived
	// cell_gen.go + _test.go + kernel/ by archtest PROJECTION-REGISTER-FUNNEL-01
	// (Medium upstream + Medium downstream — Go cannot type-gate callers of a
	// public method; this is the same permanent ceiling as Subscribe /
	// RegisterWebhookReceiver). A "cellgen-only sealed-token" Hard-ification is NOT
	// expressible in Go: cellgen emits this call into the cell's own package
	// (cell_gen.go beside hand-written cell.go), which a same-package hand-written
	// file is indistinguishable from at compile time. won't-do, gh #1372 (same
	// ceiling family as #851 / #893 / #1282).
	//
	// ref: tools/archtest/projection_register_funnel_test.go (PROJECTION-REGISTER-FUNNEL-01)
	// ref: ADR docs/architecture/202605261620-adr-cqrs-projection-lifecycle-harness.md §7 + §Amendment 2026-05-31
	RegisterProjection(req ProjectionRequest) error

	// RegisterReadiness registers a readiness probe under the typed
	// [healthz.ProbeName]. The probe runs against the runtime
	// healthz.Aggregator after bootstrap drains the snapshot. First-wins
	// duplicate semantics: [healthz.ErrDuplicateProbe] is returned on name
	// collision (the second registration is dropped, not the first).
	//
	// name is the single source of truth for the probe identity — the
	// recorder wraps prober.Check() under name even if prober itself
	// originated from a [healthz.Probe] with a different Name(); this makes
	// name/check drift structurally impossible at the entry point.
	//
	// This is the SOLE public probe-registration surface on Registrar; the
	// underlying healthz.Aggregator is no longer exposed (the legacy
	// Registrar.Healthz() method has been retired). Hand-written cell code
	// routes through the sanctioned typed funnels that themselves terminate here:
	//   - cellgen-generated `<cellpkg>.RegisterReadiness(reg, prober)` for
	//     cell-repo probes (declared in healthz_gen.go).
	//   - shared kernel `cell.RegisterEmitterHealthProbes(reg, emitter)`
	//     for outbox emitter probes.
	//
	// archtest PROBENAME-SEALED-FUNNEL-01 locks both directions: A1
	// declares the sanctioned ProbeName const set; A2 closes the callsite
	// via type resolution on the ProbeName parameter.
	//
	// Example (cell-repo probe — standard path):
	//
	//  1. Declare repo in cell.yaml.
	//  2. Run `gocell generate cell -all` to emit healthz_gen.go.
	//  3. Call the generated helper from cell Init:
	//     if err := mycell.RegisterReadiness(reg, c.repo); err != nil { ... }
	RegisterReadiness(name healthz.ProbeName, prober healthz.Prober) error

	// Lifecycle appends a lifecycle hook. Name must be non-empty; passing an
	// empty Name panics (programming error). Hooks run in declaration order
	// on startup and in reverse order on shutdown.
	Lifecycle(h LifecycleHook)

	// OnConfigReload registers a config-reload callback. prefixes==nil means
	// the callback is invoked on every reload. When non-nil, the callback is
	// invoked only when at least one changed key matches a prefix. An empty
	// string inside prefixes is a programming error and panics.
	OnConfigReload(prefixes []string, fn func(context.Context, ConfigChangeEvent) error)

	// GRPCService records a gRPC service declaration (GAP-1 PR-7 [#1150]).
	// The spec is validated and accumulated during Init; bootstrap drains
	// RegistrySnapshot.GRPCServices in phase7b — after binding listeners but
	// before calling grpcServeAll — so services are reachable from the first
	// accepted connection.
	//
	// spec.Register holds a func(grpc.ServiceRegistrar) callback (stored as any
	// because kernel/ must not import grpc). The runtime/grpc layer type-asserts
	// and invokes it. A nil Register fails Validate; a wrong dynamic type panics
	// via panicregister.Approved("grpc-registrar-bad-register-fn", …) in
	// runtime/grpc.ServiceRegistrar.Register.
	//
	// Returns a non-nil error when:
	//   - spec.Validate() fails (empty ContractID / CellID / zero Listener / nil Register)
	//   - the ContractID has already been registered by this cell (dedup by ContractID)
	//
	// Cell.Init should propagate the error via `if err := ...; err != nil { return err }`.
	GRPCService(spec GRPCServiceSpec) error
}

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

type RegistrySnapshot struct {
	RouteGroups     []RouteGroup
	Subscriptions   []SubscriptionRequest
	LifecycleHooks  []LifecycleHook
	ConfigReloaders []ConfigReloadRequest

	// Probes are the cell-level readiness probes declared during Init via
	// reg.RegisterReadiness(...). The bootstrap layer drains them onto the
	// runtime healthz.Aggregator after every cell has initialized — exactly
	// the same write-side-accumulate / read-side-drain split used for
	// RouteGroups, Subscriptions, and LifecycleHooks. The recorder does NOT
	// hold a live aggregator; it is a pure accumulator.
	Probes []healthz.Probe

	// WebhookReceivers are the inbound-webhook receivers declared during Init
	// via reg.RegisterWebhookReceiver(...). PR-2 only accumulates them; the
	// bootstrap receiver runtime drains this slice in PR-3 (no drain exists
	// yet) — same write-side-accumulate / read-side-drain split as Subscriptions.
	WebhookReceivers []WebhookReceiverRequest

	// WebhookDispatchers are the outbound-webhook dispatchers declared during
	// Init via reg.RegisterWebhookDispatch(...). PR-2 only accumulates them; the
	// bootstrap dispatcher runtime drains this slice in PR-5.
	WebhookDispatchers []WebhookDispatchRequest

	// Projections are the L3 CQRS projections declared during Init via
	// reg.RegisterProjection(...). The bootstrap projection drain constructs one
	// projection.Coordinator per request and calls Coordinator.Subscribe — same
	// write-side-accumulate / read-side-drain split as Subscriptions.
	Projections []ProjectionRequest

	// GRPCServices are the gRPC service declarations accumulated via
	// reg.GRPCService(...) during Init (GAP-1 PR-7 [#1150]). bootstrap drains
	// them in phase7b — after binding gRPC listeners but before grpcServeAll —
	// routing each spec to the listener identified by spec.Listener.
	GRPCServices []GRPCServiceSpec
}

type RouteGroup struct {
	Listener   ListenerRef
	Prefix     string
	Middleware []func(http.Handler) http.Handler
	// Register is called by bootstrap to mount the cell's sub-tree on the
	// chosen mux. Required; a nil Register is a programmer error detected
	// at phase5 validation time.
	Register func(mux RouteMux) error
	// CellID is set automatically by bootstrap during phase5CollectRouteGroups.
	CellID string
}

type RouteHandler interface {
	Handle(pattern string, handler http.Handler)
}

type RouteMux interface {
	// Handle registers handler for the given pattern.
	// Pattern follows Go 1.22+ enhanced ServeMux syntax: "METHOD /path/{param}".
	Handle(pattern string, handler http.Handler)

	// Route creates a sub-router under pattern with prefix stripping.
	Route(pattern string, fn func(sub RouteMux))

	// Mount attaches an opaque http.Handler sub-tree under pattern with prefix
	// stripping. The mounted handler does not need to follow GoCell routing
	// conventions.
	Mount(pattern string, handler http.Handler)

	// Group creates a same-level scope sharing the parent prefix.
	Group(fn func(RouteMux))

	// With returns a new RouteMux that inherits all routes and middleware
	// from this scope, plus the additional middleware provided.
	//
	// ref: go-chi/chi Mux.With — returns an inline router sharing the parent tree.
	With(mw ...func(http.Handler) http.Handler) RouteMux
}

type Slice interface {
	// ID returns the slice's stable identifier (matches slice.yaml id).
	ID() string
	// BelongsToCell returns the parent cell's ID.
	BelongsToCell() string
	// ConsistencyLevel reports the slice's consistency tier (from slice.yaml,
	// which is the strict SoR; inheritance from cell.consistencyLevel is not supported).
	ConsistencyLevel() cellvocab.Level
	// Init runs slice-local initialisation (no dependencies; that lives on Cell.Init).
	Init(ctx context.Context) error
	// Verify returns the verification spec parsed from slice.yaml.
	Verify() VerifySpec
	// AllowedFiles returns the file ownership paths. Returns nil when unset;
	// callers should treat nil as a configuration error (FMT-14 requires this field).
	AllowedFiles() []string
	// AffectedJourneys returns the journey IDs this slice participates in.
	AffectedJourneys() []string
}

type SubscriptionOption func(*SubscriptionRequest)

type SubscriptionRequest struct {
	Spec          contractspec.ContractSpec
	Handler       outbox.EntryHandler
	ConsumerGroup string
	SliceID       string

	// CellID is the cell that owns this subscription — observability owner,
	// distinct from ConsumerGroup (broker partition key + idempotency
	// namespace). The cell declares it explicitly during Init via the
	// positional cellID parameter on Registrar.Subscribe; codegen
	// (contractgen + cellgen) injects the value from cell metadata at
	// compile time. Bootstrap's drainCellSubscriptions cross-checks that
	// CellID equals the snapshot key (fail-fast on drift) and does NOT
	// silently populate it: a missing CellID is a compile failure at the
	// reg.Subscribe call site, not a runtime fallback.
	//
	// Example: accesscore registers subscriptions with
	//   ConsumerGroup = "accesscore-rbac-session-sync"
	//   CellID        = "accesscore"   (positional parameter, from cell metadata)
	// so that the resulting outbox.Subscription.CellID is "accesscore" — the
	// cell — without ever proxying ConsumerGroup as cell identity.
	//
	// ref: ThreeDotsLabs/watermill router.AddHandler handlerName / NATS subscription metadata.
	// ref: ADR docs/architecture/202605111000-adr-subscription-cellid-mandatory.md
	CellID string

	// BrokerDelaySchedule opts the subscription into broker-native delayed
	// re-delivery (#1458). It flows through to outbox.Subscription.BrokerDelaySchedule;
	// see that field for semantics. Empty for ordinary event subscriptions;
	// the webhook-dispatch drain sets it to DefaultSvixSchedule().Delays().
	BrokerDelaySchedule []time.Duration
}

type SubscriptionValidator func(outbox.Subscription) error

type SubscriptionValidatorAdder interface {
	AddSubscriptionValidator(SubscriptionValidator)
}

type VerifySpec struct {
	Unit     []string
	Contract []string
	Waivers  []Waiver
}

type Waiver struct {
	Contract  string
	Owner     string
	Reason    string
	ExpiresAt string
}

type WebhookDispatchRequest struct {
	Spec     webhook.DispatchSpec
	Selector webhook.WebhookDispatchSelector
}

type WebhookReceiverRequest struct {
	Spec    webhook.ReceiverSpec
	Handler webhook.WebhookReceiveHandler
}