nucleus

type App struct {
	app.Config `yaml:",inline"`

	Modules    map[string]ModuleSpec `yaml:"-"`
	Middleware []Middleware          `yaml:"-"`
	Services   []ServiceRegistration `yaml:"-"`
	Lifecycle  LifecycleHooks        `yaml:"-"`
	Options    []Option              `yaml:"-"`

	// OpenAPI, when non-nil, mounts a JSON OpenAPI document endpoint at
	// Run time via the underlying app container (ADR-010 Phase 4, Slice 2).
	// The fluent builder sets it through AppBuilder.WithOpenAPIHandler;
	// direct-struct callers populate it explicitly. Nil means no OpenAPI
	// endpoint.
	OpenAPI *OpenAPISpec `yaml:"-"`
	// contains filtered or unexported fields
}

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

type ConfigSource struct {
	Kind string `json:"kind"`
	Path string `json:"path,omitempty"`
	// Line is the 1-based source line a file-sourced key was defined on
	// (Phase 3.1). Populated for YAML files only — TOML positions are
	// available only via go-toml's explicitly-unstable API, and JSON has no
	// standard line API, so both report kind+path with Line == 0. Omitted
	// (zero) for the "default", "env", and "runtime" kinds.
	Line int `json:"line,omitempty"`
}

type Context struct {
	*routerpkg.Context
}

type Creator interface{ Create(*Context) error }

type Destroyer interface{ Destroy(*Context) error }

type EffectiveConfig struct {
	Values []EffectiveValue `json:"values"`
}

type EffectiveValue struct {
	Key      string       `json:"key"`
	Value    any          `json:"value"`
	Source   ConfigSource `json:"source"`
	Redacted bool         `json:"redacted,omitempty"`
}

type EventBus interface {
	// SubscribeSQL streams SQL-statement events until the returned cancel runs.
	SubscribeSQL() (<-chan SQLEvent, func())
	// SubscribeHTTP streams HTTP-request events until the returned cancel runs.
	SubscribeHTTP() (<-chan HTTPEvent, func())

	// EmitSQL publishes a SQL-statement event onto the bus so it reaches every
	// SubscribeSQL consumer. It is the emit counterpart to SubscribeSQL: an
	// external producer that runs SQL outside the framework's own CRUD layer
	// (e.g. an ORM bridge) can surface those statements in the same live feed
	// without importing the lower-level pkg/observability package.
	//
	// The adapter converts the first-party SQLEvent value into the bus's
	// pooled, refcounted event and owns the Release discipline internally; the
	// caller keeps ownership of ev and its Args slice (they are copied, not
	// aliased). The caller sets EmittedAt (typically the query's completion
	// time) and, when correlation is wanted, RequestID/TraceID/UserID. Args
	// SHOULD already be sanitized by the producer — the bus does not redact on
	// emit; see SQLEvent.Args.
	EmitSQL(ev SQLEvent)
}

type Extension = app.Extension

type HTTPEvent struct {
	EmittedAt time.Time
	NodeID    string
	Method    string
	Path      string
	Status    int
	Duration  time.Duration
	RequestID string
	TraceID   string
	UserID    string
	RemoteIP  string
	UserAgent string
	// PayloadPreview is an emit-time-sanitized preview: GET/DELETE show redacted
	// query params (keys containing KEY/SECRET/PASSWORD/TOKEN are masked — note
	// OAuth code/state are not), other methods show "body:redacted (...)". The
	// raw request body is never captured.
	PayloadPreview string
}

type Handler func(*Context) error

type Indexer interface{ Index(*Context) error }

type JobRegistry interface {
	Register(name string, spec JobSpec) error
}

