entity

type AccessControl struct {
	Read   string // List + Get
	Create string
	Update string
	Delete string
}

type AccessDeclaration struct {
	Read   string `json:"read,omitempty"`
	Create string `json:"create,omitempty"`
	Update string `json:"update,omitempty"`
	Delete string `json:"delete,omitempty"`
}

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

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

type Endpoint struct {
	Method       string          `json:"method"`
	Path         string          `json:"path"`
	Name         string          `json:"name,omitempty"`
	Description  string          `json:"description,omitempty"`
	MCP          bool            `json:"mcp,omitempty"`
	InputSchema  []schema.Field  `json:"inputSchema,omitempty"`
	OutputSchema []schema.Field  `json:"outputSchema,omitempty"`
	Handler      http.Handler    `json:"-"`
	MCPHandler   mcp.ToolHandler `json:"-"`

	// MCPGate is an optional per-caller precondition for the MCP twin. It
	// runs before MCPHandler on every tools/call, and decides whether the
	// tool is visible to that caller in tools/list.
	//
	// It exists because the two front doors of one Endpoint do not get the
	// same protection for free: Handler inherits the route's middleware
	// chain, while MCPHandler is registered straight onto the MCP server and
	// sees none of it. An endpoint behind auth.RequireRole("editor") was
	// therefore role-checked over HTTP and ungated over MCP.
	//
	// When unset, the twin defaults to requiring an authenticated caller
	// (framework.MCPRequireUser). Set MCPPublic to opt out of that default;
	// set this to something stricter, e.g. auth.MCPRole("editor").
	MCPGate func(ctx context.Context) error `json:"-"`

	// MCPPublic opts the MCP twin out of the default authenticated-caller
	// gate, for an endpoint that really is anonymous over HTTP too. Ignored
	// when MCPGate is set.
	MCPPublic bool `json:"mcpPublic,omitempty"`
}

type Entity struct {
	Config     EntityConfig
	DB         *sql.DB
	PrimaryKey string // defaults to "id"

	// Version identifies the API version this entity is mounted under, when
	// registered via App.GroupEntity. It is the route group's full prefix
	// (e.g. "/api/v1"). Empty for entities registered via App.Entity — those
	// keep the historical single-version behaviour. The registry keys on
	// (Config.Name, Version) so the same entity name can coexist under
	// different versions; callers that don't care about version resolve the
	// unversioned or sole entity via Registry.Get.
	Version string

	// OpenAPITag is the tag applied to this entity's operations in the
	// generated OpenAPI document. Set from the route group's OpenAPITag
	// when registered via App.GroupEntity; empty for App.Entity (the tag
	// defaults to the entity name in that case).
	OpenAPITag string
}

