core

type APIKey struct {
	ID        string
	Name      string
	Key       string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type APIKeyInfo struct {
	ID         string
	Name       string
	CreatedAt  time.Time
	LastUsedAt time.Time
	ExpiresAt  time.Time
}

type AccessCapabilities struct {
	Operations OperationCapabilities
	Fields     map[string]FieldCapabilities
}

type AccessContext struct {
	// Context is the request-scoped cancellation and deadline context.
	Context context.Context
	// Operation is the collection operation being evaluated.
	Operation operation.Kind
	// CollectionID is the stable identity of the target collection.
	CollectionID schema.StableID
	// GlobalID is the stable identity of the target global, when applicable.
	GlobalID schema.StableID
	// ID is the requested document ID. It is empty for creates and list reads.
	ID string
	// Actor is the authenticated document, or nil for an anonymous request.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Data is a detached snapshot of incoming create or update values.
	Data store.Values
	// Local exposes nested operations through the same transaction and access
	// pipeline. Rules must avoid recursively invoking themselves without a guard.
	Local *LocalAPI
	// Locale is the exact content locale currently being authorized.
	Locale schema.LocaleCode
	// AllLocales reports that the caller requested every locale. Such a request
	// may evaluate the rule once for each configured Locale and requires
	// compatible decisions across them.
	AllLocales bool
}

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

type AccessDecisionKind string

type AccessRule func(AccessContext) (AccessDecision, error)

type AdminConfig struct {
	// User is the slug of the auth-enabled collection whose sessions may access
	// the admin. It is required when the application has any auth collection.
	User schema.CollectionSlug
	// Localization configures the language and timezone choices for the
	// framework-owned interface. It is independent from content localization.
	Localization AdminLocalizationConfig
}

type AdminLanguage struct {
	Code              string
	Label             string
	LabelTranslations map[string]string
	RTL               bool
}

type AdminLocalizationConfig struct {
	Languages       []AdminLanguage
	DefaultLanguage string
	TimeZones       []AdminTimeZone
	DefaultTimeZone string
}

type AdminPluginMetadata struct {
	// Package is an installed bare JavaScript package specifier.
	Package string
	// Export is the named AdminPlugin export in Package.
	Export string
	// APIVersion must equal AdminPluginAPIVersion.
	APIVersion uint32
	// PairingVersion changes when backend and admin halves cease to match.
	PairingVersion uint32
	// Routes lists authenticated admin route paths in exact registration order.
	Routes []string
	// Assets lists package-relative static assets in exact registration order.
	Assets []string
}

type AdminTimeZone struct {
	ID                string
	Label             string
	LabelTranslations map[string]string
}

type AfterCommitDispatcher interface {
	Dispatch(context.Context, AfterCommitEffect) error
}

type AfterCommitEffect struct {
	// Operation identifies the committed operation.
	Operation operation.Kind
	// CollectionID identifies the affected collection.
	CollectionID schema.StableID
	// GlobalID identifies the affected global, when applicable.
	GlobalID schema.StableID
	// DocumentID identifies the affected document; it is empty for an effect
	// without a single document, such as a list read.
	DocumentID string
	// Run calls the hook outside its original transaction. Pass the effect's
	// execution context to control cancellation and deadlines.
	Run func(context.Context) error
}

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

type AuditEvent struct {
	// Time is when the event occurred.
	Time time.Time
	// RequestID correlates the event with logs and observations.
	RequestID string
	// ClientIP is the resolved direct or trusted-forwarded client address.
	ClientIP string
	// Action names the operation, such as login, create, or delete.
	Action string
	// Collection is the affected collection slug when applicable.
	Collection string
	// DocumentID is the affected document identity when applicable.
	DocumentID string
	// ActorID is the authenticated document identity when available.
	ActorID string
	// ActorCollection disambiguates ActorID across auth collections.
	ActorCollection schema.CollectionSlug
}

type AuthAccess struct {
	Login         AuthAccessRule
	PasswordReset AuthAccessRule
	Verification  AuthAccessRule
	APIKey        AuthAccessRule
	Session       AuthAccessRule
}

type AuthAccessRule func(AuthContext) (bool, error)

type AuthConfig struct {
	// SessionDuration is how long a login remains valid. Zero defaults to 24 hours.
	SessionDuration time.Duration
	// Password controls local password validation and hashing. Zero values use
	// the secure framework defaults documented on PasswordPolicy.
	Password PasswordPolicy
	// MaxLoginAttempts is the number of consecutive credential failures allowed
	// before the account is temporarily locked. Zero defaults to 5; a negative
	// value disables account lockout.
	MaxLoginAttempts int
	// LockDuration is how long an account remains locked after MaxLoginAttempts.
	// Zero defaults to 10 minutes.
	LockDuration time.Duration
	// PasswordReset enables the forgot/reset-password flow when Send is set.
	// The raw single-use token is delivered only to this trusted callback.
	PasswordReset PasswordResetConfig
	// Verify enables email verification. When non-nil, newly provisioned
	// credentials cannot log in until a verification token is consumed.
	Verify *VerifyEmailConfig
	// APIKeys allows users to mint revocable, session-independent bearer
	// credentials. API keys are disabled by default.
	APIKeys bool
	// Access contains authorization rules for auth operations that are not CRUD.
	Access AuthAccess
	// Hooks contains authentication lifecycle callbacks.
	Hooks AuthHooks
	// Strategies adds application-owned request authentication in declaration order.
	Strategies []AuthStrategy
}

type AuthContext struct {
	Context      context.Context
	Operation    AuthOperation
	CollectionID schema.StableID
	User         *store.Document
	Identity     string
	IPAddress    string
	UserAgent    string
	Local        *LocalAPI
}

type AuthHook func(AuthContext) error

type AuthHooks struct {
	BeforeLogin          []AuthHook
	AfterLogin           []AuthHook
	AfterMe              []AuthHook
	BeforeLogout         []AuthHook
	AfterLogout          []AuthHook
	BeforeRefresh        []AuthHook
	AfterRefresh         []AuthHook
	BeforeForgotPassword []AuthHook
	AfterForgotPassword  []AuthHook
	BeforePasswordReset  []AuthHook
	AfterPasswordReset   []AuthHook
	BeforeVerification   []AuthHook
	AfterVerification    []AuthHook
	BeforeAPIKey         []AuthHook
	AfterAPIKey          []AuthHook
}

type AuthIdentity struct {
	Collection schema.CollectionSlug
	Actor      store.Document
	// PreviewEpoch is an opaque lifecycle snapshot captured before transport
	// authentication. Zero lets direct Go callers snapshot at mint entry.
	PreviewEpoch uint64
}

type AuthOperation string

type AuthSession struct {
	// ID is the non-secret identifier used to manage this session.
	ID string
	// Token is the opaque credential accepted by session-aware transports.
	Token string
	// Collection is the auth-enabled collection that owns the identity.
	Collection schema.CollectionSlug
	// User is the current document from Collection.
	User store.Document
	// ExpiresAt is the absolute UTC expiry time.
	ExpiresAt time.Time
}

type AuthSessionInfo struct {
	ID         string
	CreatedAt  time.Time
	LastSeenAt time.Time
	ExpiresAt  time.Time
	IPAddress  string
	UserAgent  string
	Current    bool
}

type AuthStrategy struct {
	// Name is a stable lowercase kebab-case identifier used in diagnostics.
	Name string
	// Authenticate returns Authenticated false when the request does not belong
	// to this strategy. It must not return raw credentials or untrusted user data.
	Authenticate func(AuthStrategyContext) (AuthStrategyResult, error)
}

type AuthStrategyContext struct {
	Context      context.Context
	CollectionID schema.StableID
	Headers      map[string][]string
	Local        *LocalAPI
}

type AuthStrategyResult struct {
	Authenticated bool
	UserID        string
}

type BoundTypedAllLocalesCollection[Document any] struct {
	// contains filtered or unexported fields
}

type BoundTypedAllLocalesGlobal[Document any] struct {
	// contains filtered or unexported fields
}

type BoundTypedCollection[Document, Create, Update any] struct {
	// contains filtered or unexported fields
}

type BoundTypedGlobal[Document, Update any] struct {
	// contains filtered or unexported fields
}

type CapabilityOptions struct {
	Data            store.Values
	Actor           *store.Document
	ActorCollection schema.CollectionSlug
	TrashOnly       bool
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
	AllLocales      bool
}

type Collection struct {
	// Slug is the URL-safe collection name used by APIs, relationships, and the admin.
	Slug schema.CollectionSlug
	// Labels override the singular and plural names shown to authors.
	Labels CollectionLabels
	// Admin configures collection presentation and editorial organization.
	Admin CollectionAdmin
	// Fields owns the collection's immutable field shape, behavior, and presentation.
	Fields field.Fields
	// Indexes defines ordered multi-field indexes. Unique indexes enforce tuple
	// uniqueness while allowing multiple rows containing null.
	Indexes []CollectionIndex
	// Auth enables identities, passwords, and sessions for this collection.
	Auth bool
	// AuthConfig customizes behavior that applies when Auth is enabled.
	AuthConfig AuthConfig
	// Upload enables file metadata and storage behavior for this collection.
	Upload bool
	// UploadConfig customizes validation, privacy, and image variants for uploads.
	UploadConfig UploadConfig
	// Versions enables document revisions for this collection.
	Versions bool
	// Trash keeps deleted documents recoverable until they are permanently deleted.
	Trash bool
	// LockDocuments coordinates exclusive document editing with timeout and takeover.
	LockDocuments bool
	// DocumentLockConfig customizes lock expiry when LockDocuments is enabled.
	DocumentLockConfig DocumentLockConfig
	// VersionConfig customizes drafts, retention, and autosave behavior.
	VersionConfig VersionConfig
	// Access defines collection-level authorization for each operation.
	Access CollectionAccess
	// Hooks defines collection-wide lifecycle behavior.
	Hooks CollectionHooks
	// Endpoints declares custom HTTP endpoints below
	// /api/collections/<slug>. They run before matching built-in collection
	// routes for the same method.
	Endpoints []Endpoint
}

type CollectionAccess struct {
	// Admin controls whether an authenticated user from this auth collection may
	// enter the framework admin. It accepts only Allow or Deny and defaults to
	// Allow when omitted.
	Admin AccessRule
	// Create controls document creation.
	Create AccessRule
	// Read controls individual and list reads and may return a Where decision.
	Read AccessRule
	// ReadVersions controls version-history reads and may return a Where
	// decision. When omitted, Read is used.
	ReadVersions AccessRule
	// Update controls document updates and may return a Where decision.
	Update AccessRule
	// Publish controls publishing and atomic published-document edits. When
	// omitted, Update is used so existing policies remain coherent.
	Publish AccessRule
	// Unpublish controls moving a published document back to draft. When
	// omitted, Update is used.
	Unpublish AccessRule
	// Delete controls document deletion and may return a Where decision.
	Delete AccessRule
	// Unlock controls takeover of another editor's active document lock. When
	// omitted, Update is used so existing collection policies remain coherent.
	Unlock AccessRule
}

type CollectionAdmin struct {
	UseAsTitle              string
	DefaultColumns          []string
	Group                   string
	GroupTranslations       map[string]string
	Description             string
	DescriptionTranslations map[string]string
	FolderField             string
	ParentField             string
	LivePreview             LivePreviewConfig
}

type CollectionHooks struct {
	// BeforeDuplicate runs after the source is access-checked and copied but before validation.
	BeforeDuplicate []Hook
	// BeforeValidate runs before field hooks and built-in checks. On updates,
	// Data may contain only the submitted fields. This shared phase also runs for
	// reads and deletes; check Operation when changing write input.
	BeforeValidate []Hook
	// BeforeChange runs after initial built-in validation for create, duplicate,
	// update, publish, and unpublish. Changes to Data are checked again afterward;
	// custom field validators run after the write hooks finish.
	BeforeChange []Hook
	// BeforeOperation runs before the store operation, including reads and deletes.
	// On writes it follows BeforeChange; changed values are validated before saving.
	BeforeOperation []Hook
	// BeforeRead runs before one or many documents are read.
	BeforeRead []Hook
	// BeforeDelete runs after the original document is loaded but before deletion.
	BeforeDelete []Hook
	// AfterChange runs after create, duplicate, update, publish, or unpublish has
	// saved the document, but before commit. Returning an error rolls back the save.
	AfterChange []Hook
	// AfterRead runs for each response document, including mutation responses,
	// after computed fields resolve and before field read access removes values.
	AfterRead []Hook
	// AfterDelete runs inside the transaction after deletion or trashing.
	AfterDelete []Hook
	// AfterOperation runs after the store operation, including reads and deletes,
	// but before response processing and commit. Errors can still roll back writes.
	AfterOperation []Hook
	// AfterError observes a failure in this resource through Error. It cannot
	// suppress that failure; its own error is added to the returned error.
	AfterError []Hook
	// AfterCommit runs after a successful commit, including read transactions.
	// Guard write-only effects with Operation. It runs outside the transaction;
	// failures cannot roll back saved data, and later effects still run.
	AfterCommit []Hook
}

type CollectionIndex struct {
	Fields []string
	Unique bool
}

type CollectionLabels struct {
	// Singular is used when referring to one document.
	Singular string
	// SingularTranslations overrides Singular for configured admin languages.
	SingularTranslations map[string]string
	// Plural is used in navigation and collection lists.
	Plural string
	// PluralTranslations overrides Plural for configured admin languages.
	PluralTranslations map[string]string
}

type Config struct {
	// Name is the author-facing application name shown by framework tooling.
	Name string
	// NameTranslations overrides Name for configured admin interface languages.
	NameTranslations map[string]string
	// Admin configures the framework-owned administration interface.
	Admin AdminConfig
	// Localization configures content locales. The zero value disables content
	// localization without affecting admin interface language.
	Localization LocalizationConfig
	// AllowIDOnCreate lets ordinary create operations accept a caller-supplied
	// canonical string ID. It is disabled by default; migration imports retain
	// their separate identity-preserving path regardless of this setting.
	AllowIDOnCreate bool
	// Blocks declares shared immutable definitions selected by field and embedded references.
	Blocks []field.Block
	// Collections declares every document collection owned by the application.
	Collections []Collection
	// Globals declares singleton documents with their own API and admin routes.
	Globals []Global
	// Endpoints declares application-level custom HTTP endpoints below /api.
	// Handlers are anonymous by default and must enforce their own policy.
	Endpoints []Endpoint
	// Tasks registers compiled durable task handlers. Executable handlers are
	// runtime-only and are intentionally excluded from the schema manifest.
	Tasks []TaskDefinition
	// Hooks observes application-wide lifecycle failures.
	Hooks RootHooks
	// Plugins lists compiled extensions in deterministic execution order.
	Plugins []Plugin
	// AfterCommit dispatches effects only after a successful transaction commits.
	AfterCommit AfterCommitDispatcher
	// Storage provides the application-wide object-storage adapter when App is
	// constructed directly with New. Applications run through Execute should
	// prefer WithUploadStorage so external clients are opened only at runtime.
	// Storage is never serialized into the schema manifest.
	Storage storage.Backend
	// StorageNamespace is the stable, deployment-owned prefix for upload objects.
	// It must remain unchanged when the display Name changes and must be unique
	// among applications sharing one backend.
	StorageNamespace string
	// contains filtered or unexported fields
}

type ConfigTransformer interface {
	Plugin
	TransformConfig(Config) (Config, error)
}

type DescriptorProvider interface {
	Plugin
	Descriptor() PluginDescriptor
}

type DistinctOptions struct {
	// Field names the authored scalar, singular relationship, singular upload,
	// or document ID whose unique values should be returned.
	Field query.Path
	// Where remains atomic with the collection read-access predicate.
	Where query.Expression
	// Page is one-based. Zero selects the first page.
	Page int
	// Limit follows ordinary Ridu list bounds and defaults.
	Limit int
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Draft follows List semantics for versioned collections.
	Draft *bool
	// TrashOnly returns values from deleted documents and requires trash support.
	TrashOnly       bool
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
}

type DocumentLockConfig struct {
	Duration time.Duration
}

type DocumentLockState struct {
	Lock        *store.DocumentLock
	Owned       bool
	Acquired    bool
	CanTakeOver bool
}

type Endpoint struct {
	// Method is one supported HTTP method. Matching is case-insensitive during
	// config resolution and the manifest stores its uppercase form.
	Method string
	// Path begins with / and may contain named :parameter segments.
	Path string
	// Summary appears in the generated OpenAPI operation. When empty, Ridu
	// supplies a deterministic generic summary.
	Summary string
	// MaxBodyBytes bounds the raw request body before Handler receives it. Zero
	// inherits HandlerOptions.MaxBodyBytes; a negative value opts trusted
	// streaming code out of that bound.
	MaxBodyBytes int64
	// Handler is trusted compiled application code and is never serialized.
	Handler EndpointHandler
}

type EndpointContext struct {
	// Writer receives the status, headers, and body chosen by the handler.
	Writer http.ResponseWriter
	// Request is the matched HTTP request. Use its Context for cancellation,
	// deadlines, and dependent work.
	Request *http.Request
	// RequestID is the framework request ID also returned in X-Request-ID.
	RequestID string
	// ClientIP is resolved through the configured trusted-proxy policy.
	ClientIP string
	// RouteParams contains decoded named path parameters.
	RouteParams map[string]string
	// Collection identifies the owning collection endpoint, when applicable.
	Collection schema.CollectionSlug
	// Global identifies the owning global endpoint, when applicable.
	Global schema.CollectionSlug
	// Actor is the authenticated user, or nil for an anonymous request.
	Actor *store.Document
	// ActorCollection identifies the auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Local enters the same access-controlled operation engine as REST and the
	// generated SDK.
	Local *LocalAPI
	// AdmitAuthAttempt applies the distributed authentication-attempt policy for
	// endpoints implementing an authentication flow.
	AdmitAuthAttempt func(context.Context, string, string) error
	// ReportError records a stable code and sends trusted detail to
	// HandlerOptions.RequestError without exposing it to the client.
	ReportError func(error, string)
}

type EndpointHandler func(EndpointContext)

type EndpointProvider interface {
	Plugin
	Endpoints() []PluginEndpoint
}

type ExecuteOption func(*executeOptions)

type FieldCapabilities struct {
	Read   bool
	Create bool
	Update bool
}

type FieldGraphContext struct {
	ResourceKind string
	Slug         schema.CollectionSlug
}

type FieldGraphTransformer interface {
	Plugin
	TransformFields(FieldGraphContext, field.Fields) (field.Fields, error)
}

type FieldGraphValidator interface {
	Plugin
	ValidateFields(FieldGraphContext, field.Fields) error
}

type FieldValidatorProvider interface {
	Plugin
	FieldValidators() map[string]PluginFieldValidator
}

type FindOptions struct {
	// Select is nil for all authored fields. A non-nil empty slice returns only
	// document metadata.
	Select   []query.Path
	Populate []query.Population
	// OutputFields limits computed and inverse-join resolution independently
	// from Select. Nil resolves all; a non-nil empty slice resolves none.
	OutputFields []query.Path
	// Draft explicitly includes draft documents when true or restricts reads to
	// published documents when false. Nil preserves the Local API default.
	Draft           *bool
	Actor           *store.Document
	ActorCollection schema.CollectionSlug
	TrashOnly       bool
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
	AllLocales      bool
}

type GenerationProvider interface {
	Plugin
	GeneratedArtifacts(PluginGenerationContext) ([]PluginGeneratedArtifact, error)
}

type Global struct {
	// Slug is the URL-safe global name used by APIs and the admin.
	Slug schema.CollectionSlug
	// Label overrides the author-facing name shown in navigation and headings.
	Label string
	// LabelTranslations overrides Label for configured admin interface languages.
	LabelTranslations map[string]string
	// Admin is serializable presentation metadata consumed by the framework admin.
	Admin GlobalAdmin
	// Fields owns the global's immutable field shape, behavior, and presentation.
	Fields field.Fields
	// Versions enables revisions for this global.
	Versions bool
	// VersionConfig customizes drafts, retention, and autosave behavior.
	VersionConfig VersionConfig
	// Access defines read and update authorization.
	Access GlobalAccess
	// Hooks defines global-wide lifecycle behavior.
	Hooks CollectionHooks
	// Endpoints declares custom HTTP endpoints below /api/globals/<slug>.
	// They run before matching built-in global routes for the same method.
	Endpoints []Endpoint
}

type GlobalAccess struct {
	// Read controls global reads and may return a Where decision.
	Read AccessRule
	// ReadVersions controls version-history reads and may return a Where decision.
	// When omitted, Read is used.
	ReadVersions AccessRule
	// Update controls global updates and may return a Where decision for an
	// existing singleton.
	Update AccessRule
	// Publish controls publishing and atomic published-global edits. When
	// omitted, Update is used.
	Publish AccessRule
	// Unpublish controls moving a published global back to draft. When omitted,
	// Update is used.
	Unpublish AccessRule
}

type GlobalAdmin struct {
	Group                   string
	GroupTranslations       map[string]string
	Description             string
	DescriptionTranslations map[string]string
	LivePreview             LivePreviewConfig
}

type HandlerOptions struct {

	// AdminAssets overrides the framework's embedded admin asset filesystem.
	AdminAssets fs.FS
	// MaxBodyBytes limits decoded request bodies. Zero uses the framework default.
	MaxBodyBytes int64
	// SecureCookies restricts auth cookies to HTTPS requests.
	SecureCookies bool
	// AllowedOrigins lists browser origins permitted by CORS.
	AllowedOrigins []string
	// AllowedRequestHeaders appends application-owned CORS request headers to
	// Ridu's SDK headers. Invalid HTTP token names are ignored.
	AllowedRequestHeaders []string
	// AllowedHosts restricts the HTTP Host header. Entries are exact hostnames
	// with an optional port; an entry without a port accepts any port. Empty
	// accepts every syntactically valid host for development. Production
	// deployments should set their public hostnames.
	AllowedHosts []string
	// TrustedProxyCIDRs lists proxies whose forwarded client addresses are trusted.
	TrustedProxyCIDRs []string
	// AuthRateLimit is the maximum auth attempts per identity and client window.
	AuthRateLimit int
	// AuthRateWindow is the duration over which AuthRateLimit is enforced.
	AuthRateWindow time.Duration
	// Audit receives security-relevant application events.
	Audit func(AuditEvent)
	// Observe receives timing and status metadata for completed requests.
	Observe func(RequestObservation)
	// RequestError receives trusted diagnostic detail for internal failures and
	// recovered panics. The HTTP response remains redacted.
	RequestError func(RequestErrorEvent)
	// RequestTimeout limits request execution. Zero uses the framework default;
	// a negative duration disables the handler deadline for streaming plugins.
	RequestTimeout time.Duration
	// ReadinessChecks add application/plugin dependencies to /readyz. Checks
	// must be read-only, repeatable, and honor Context cancellation.
	ReadinessChecks []ReadinessCheck
	// ReadinessTimeout bounds the complete database, storage, and custom
	// readiness probe. Zero uses five seconds; a negative duration disables it.
	ReadinessTimeout time.Duration
	// ContentSecurityPolicy overrides the framework admin policy. Empty uses a
	// conservative default compatible with live-preview frames.
	ContentSecurityPolicy string
	// DisableContentSecurityPolicy explicitly disables the admin CSP when an
	// upstream gateway owns it.
	DisableContentSecurityPolicy bool
	// StrictTransportSecurity is emitted verbatim when non-empty. Configure it
	// only when every public request is HTTPS, normally at the TLS terminator.
	StrictTransportSecurity string
	// TaskInterval controls how often the durable task queues are polled. Zero
	// uses the framework default.
	TaskInterval time.Duration
	// TaskBatch limits durable task leases claimed during one polling cycle.
	TaskBatch int
	// TaskQueues optionally restricts this process to named queues. An empty
	// list consumes every queue, including unknown task slugs so they can be
	// moved to a stable terminal failure.
	TaskQueues []string
	// TaskLeaseDuration is extended by heartbeats while a handler is running.
	TaskLeaseDuration time.Duration
	// TaskHeartbeatInterval must remain shorter than TaskLeaseDuration.
	TaskHeartbeatInterval time.Duration
	// TaskPruneBatch bounds terminal records removed after their retention.
	TaskPruneBatch int
	// AuthPruneBatch bounds expired sessions and API keys removed from each
	// durable credential family during one background maintenance cycle.
	AuthPruneBatch int
	// JobError receives failures from scheduled background work.
	JobError func(error)
	// contains filtered or unexported fields
}

type Hook func(HookContext) error

type HookContext struct {
	// Context carries cancellation, deadlines, and the active transaction.
	// Pass it to Local calls that must succeed or roll back with this operation.
	Context context.Context
	// Operation names the document operation, such as Create, Update, or Read,
	// not the hook phase. Shared hooks should check it before running write-only work.
	Operation operation.Kind
	// CollectionID is the collection's stable resource ID, not its slug.
	// It is empty for a global operation.
	CollectionID schema.StableID
	// GlobalID is the global's stable resource ID, not its slug.
	// It is empty for a collection operation.
	GlobalID schema.StableID
	// Actor is the authenticated document, or nil for an anonymous operation.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Data contains values at this phase: submitted input in BeforeValidate,
	// then the completed document in BeforeChange and BeforeOperation on writes.
	// Change map entries to change stored values; assigning a new map to Data
	// does not replace the engine's values. Changes after saving are not persisted.
	Data store.Values
	// Document is the response document when available. AfterRead receives each
	// document in a list separately. Changes to Document.Values affect the response,
	// not stored data, and remain subject to field read access rules.
	Document *store.Document
	// Original is a detached copy of the saved document before an update, delete,
	// or duplication. Changing it does not change storage.
	Original *store.Document
	// Local performs nested reads and writes through the normal operation engine.
	// Pass Context to reuse the transaction, and pass Actor, ActorCollection, and
	// locale options explicitly when the nested operation represents the same user.
	// Standalone reads reject nested writes; AfterCommit starts new transactions.
	Local *LocalAPI
	// Error is set only for after-error hooks and preserves the original failure.
	// Returning nil from AfterError does not make the failed operation succeed.
	Error error
	// Locale is the selected content language. Write hooks use the write locale;
	// AfterRead uses the response locale, whose values may include fallback text.
	Locale schema.LocaleCode
	// AllLocales reports whether localized values contain maps keyed by locale.
	// It describes this hook's values, which may differ from the requested response.
	AllLocales bool
}

type HookProvider interface {
	Plugin
	Hooks() []PluginHookContribution
}

type ImageSize struct {
	// Name is the stable key used to address the generated variant.
	Name string
	// Width is the target width in pixels.
	Width int
	// Height is the target height in pixels.
	Height int
	// Fit controls resizing and must be either "cover" or "contain".
	Fit string
}

type ImportOptions struct {
	// ID preserves the source document identity.
	ID string
	// Status preserves the source draft or published status.
	Status store.Status
	// CreatedAt preserves the source creation timestamp.
	CreatedAt time.Time
	// UpdatedAt preserves the source modification timestamp.
	UpdatedAt time.Time
}

type Input[T any] struct {
	// contains filtered or unexported fields
}

type JoinMutationResult struct {
	Document store.Document
	Added    int
	Removed  int
}

type ListOptions struct {
	// Where filters documents before pagination and remains atomic with access predicates.
	// Paths with a Read rule on the field or an ancestor are not queryable.
	Where query.Expression
	// Page is the one-based result page. Zero selects the first page.
	Page int
	// Limit is the maximum documents returned per page.
	Limit int
	// Sort orders results by authored field paths without Read rules on the field or ancestors.
	// Container sorts also require all descendants to have no Read rules.
	Sort []query.Sort
	// Select restricts returned document fields.
	Select []query.Path
	// Populate expands configured relationship paths.
	Populate []query.Population
	// OutputFields limits computed and inverse-join resolution without
	// projecting away stored fields. Nil resolves all output fields; a non-nil
	// empty slice resolves none.
	OutputFields []query.Path
	// Draft explicitly includes draft documents when true or restricts reads to
	// published documents when false. Nil preserves the Local API default.
	Draft *bool
	// Actor is the authenticated document used by access rules.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// TrashOnly returns deleted documents and is valid only for trash-enabled collections.
	TrashOnly bool
	// Locale selects one configured content locale. Empty uses the application default.
	Locale schema.LocaleCode
	// FallbackLocales replaces the locale's configured fallback chain when non-nil.
	FallbackLocales []schema.LocaleCode
	// DisableFallback requires an exact value in Locale.
	DisableFallback bool
	// AllLocales returns locale-keyed values for localized fields.
	AllLocales bool
}

type ListWindowOptions struct {
	Index           query.Path
	LowerBound      string
	UpperBound      string
	Limit           int
	Select          []query.Path
	Actor           *store.Document
	ActorCollection schema.CollectionSlug
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
	AllLocales      bool
}

type LivePreviewConfig struct {
	URL         string
	Breakpoints []PreviewBreakpoint
}

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

type Locale struct {
	Code            schema.LocaleCode
	Label           string
	RTL             bool
	FallbackLocales []schema.LocaleCode
}

type LocaleAvailability func(LocaleAvailabilityContext) ([]schema.LocaleCode, error)

type LocaleAvailabilityContext struct {
	Context         context.Context
	Actor           *store.Document
	ActorCollection schema.CollectionSlug
	Local           *LocalAPI
}

type LocaleOptions struct {
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
	AllLocales      bool
}

type LocalizationConfig struct {
	Locales         []Locale
	DefaultLocale   schema.LocaleCode
	DisableFallback bool
	// AvailableLocales may reduce the locale list exposed to an admin request.
	// It does not weaken API validation or authorization and is never serialized.
	AvailableLocales LocaleAvailability
}

type LoginOptions struct {
	// IPAddress is the direct or trusted-forwarded client address.
	IPAddress string
	// UserAgent is the untrusted client user-agent string.
	UserAgent string
}

type MutationOptions struct {
	// ID supplies a caller-owned document ID for create operations when
	// Config.AllowIDOnCreate is enabled. Other mutations ignore it.
	ID               string
	Actor            *store.Document
	ActorCollection  schema.CollectionSlug
	ExpectedRevision int
	Populate         []query.Population
	// OutputFields limits computed and inverse-join resolution in the returned
	// document. Nil resolves all; a non-nil empty slice resolves none.
	OutputFields []query.Path
	// Draft selects draft (true) or published (false) status for versioned
	// creates. Updates preserve status so publish and unpublish hooks cannot be bypassed.
	Draft           *bool
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
	AllLocales      bool
}

type NonNullInput[T any] struct {
	// contains filtered or unexported fields
}

type OperationCapabilities struct {
	Admin           bool
	Create          bool
	Read            bool
	ReadVersions    bool
	Update          bool
	Delete          bool
	Duplicate       bool
	Publish         bool
	Unpublish       bool
	RestoreDeleted  bool
	DeletePermanent bool
	SelectAll       bool
	Unlock          bool
}

type OperationError = operationengine.Error

type PasswordPolicy struct {
	// MinLength is the minimum password length in Unicode code points. Zero
	// defaults to 8.
	MinLength int
	// MaxBytes is the maximum UTF-8 encoded password length. Zero defaults to 72,
	// bcrypt's safe input limit.
	MaxBytes int
	// BcryptCost controls bcrypt work. Zero uses bcrypt.DefaultCost. Increasing
	// it transparently upgrades older hashes after a successful login. Values
	// above 16 are rejected because they can make startup and login impractical.
	BcryptCost int
	// Validate adds application-specific password rules. Return a user-safe error
	// explaining how the candidate must change.
	Validate func(password string) error
}

type PasswordResetConfig struct {
	// TokenDuration is the lifetime of a reset token. Zero defaults to one hour.
	TokenDuration time.Duration
	// Send delivers a newly issued token. It should enqueue or send the message
	// before returning; returning an error prevents a success response.
	Send func(context.Context, PasswordResetNotification) error
}

type PasswordResetNotification struct {
	Collection schema.CollectionSlug
	User       store.Document
	Token      string
	ExpiresAt  time.Time
}

type Plugin interface {
	Key() string
}

type PluginDatabaseAdapter = schema.PluginDatabaseAdapter

type PluginDatabaseContribution struct {
	Adapter    PluginDatabaseAdapter
	Migrations []PluginMigration
	Tables     []string
}

type PluginDescriptor struct {
	// Version is the plugin's complete semantic release without a leading v.
	Version string
	// GoPackage is the canonical import path that provides the plugin.
	GoPackage string
	// APIVersion must equal PluginAPIVersion for this Ridu release.
	APIVersion uint32
	// Ridu limits the framework releases allowed to compile this plugin.
	Ridu RiduCompatibility
	// Admin describes the optional statically bundled admin half.
	Admin *AdminPluginMetadata
	// FieldTypes maps every reusable plugin field to generated public types.
	FieldTypes []PluginFieldType
	// DatabaseContributions contains exceptional, adapter-specific private
	// database state. Ordinary plugin data should be added as collections or
	// fields through ConfigTransformer instead.
	DatabaseContributions []PluginDatabaseContribution
}

type PluginEndpoint struct {
	// Method is an exact supported HTTP method such as GET or POST.
	Method string
	// Path is relative to the plugin's namespaced API prefix.
	Path string
	// Summary appears in generated OpenAPI.
	Summary string
	// MaxBodyBytes bounds the raw request body before Handler receives it. Zero
	// inherits HandlerOptions.MaxBodyBytes; a negative value explicitly opts a
	// trusted streaming endpoint out of that byte bound.
	MaxBodyBytes int64
	// Handler is trusted compiled endpoint code.
	Handler PluginEndpointHandler
}

type PluginEndpointContext struct {
	// Writer receives the endpoint response.
	Writer http.ResponseWriter
	// Request is the original namespaced HTTP request.
	Request *http.Request
	// ClientIP is the direct or trusted-forwarded client address resolved by
	// the framework HTTP boundary. Authentication transports should use this
	// value instead of interpreting forwarding headers independently.
	ClientIP string
	// Actor is the authenticated user, or nil for an anonymous request.
	Actor *store.Document
	// ActorCollection identifies the auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Local enters the same access-controlled operation engine as other APIs.
	Local *LocalAPI
	// AdmitAuthAttempt applies the application's distributed IP and identity
	// admission policy. Authentication transports must call it before work that
	// can be amplified by aliases or repeated requests.
	AdmitAuthAttempt func(context.Context, string, string) error
	// ReportError records a stable transport error code and sends trusted error
	// detail to HandlerOptions.RequestError without exposing it to the client.
	// Plugins that implement their own error envelopes should call this for
	// internal failures. Passing nil records only Code in request observations.
	ReportError func(error, string)
}

type PluginEndpointHandler func(PluginEndpointContext)

type PluginFieldType struct {
	// EmbeddedTypes lists tree.case selectors supplying ordered generic payload type arguments.
	EmbeddedTypes []string `json:"embeddedTypes,omitempty"`
	// Key matches the PluginField key stored in the schema manifest.
	Key string
	// TypeScriptPackage is the static import specifier exporting the named output,
	// input, and where types. It may select a package export subpath.
	TypeScriptPackage string
	// TypeScriptOutput is the stored document value type export.
	TypeScriptOutput string
	// TypeScriptInput is the create and update value type export.
	TypeScriptInput string
	// TypeScriptWhere is the optional query operand type export.
	TypeScriptWhere string
	// GoPackage and GoType optionally name the generated Go model type.
	GoPackage string
	// GoType is an exported type in GoPackage; both Go fields are optional together.
	GoType string
	// JSONSchema is the deterministic OpenAPI 3.1 schema for one field value.
	JSONSchema []byte
}

type PluginFieldValidationContext struct {
	// Field is the resolved manifest definition owned by the plugin.
	Field schema.Field
	// RuntimePath identifies this concrete value occurrence. Unlike Field.Path,
	// it includes array and block indexes and omits block schema discriminators.
	RuntimePath string
	// Value is the candidate document value to validate.
	Value store.Value
}

type PluginFieldValidator func(PluginFieldValidationContext) []schema.Issue

type PluginGeneratedArtifact struct {
	Name    string
	Content []byte
}

type PluginGenerationContext struct {
	Manifest schema.Manifest
}

type PluginHookContribution struct {
	// Collection identifies the collection receiving Hooks.
	Collection schema.CollectionSlug
	// Hooks are appended after application-authored hooks.
	Hooks CollectionHooks
}

type PluginMigration struct {
	// Version starts at 1 and increments without gaps.
	Version uint32
	// Name is a stable lowercase kebab-case review label.
	Name string
	// UpSQL executes in order when entering Version.
	UpSQL []string
	// DownSQL executes in order when leaving Version.
	DownSQL []string
}

type PluginTransport struct {
	Method       string
	Path         string
	Summary      string
	MaxBodyBytes int64
	Handler      PluginEndpointHandler
}

type PluginTransportContext struct {
	Manifest schema.Manifest
	Local    *LocalAPI
	// App exposes public authentication and other application-owned operations
	// that do not belong to LocalAPI. It is fully initialized before binding.
	App *App
}

type PreviewBreakpoint struct {
	Name              string
	Label             string
	LabelTranslations map[string]string
	Width             int
	Height            int
}

type PreviewToken struct {
	Token      string
	Resource   string
	Slug       string
	DocumentID string
	ExpiresAt  time.Time
}

type ReadinessCheck func(context.Context) error

type ReconcileResult struct {
	// Scanned is the number of stored objects inspected.
	Scanned int
	// Candidates is the number of unreferenced objects older than the safety window.
	Candidates int
	// Deleted is the number of unreferenced objects removed.
	Deleted int
}

type RemoteUploadInput struct {
	URL             string
	Data            store.Values
	Actor           *store.Document
	ActorCollection schema.CollectionSlug
	Locale          LocaleOptions
}

type RequestErrorEvent struct {
	Time      time.Time
	RequestID string
	Method    string
	Path      string
	Error     error
	Panic     bool
	Stack     string
}

type RequestObservation struct {
	// Time is when the observation was recorded.
	Time time.Time
	// RequestID correlates the observation with audit events and logs.
	RequestID string
	// Method is the HTTP request method.
	Method string
	// Path is the requested URL path.
	Path string
	// Status is the HTTP response status code.
	Status int
	// ErrorCode is the stable public Ridu code for a failed request.
	ErrorCode string
	// ResponseBytes is the number of response-body bytes written.
	ResponseBytes int64
	// Duration is the total handler execution time.
	Duration time.Duration
}

type RiduCompatibility struct {
	// Minimum is the oldest supported Ridu semantic version, inclusive.
	Minimum string
	// MaximumExclusive is the optional first unsupported Ridu version.
	MaximumExclusive string
}

type RootHooks struct {
	// AfterError observes failures after resource error hooks, including failures
	// before a collection or global could be identified. It cannot suppress them.
	AfterError []Hook
}

type ServerOptions struct {
	ReadHeaderTimeout   time.Duration
	ReadTimeout         time.Duration
	WriteTimeout        time.Duration
	IdleTimeout         time.Duration
	MaxHeaderBytes      int
	ShutdownTimeout     time.Duration
	WorkerDrainTimeout  time.Duration
	ReadinessDrainDelay time.Duration
	// AllowUnverifiableReadiness permits Execute with custom database or upload
	// adapters that cannot prove readiness. It is an explicit production safety
	// escape hatch; official adapters do not require it.
	AllowUnverifiableReadiness bool
	// SkipReadinessPreflight lets a development server bind before dependency
	// verification. Its /readyz probe still checks database connectivity,
	// storage, and custom checks, but permits an unapplied migration ledger
	// while ridu dev owns non-destructive schema synchronization.
	SkipReadinessPreflight bool
}

type StorageFactory func(context.Context) (storage.Backend, error)

type StoreFactory func(context.Context) (store.Store, error)

type TaskBackoff = store.TaskBackoff

type TaskContext struct {
	Context context.Context
	ID      string
	Attempt int
	Local   *LocalAPI
	// contains filtered or unexported fields
}

type TaskDefinition interface {
	TaskSlug() string
	// contains filtered or unexported methods
}

type TaskEnqueueOptions struct {
	RunAt          time.Time
	Queue          string
	ConcurrencyKey string
	Target         *store.DocumentReference
	RequestedBy    *store.DocumentReference
}

type TaskError struct {
	Code    TaskErrorCode
	Message string
	Cause   error
}

type TaskErrorCode string

type TaskHandler[Input, Output any] func(TaskContext, Input) (Output, error)

type TaskOption func(*taskConfig)

type TaskReceipt[Output any] struct {
	ID    string
	Slug  string
	Queue string
	RunAt time.Time
}

type TaskReconciler func(context.Context, *App) error

type TaskResult[Output any] struct {
	ID            string
	Slug          string
	Queue         string
	State         store.TaskState
	Attempts      int
	MaxAttempts   int
	LastErrorCode string
	LastError     string
	CreatedAt     time.Time
	UpdatedAt     time.Time
	CompletedAt   *time.Time
	Output        Output
	HasOutput     bool
}

type TaskRunSummary struct {
	Claimed   int
	Succeeded int
	Retried   int
	Failed    int
	Released  int
	Pruned    int
}

type TransportProvider interface {
	Plugin
	BindTransports(PluginTransportContext) ([]PluginTransport, error)
}

type TypedAllLocalesCollection[Document any] struct {
	// contains filtered or unexported fields
}

type TypedAllLocalesGlobal[Document any] struct {
	// contains filtered or unexported fields
}

type TypedCollection[Document, Create, Update any] struct {
	// contains filtered or unexported fields
}

type TypedGlobal[Document, Update any] struct {
	// contains filtered or unexported fields
}

type TypedListOptions struct {
	// Where filters documents before pagination and remains atomic with access predicates.
	Where query.Expression
	// Page is the one-based result page. Zero selects the first page.
	Page int
	// Limit is the maximum documents returned per page.
	Limit int
	// Sort orders results by authored field paths.
	Sort []query.Sort
	// TrashOnly returns deleted documents and is valid only for trash-enabled collections.
	TrashOnly bool
	// Draft explicitly includes draft documents when true or restricts reads to
	// published documents when false. Nil preserves the Local API default.
	Draft *bool
	// Select restricts returned document fields.
	Select []query.Path
	// Populate expands configured relationship paths.
	Populate []query.Population
	// OutputFields limits computed and inverse-join resolution without
	// projecting away stored fields. Nil resolves all output fields; a non-nil
	// empty slice resolves none.
	OutputFields []query.Path
	// Actor is the authenticated document used by access rules.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Locale selects one configured content locale. Empty uses the application default.
	Locale schema.LocaleCode
	// FallbackLocales replaces the locale's configured fallback chain when non-nil.
	FallbackLocales []schema.LocaleCode
	// DisableFallback requires an exact value in Locale.
	DisableFallback bool
}

type TypedLocaleOptions struct {
	Locale          schema.LocaleCode
	FallbackLocales []schema.LocaleCode
	DisableFallback bool
}

type TypedPage[Document any] struct {
	Documents []Document
	Page      int
	Limit     int
	Total     int
}

type TypedReadOptions struct {
	// Draft explicitly includes draft documents when true or restricts reads to
	// published documents when false. Nil preserves the Local API default.
	Draft *bool
	// Select restricts returned document fields.
	Select []query.Path
	// Populate expands configured relationship paths.
	Populate []query.Population
	// OutputFields limits computed and inverse-join resolution without
	// projecting away stored fields. Nil resolves all output fields; a non-nil
	// empty slice resolves none.
	OutputFields []query.Path
	// Actor is the authenticated document used by access rules.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Locale selects one configured content locale. Empty uses the application default.
	Locale schema.LocaleCode
	// FallbackLocales replaces the locale's configured fallback chain when non-nil.
	FallbackLocales []schema.LocaleCode
	// DisableFallback requires an exact value in Locale.
	DisableFallback bool
}

type TypedTask[Input, Output any] struct {
	// contains filtered or unexported fields
}

type UpdateUploadImageInput struct {
	// FocalX is the horizontal focal coordinate from 0 (left) to 100 (right).
	FocalX float64
	// FocalY is the vertical focal coordinate from 0 (top) to 100 (bottom).
	FocalY float64
	// CropX and CropY are the top-left of an optional normalized crop rectangle.
	CropX float64
	CropY float64
	// CropWidth and CropHeight are zero to clear the crop, otherwise each must
	// be positive and the rectangle must remain within the original image.
	CropWidth  float64
	CropHeight float64
	// ExpectedRevision rejects changes based on a stale document revision.
	ExpectedRevision int
	// Actor is the authenticated document used by read and update access rules.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
}

type UploadConfig struct {
	// MaxFileSize is the maximum accepted upload size in bytes. Zero uses the
	// framework default; values above 256 MiB are rejected so one request cannot
	// bypass the process-wide upload work budget.
	MaxFileSize int64
	// MimeTypes restricts uploads to the listed media types. Empty accepts any supported type.
	MimeTypes []string
	// Private requires authorized delivery instead of exposing storage objects publicly.
	Private bool
	// ImageSizes declares derived image variants generated from supported image uploads.
	ImageSizes []ImageSize
}

type UploadInput struct {
	// Filename is the original client-supplied file name.
	Filename string
	// Reader provides the uploaded bytes.
	Reader io.Reader
	// Data contains application-owned upload document fields.
	Data store.Values
	// Actor is the authenticated document used by access rules.
	Actor *store.Document
	// ActorCollection identifies the exact auth collection that owns Actor.
	ActorCollection schema.CollectionSlug
	// Locale selects the content locale for application-owned upload metadata.
	Locale LocaleOptions
}

type VerifyEmailConfig struct {
	// TokenDuration is the lifetime of a verification token. Zero defaults to 24 hours.
	TokenDuration time.Duration
	// Send delivers a newly issued verification token.
	Send func(context.Context, VerifyEmailNotification) error
}

type VerifyEmailNotification struct {
	Collection schema.CollectionSlug
	User       store.Document
	Token      string
	ExpiresAt  time.Time
}

type VersionConfig struct {
	// Drafts allows unpublished document states.
	Drafts bool
	// MaxPerDocument limits retained revisions per document. Zero uses the framework default.
	MaxPerDocument int
	// AutosaveInterval controls draft autosave frequency. Zero disables autosave.
	AutosaveInterval time.Duration
}