type JobSpec struct {
	// Handler runs on every scheduled tick. Required. It receives a
	// context that is cancelled on application shutdown (and bounded by
	// Timeout when one is set); a non-nil error is logged, never fatal.
	Handler func(ctx context.Context) error

	// Every schedules the job at a fixed interval (e.g. 30*time.Second).
	// Mutually exclusive with Cron.
	Every time.Duration

	// Cron schedules the job with a standard 5-field cron expression
	// ("*/5 * * * *") or a descriptor ("@hourly", "@daily", "@every 90s").
	// The framework validates the expression at registration time —
	// boot fails on an invalid spec — and translates it for the
	// configured provider, so the same spec means the same schedule on
	// both the memory and the asynq provider. Mutually exclusive with
	// Every.
	Cron string

	// Timeout bounds each run with a context deadline. Zero means no
	// per-run deadline; the run still stops when the application shuts
	// down.
	Timeout time.Duration

	// Singleton skips a tick while the previous run of this job is
	// still executing in this process, instead of overlapping runs.
	// Each skip is logged at WARN.
	Singleton bool
}

type LifecycleHooks struct {
	OnStart    func(context.Context) error
	OnShutdown func(context.Context) error
}

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

type Middleware = func(http.Handler) http.Handler

type Module[C any] struct {
	Name       string
	Prefix     string
	DefaultDB  string
	Requires   []string
	Models     []any
	Middleware []Middleware
	// Config is the module's typed configuration. At Run time (ADR-010 §2
	// layer 5) the framework binds the `modules.<Name>.*` config subtree into
	// it, fills still-zero fields from `default:` struct tags, and validates it
	// against `validate:` tags. Precedence is: a value set here (the
	// programmatic baseline) < the config file < `default:` tags fill only what
	// remains zero. Because defaulting keys off the zero value, a field
	// deliberately left at its zero value cannot be distinguished from "unset"
	// and will receive its `default:` tag value if it has one.
	Config C
	Routes func(r Router, cfg C)
	// Jobs registers background jobs on the real registry (executed by
	// the provider selected with `jobs_provider`); Webhooks mounts
	// signed inbound webhook routes under `webhooks_prefix`. Both run
	// once at startup, after OnStart. See JobRegistry / WebhookRegistry.
	Jobs       func(j JobRegistry, cfg C)
	Webhooks   func(w WebhookRegistry, cfg C)
	Migrations fs.FS
	// Templates carries the module's .html templates embedded in the
	// binary. At Run time each file registers in the application's
	// template engine under `<module-name>/<slash-path>` — before app.New,
	// the only window (html/template forbids Parse after the first
	// Execute, and sub-routers copy the engine at derivation). A handler
	// renders one with c.Render(status, "<name>/<path>", data). On a
	// name collision the host's templates_dir parses last and wins.
	Templates fs.FS
	// Policies contributes RBAC rows to the application's default-deny
	// enforcer so the module's routes work when mounted, without the host
	// editing rbac_policy.csv by hand. Objects are relative to Prefix; a
	// deny row in the host's policy file always overrides a module allow.
	// Malformed rules fail boot (ErrInvalidModulePolicy). See PolicyRule.
	Policies []PolicyRule
	// CSRFExempt lists path prefixes (relative to Prefix, raw-prefix
	// matched like csrf_exempt_paths) the module needs exempted from CSRF
	// protection — typically its JSON API paths. Declarative, not a
	// closure, because the exemption list is frozen inside the middleware
	// stack at app.New, before any module closure can run (the same
	// constraint that shaped the automatic webhook-prefix exemption).
	CSRFExempt []string
	OnStart    func(ctx context.Context, rt Runtime, cfg C) error
	OnShutdown func(ctx context.Context, rt Runtime, cfg C) error
}

type ModuleSpec interface {
	Name() string
	Prefix() string
	DefaultDB() string
	Requires() []string
	Models() []any
	Middleware() []Middleware
	Routes(r Router)
	Jobs(j JobRegistry)
	Webhooks(w WebhookRegistry)
	Migrations() fs.FS
	// OnStart runs before the module's Routes are registered (ADR-010
	// Phase 4, Gap 2), so a module initialises its managed resources here
	// — typically `rt.DB()` — and its Routes closure can then capture that
	// state directly. The `Runtime` handle replaces the former `*App`
	// config struct so modules reach the framework-managed connection pool
	// instead of opening their own.
	OnStart(ctx context.Context, rt Runtime) error
	OnShutdown(ctx context.Context, rt Runtime) error
	Config() any
}