type EntityConfig struct {
	Name       string            // entity name (e.g. "users")
	Table      string            // DB table name (defaults to snake_case of Name)
	Fields     []schema.Field    // typed field definitions
	Relations  []Relation        // entity relationships
	Endpoints  []Endpoint        // custom HTTP endpoints for this entity
	Scope      *ScopeConfig      // ownership, tenancy, and soft-delete behavior
	Pagination *PaginationConfig // list limits and keyset cursor shape
	Exposure   *ExposureConfig   // generated HTTP/MCP and access posture
	Timestamps *bool             // add created_at / updated_at columns; nil defaults to true
	Indices    []Index           // additional CREATE INDEX statements emitted by AutoMigrate
	Unmanaged  bool              // when true, the migration system never emits DDL for this object (it is created elsewhere — e.g. a view, an FTS virtual table, or a legacy/external table). The ORM still queries it.

	// Properties holds caller-owned metadata. The framework does not
	// interpret any key; generators, plugins, and apps define their own keys.
	Properties map[string]any

	// SearchFields names the DB columns that ?q= free-text search operates
	// on (e.g. []string{"title","body"}). When non-empty, a List request
	// carrying ?q=<term> tokenizes the term on whitespace (deduped, capped
	// at filter.MaxSearchTerms) and AND-composes one LOWER(col) LIKE
	// pattern per token across the listed fields. Matching is
	// ASCII-case-insensitive everywhere (Unicode-folding on Postgres).
	// Leave nil to keep pre-existing behaviour (?q= is ignored). Column
	// names must be known, non-Hidden, and String/Text-typed; Define panics
	// otherwise. An entity WITHOUT SearchFields ignores ?q= exactly as
	// before (back-compat).
	SearchFields []string

	// Seed runs once per entity after AutoMigrate creates the table. The
	// framework tracks completion in the _gofastr_seeded ledger; subsequent
	// App.Start() calls skip the entity. Errors abort App.Start.
	//
	// Go-only: function values cannot be expressed in a blueprint
	// declaration. Apps whose entities come from a gofastr.yml blueprint
	// must wire seeding from Go.
	//
	// Concurrency: RunSeeds is NOT safe for concurrent invocation across
	// multiple processes. The framework assumes serialized startup (one
	// process / replica calls App.Start at a time). For HA setups, gate
	// seeding behind an external mechanism (init container, one-shot
	// job, advisory lock). Seed implementations should be idempotent
	// (INSERT … ON CONFLICT DO NOTHING) so accidental re-runs cannot
	// duplicate data.
	Seed func(ctx context.Context, db *sql.DB) error

	// SeedFS is an optional fs.FS (typically a //go:embed embed.FS) that
	// the framework attaches to the Seed function's context. Use with
	// SeedPath to point at a single file within the FS.
	//
	// Go-only: like Seed itself, an fs.FS cannot be expressed in JSON
	// entity declarations.
	SeedFS fs.FS

	// SeedPath is the path within SeedFS that Seed should consume.
	// Ignored when SeedFS is nil.
	SeedPath string

	// LenientFilters opts the entity's auto-CRUD List endpoint OUT of strict
	// filter parsing. By default an unknown top-level filter key (a typo like
	// ?stauts=active) is REJECTED with a 400 rather than silently dropped —
	// silently dropping it returns an UNFILTERED result set, which is a
	// data-exposure and broken-client hazard. Set true only as a migration
	// escape hatch for an endpoint that must tolerate arbitrary extra query
	// params (e.g. legacy tracking params); prefer fixing the caller.
	// Default false (strict).
	LenientFilters bool

	// AllowedFilterParams declares extra query-param keys that are NOT entity
	// columns but are legitimately consumed elsewhere on the List request —
	// typically read by a BeforeList hook or custom middleware (e.g. a
	// bespoke "?region=eu" scope param). Strict filter parsing skips these
	// instead of rejecting them, so the endpoint keeps typo-protection for
	// real fields without falling back to LenientFilters (which disables it
	// entirely). Reserved list controls are always allowed and need not be
	// listed here.
	AllowedFilterParams []string
	// Renames declares column renames (old name → new name) so the schema
	// diff emits a non-destructive ALTER TABLE … RENAME COLUMN instead of a
	// data-losing DROP of the old column + ADD of the new one. Rename is
	// otherwise indistinguishable from drop+add, so it requires this explicit
	// declaration; auto-detection is unsafe. A rename only fires when the old
	// column is present in the live schema and the new name is declared on the
	// entity. Declare it in Go or under an entity's `renames:` key in a
	// blueprint.
	Renames map[string]string
}

type EntityDeclaration struct {
	Name         string                 `json:"name"`
	Table        string                 `json:"table,omitempty"`
	Fields       []FieldDeclaration     `json:"fields"`
	Relations    []Relation             `json:"relations,omitempty"`
	Endpoints    []Endpoint             `json:"endpoints,omitempty"`
	Scope        *ScopeDeclaration      `json:"scope,omitempty"`
	Pagination   *PaginationDeclaration `json:"pagination,omitempty"`
	Exposure     *ExposureDeclaration   `json:"exposure,omitempty"`
	SearchFields []string               `json:"search_fields,omitempty"`
	Timestamps   *bool                  `json:"timestamps,omitempty"`
	Indices      []Index                `json:"indices,omitempty"`
	Properties   map[string]any         `json:"properties,omitempty"`
	Renames      map[string]string      `json:"renames,omitempty"`
}

type ExposureConfig struct {
	CRUD   *bool         // nil or true generates CRUD routes
	MCP    bool          // register MCP CRUD tools
	Public bool          // allow anonymous CRUD when no scope or access rule applies
	Access AccessControl // per-operation permissions
}