type OpenAPISpec struct {
	Pattern string
	Handler http.Handler
}

type Option = app.Option

type Patcher interface{ Patch(*Context) error }

type PolicyRule struct {
	Subject string
	Object  string
	Action  string
	Effect  string
}

type ResourceMethod int

type Router interface {
	Get(path string, handlers ...Handler)
	Post(path string, handlers ...Handler)
	Put(path string, handlers ...Handler)
	Patch(path string, handlers ...Handler)
	Delete(path string, handlers ...Handler)
	Group(prefix string, fn func(g Router))
	Resource(path string, controller any, methods MethodSet)

	// With returns a Router that applies the given middleware to every route
	// registered on the returned value, WITHOUT affecting routes registered on
	// the parent — the per-route / per-scope counterpart to a module's global
	// Middleware. Chain it before a single route to guard just that endpoint:
	//
	//	r.With(rt.Authorizer().RequireRole("admin")).Get("/billing", billing)
	//
	// Middleware is `func(http.Handler) http.Handler`, so any standard net/http
	// middleware — the framework's `Enforcer.RequireRole`, `router.CSRFMiddleware`,
	// or a hand-written guard — mounts directly, with no adapter. With composes
	// additively: each nested With / Group layer adds to the chain (outer→inner),
	// on top of any module-level Middleware.
	With(mw ...Middleware) Router

	// Mount attaches a standard http.Handler subtree at pattern (joined to the
	// module's prefix). Everything under pattern is delegated to h — use it to
	// mount a self-contained sub-application whose internal routing the framework
	// should not interpret: an admin panel's own router (e.g. orbit), a
	// static-file server, or any third-party http.Handler. Unlike Get/Post/…,
	// which register a single endpoint, Mount owns the whole subtree below
	// pattern. A request for the bare pattern without a trailing slash (e.g.
	// GET /admin) is 307-redirected to the canonical pattern/ (GET /admin/).
	// Module-level and With/Group middleware still wrap the mounted handler.
	Mount(pattern string, h http.Handler)
}

type Runtime interface {
	// DB returns the managed `*sql.DB` for the module's database alias
	// (the module's `DefaultDB`, or the application default when unset).
	// It returns nil only when no database is configured for that alias —
	// a misconfiguration the module should surface as an OnStart error.
	DB() *sql.DB

	// DBForRequest resolves the managed `*sql.DB` for the request's resolved
	// scope: the tenant's isolated database when multi-tenant resolution is
	// active (`multitenant.*`), the site's database under multi-site, and the
	// application default otherwise. It mirrors
	// `(*app.App).DatabaseForRequest` semantics — including the
	// tenant-isolation-violation error when an unresolvable tenant would
	// otherwise fall through to a shared database under
	// `multitenant.require_isolated_db` — so module handlers in multi-tenant
	// applications should prefer it over DB(), which is bound to one static
	// alias for the whole module lifetime.
	DBForRequest(r *http.Request) (*sql.DB, error)

	// AutoMigrate synchronises the schema for the given models. NOTE: unlike
	// DB(), it does NOT scope to the module's bound DefaultDB alias — each
	// model is migrated against the database alias declared in its own
	// metadata (defaulting to the application default). It is a development
	// convenience; production deployments should prefer explicit SQL
	// migrations (`nucleus migrate up`), consistent with the SPEC's
	// SQL-first stance.
	AutoMigrate(models ...any) error

	// ApplyModuleMigrations applies THIS module's embedded migrations
	// (`Module.Migrations`) against the module's bound database alias,
	// through the real migration pipeline: the module-scoped ledger
	// (storage IDs prefixed `<module>/`, ADR-010 §16) with checksum
	// tracking — unlike AutoMigrate, which bypasses both. Already-applied
	// migrations are skipped, so the call is idempotent across restarts.
	//
	// This is a DELIBERATE call — the framework never invokes it (ADR-013
	// §R1: application boot never mutates the schema on its own; ADR-022
	// wires the field to this explicit call). A module that wants its
	// embedded migrations live from day one calls it in OnStart; an
	// application that wants operator-controlled schema changes leaves it
	// out and ships the SQL through `nucleus migrate up` instead. Like the
	// CLI, it runs to completion once started. It errors when the module
	// declares no Migrations, on an unbacked runtime, and on any
	// migration failure.
	ApplyModuleMigrations() error

	// Logger returns the application's structured logger. It is never nil;
	// callers always receive at least `slog.Default()`.
	Logger() *slog.Logger

	// Session returns the application's session manager — the same
	// instance whose LoadAndSave middleware the framework mounts on every
	// request, so handlers can already read and write session values
	// through the request context. Modules need the manager itself for the
	// operations that go beyond get/put: `RenewToken` after a successful
	// login (session-fixation defence), `Destroy`/`Invalidate` on logout,
	// and flash messaging. The manager is constructed unconditionally by
	// `app.New`; Session returns nil only on an unbacked runtime.
	Session() *auth.SessionManager

	// Authorizer returns the application's RBAC enforcer (ADR-004) — the
	// same instance behind the framework's default-deny middleware and the
	// admin panel. Modules use it to mount `RequireRole` middleware on
	// their routes, manage role groupings (`AddRole`/`RemoveRole`), or
	// audit live policy through the read-only forwarders (`GetPolicy`,
	// `GetGroupingPolicy`, `GetAllRoles`). Returns nil on an unbacked
	// runtime AND when the RBAC subsystem was not attached (an app built
	// with `app.WithoutDefaults()`) — guard accordingly.
	//
	// Mutations (`AddPolicy`/`Deny`/`AddRole`) act on the live in-memory
	// ruleset only: the policy file is read once at startup and runtime
	// changes do not persist across restarts.
	Authorizer() *authz.Enforcer

	// Mailer returns the application's outbound mail sender — the same
	// instance the framework built from the `mail_*` config and wrapped
	// with the health check and circuit breaker. Modules send through it
	// (e.g. from a signal handler or a task) rather than constructing their
	// own sender, which would bypass that lifecycle. Returns nil on an
	// unbacked runtime AND when the mail subsystem was not attached
	// (`app.WithoutDefaults()`) — guard accordingly. When attached, the
	// default driver is a no-op sender, so a non-nil Mailer is safe to call
	// even when no SMTP is configured.
	Mailer() mail.Sender

	// Storage returns the application's object store — the same instance the
	// framework built from the `storage_*` config, with its background
	// cleaner and circuit breaker. Modules Put/Get/SignedURL through it for
	// uploads and generated artifacts (report exports, etc.) instead of
	// opening their own store. Returns nil on an unbacked runtime AND when
	// the storage subsystem was not attached (`app.WithoutDefaults()`).
	Storage() storage.Store

	// JWT returns the application's JWT manager — the same instance the
	// framework built from `jwt_secret` / `jwt_keys[]` (and whose JWKS the
	// framework auto-mounts for asymmetric keys). Modules mint bearer tokens
	// (`Generate`) and validate them (`Validate`, or mount `Middleware` /
	// `OptionalJWTMiddleware`) through it instead of constructing their own
	// manager from a duplicated secret.
	//
	// Returns nil on an unbacked runtime AND when no signing material is
	// configured (`App.JWT` is nil) — a read-only service that only consumes
	// JWTs minted by an external IdP may legitimately leave it unset, so guard
	// accordingly.
	//
	// Treat the returned manager as read-only from request handlers: its
	// `RotateKey` / `RemoveKey` methods mutate the shared keyset for every
	// concurrent caller (and the framework's JWKS endpoint), so key lifecycle
	// is an operator concern, not a per-request module call — the same posture
	// as `Authorizer()`'s in-memory policy mutations.
	JWT() *auth.JWTManager

	// Models returns the application's model registry — the same instance the
	// framework registers every mounted module's `Models()` into. A module that
	// hosts a generic data UI (enumerate models, run CRUD over arbitrary models)
	// reads it; ordinary modules that only use their own typed models do not need
	// it. Returns nil on an unbacked runtime. The registry is process-wide and
	// shared — treat schema mutations (`UpdateFieldMeta`) as an operator concern,
	// not a per-request call.
	Models() *model.Registry

	// Databases returns a snapshot of every configured managed database handle,
	// keyed by alias (the application default included), unwrapped to `*sql.DB`.
	// Unlike `DB()` — bound to the module's single alias — this exposes all
	// handles, for a module that browses across databases (a data console over a
	// multi-database or multi-tenant topology). The returned map is a copy:
	// mutating it does not affect the framework's registry, and the handles
	// remain framework-owned (a module must NOT close them). Returns nil on an
	// unbacked runtime; an alias whose handle cannot be unwrapped is omitted.
	//
	// It is NOT scoped to the module's own alias or the request's tenant — every
	// configured handle is returned, so the caller owns any tenant-isolation
	// policy. Intended for a trusted, first-party admin module (orbit).
	Databases() map[string]*sql.DB

	// DatabaseHandle returns the framework's managed *db.DB wrapper for the
	// default database. It is the engine-aware handle a deep module needs for
	// operations the raw *sql.DB cannot do — `db.NewMigrator`'s dialect-aware DDL,
	// and `Engine()`/`System()` for dialect detection. Most modules want DB() (the
	// *sql.DB) instead. Returns nil on an unbacked runtime or when no default
	// database is configured (e.g. app.WithoutDefaults()). The handle is
	// framework-owned — a module must NOT Close it.
	DatabaseHandle() *db.DB

	// DatabaseHandles returns a snapshot of every managed *db.DB wrapper keyed by
	// alias — the engine-aware counterpart to Databases() (which returns *sql.DB)
	// — for a module that needs per-database dialect/migration capability across a
	// multi-database topology (e.g. orbit's admin). The map is freshly allocated;
	// the handles remain framework-owned (do NOT Close them). Nil on an unbacked
	// runtime.
	DatabaseHandles() map[string]*db.DB

	// Observability returns a first-party view of the framework's in-process
	// event bus, for a module that renders a live activity feed (orbit's live
	// SQL/HTTP view). It emits nucleus-owned event values through EventBus, so
	// the module never touches the lower-level pkg/observability surface and is
	// freed from its pooled-event Release discipline. Returns nil on an unbacked
	// runtime or when no bus is attached.
	Observability() EventBus

	// AuthChain returns the ordered authentication chain built from
	// auth_backends, or nil when none is declared. A module that owns a
	// login route — an admin panel, a custom sign-in page — authenticates
	// through this rather than reaching for the user table itself, so the
	// operator's declared order (directory first, local account second)
	// applies to every entry point in the application, not only the ones
	// the framework happens to own.
	AuthChain() *auth.Chain

	// Outbox returns the application's managed transactional outbox — the
	// same instance the framework built from the `outbox.*` config, whose
	// dispatcher and bridges are already running. A module enqueues events
	// through it (Enqueue, or EnqueueTx inside its own transaction for the
	// transactional guarantee) instead of writing to the outbox table by
	// hand. Returns nil on an unbacked runtime AND when the outbox is
	// disabled (`outbox.enabled: false`) — guard accordingly (NF-13).
	Outbox() *outbox.ManagedOutbox

	// Tasks returns the shared task manager of the module-jobs runtime —
	// the handle a module uses to enqueue ONE-OFF background tasks
	// (EnqueueJSON and friends) beyond the cron jobs it declared in
	// ModuleSpec.Jobs (NF-13). The provider is the configured
	// `jobs_provider` (memory or asynq).
	//
	// Availability: the manager exists once the jobs runtime has started —
	// which happens when at least one module registered a job, OR when
	// `jobs_provider` names a broker-backed provider (asynq) even with no
	// cron jobs — configuring a broker is the opt-in for enqueue-only
	// applications (the in-process memory provider is the framework
	// default, so it cannot double as that signal and is only built when
	// jobs exist). The runtime starts AFTER every module's OnStart,
	// so Tasks() returns nil inside OnStart — resolve it lazily from
	// request handlers or job closures, and treat nil as "no jobs runtime
	// configured". A handler for a one-off task type is registered through
	// the same manager's HandleFunc (both in-tree providers accept
	// registration at any time); register before the first enqueue of that
	// type, or the provider treats the early deliveries as failures per
	// its retry policy.
	Tasks() tasks.Manager
}