type ExposureDeclaration struct {
	CRUD   *bool              `json:"crud,omitempty"`
	MCP    bool               `json:"mcp,omitempty"`
	Public bool               `json:"public,omitempty"`
	Access *AccessDeclaration `json:"access,omitempty"`
}

type FieldDeclaration struct {
	Name         string   `json:"name"`
	Type         string   `json:"type"`
	Required     bool     `json:"required,omitempty"`
	Unique       bool     `json:"unique,omitempty"`
	Default      any      `json:"default,omitempty"`
	AutoGenerate string   `json:"auto_generate,omitempty"`
	ReadOnly     bool     `json:"read_only,omitempty"`
	Hidden       bool     `json:"hidden,omitempty"`
	NoQuery      bool     `json:"no_query,omitempty"`
	Max          *float64 `json:"max,omitempty"`
	Min          *float64 `json:"min,omitempty"`
	Pattern      string   `json:"pattern,omitempty"`
	Values       []string `json:"values,omitempty"`
	To           string   `json:"to,omitempty"`
	Many         bool     `json:"many,omitempty"`
}

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

type Index struct {
	Name       string   `json:"name,omitempty"`
	Columns    []string `json:"columns,omitempty"`
	Unique     bool     `json:"unique,omitempty"`
	Expression string   `json:"expression,omitempty"`
}

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

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

type PaginationConfig struct {
	CursorField  string
	CursorFields []string
	MaxListLimit int
}

type PaginationDeclaration struct {
	CursorField  string   `json:"cursor_field,omitempty"`
	CursorFields []string `json:"cursor_fields,omitempty"`
	MaxListLimit int      `json:"max_list_limit,omitempty"`
}

type Registry interface {
	// All returns a snapshot of every registered entity keyed by name.
	// Map iteration order is randomised by Go; for stable iteration use
	// AllSorted().
	All() map[string]*Entity

	// AllSorted returns every registered entity in alphabetical order
	// by name. Use this when emitting bytes whose ordering matters
	// (OpenAPI, generated code, golden-file tests, ETag-cached
	// responses).
	AllSorted() []*Entity

	// Get retrieves one entity by name, or an error when no such entity
	// is registered. When multiple versions of the name exist and none is
	// unversioned, Get returns an ambiguity error.
	//
	// Get is NOT safe for resolving a relation target: it prefers the
	// unversioned entity, so a v1 relation would resolve an unversioned
	// declaration with different Hidden columns and different scopes. Use
	// ResolveTarget for anything that drives visibility or scoping.
	Get(name string) (*Entity, error)
}

type Relation struct {
	Type             RelationType `json:"type"`
	Name             string       `json:"name"`                // logical name for this relation (e.g. "author", "comments")
	Entity           string       `json:"entity"`              // target entity/table name
	ForeignKey       string       `json:"foreign_key"`         // FK column name
	Through          string       `json:"through,omitempty"`   // pivot table name (ManyToMany only)
	LocalKey         string       `json:"local_key,omitempty"` // column on the local side of a ManyToMany pivot
	ForeignKeyTarget string       `json:"foreign_key_target,omitempty"`
}

type RelationType int

type ScopeConfig struct {
	SoftDelete     bool   // add deleted_at and hide deleted rows by default
	MultiTenant    bool   // scope rows to the tenant in the request context
	TenantField    string // tenant column; empty uses tenant_id
	OwnerField     string // owner column stamped and scoped by auto-CRUD
	CrossOwnerRead string // permission that lifts owner scoping for reads only
}

type ScopeDeclaration struct {
	SoftDelete     bool   `json:"soft_delete,omitempty"`
	MultiTenant    bool   `json:"multi_tenant,omitempty"`
	TenantField    string `json:"tenant_field,omitempty"`
	OwnerField     string `json:"owner_field,omitempty"`
	CrossOwnerRead string `json:"cross_owner_read,omitempty"`
}

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

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

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

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

type ValidatorFunc func(ctx context.Context, data map[string]any) map[string]string

type VersionedRegistry interface {
	// GetVersioned retrieves the entity registered under name at exactly
	// version (the route-group prefix it was mounted at; "" for the
	// unversioned App.Entity registration).
	GetVersioned(name, version string) (*Entity, error)
}