type SQLEvent struct {
	EmittedAt time.Time
	NodeID    string
	ModelName string
	Operation string
	Query     string
	// Args are the bound arguments AFTER the observability layer's emit-time
	// sanitization: string and []byte values are replaced with a "type(len):***"
	// marker, but numeric, bool, time.Time and nil args are kept verbatim (so a
	// "WHERE id = ?" key appears as e.g. "42"). Operator-only; see EventBus.
	Args     []string
	Duration time.Duration
	Err      string
	// RowsAffected is the driver-reported row count for exec-style
	// operations (INSERT/UPDATE/DELETE); 0 means "not reported" —
	// SELECT paths and drivers without support. Additive in v1.1.0.
	RowsAffected int64
	RequestID    string
	TraceID      string
	UserID       string
}

type ServiceRegistration struct {
	Name   string
	Run    func(context.Context) error
	Health func(context.Context) error
}

type Shower interface{ Show(*Context) error }

type Updater interface{ Update(*Context) error }

type WebhookRegistry interface {
	Register(path string, spec WebhookSpec) error
}

type WebhookSpec struct {
	// Handler serves the request after the framework's checks (method,
	// body cap, signature) pass. Required. The request body has already
	// been read for signature verification and is replayed, so Handler
	// reads it as usual.
	Handler http.HandlerFunc

	// Secret, when non-empty, requires each request to carry a valid
	// HMAC-SHA256 signature of the raw request body in the
	// X-Nucleus-Signature header, formatted "sha256=<hex>" (see
	// SignWebhookBody). Requests with a missing or invalid signature
	// are rejected with 401 before Handler runs. When empty, no
	// signature is checked and the framework WARNs once at boot —
	// Handler must then authenticate the caller itself.
	//
	// Declared limit — no anti-replay: the signature authenticates
	// content, not freshness or uniqueness. A captured signed request
	// verifies again if re-sent verbatim. Handlers whose effects are not
	// idempotent should deduplicate by an event ID carried in the
	// payload; setting TimestampTolerance additionally narrows the
	// replay window to that tolerance (dedup is still what closes it
	// within the window).
	Secret string

	// Methods restricts the accepted HTTP methods. Default: POST only.
	// Other methods receive 405 with an Allow header.
	Methods []string

	// MaxBytes caps the request body size; larger bodies are rejected
	// with 413. Default: 1 MiB.
	MaxBytes int64

	// TimestampTolerance, when positive, switches the signature check to
	// the timestamped scheme: each request must carry its send time as
	// decimal Unix seconds in the X-Nucleus-Timestamp header, the time
	// must lie within ±TimestampTolerance of the receiver's clock, and
	// the signature must cover `<timestamp>.<body>` — senders use
	// SignWebhookBodyWithTimestamp, which returns both header values.
	// Missing, malformed, out-of-tolerance, or unsigned timestamps are
	// rejected with 401 before Handler runs.
	//
	// Zero (the default) keeps the compatible body-only scheme of
	// SignWebhookBody with no timestamp requirement. Opt-in because it
	// changes what senders must sign; 5m is a reasonable tolerance for
	// senders with NTP-synced clocks. Setting it without a Secret is a
	// registration error (the timestamp is only trustworthy signed), as
	// is a negative value.
	TimestampTolerance time.Duration
}