entity

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

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:"-"`
}

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

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
	SoftDelete   bool           // enable soft-delete (deleted_at column)
	MultiTenant  bool           // scope queries by the tenant column (see TenantField)
	TenantField  string         // tenant-scoping column name when MultiTenant; defaults to "tenant_id"
	Timestamps   bool           // add created_at / updated_at columns
	CRUD         *bool          // auto-generate CRUD routes. nil=auto(true when DB set), &true=always, &false=never
	MCP          bool           // auto-generate MCP tools
	CursorField  string         // optional: single-field keyset cursor; defaults to PrimaryKey
	CursorFields []string       // optional: composite cursor — ORDER BY each field in order with tuple-compared keyset. Wins over CursorField when non-empty.
	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   map[string]any // caller-owned metadata for generators, plugins, and app conventions
	MaxListLimit int            // opt-in cap for ?limit and the streaming list path. 0 = use default (100); negative = no streaming cap above default.

	// OwnerField names the DB column that holds the row's owner id (e.g.
	// "user_id"). When set AND an owner extractor is registered (typically
	// by battery/auth), auto-CRUD scopes List/Get/Update/Delete by the
	// current request's owner and auto-stamps Create. Leave empty to keep
	// pre-existing behaviour.
	OwnerField string

	// Access declares the RBAC permission required for each CRUD operation.
	// A blank permission leaves that operation un-gated by RBAC (owner and
	// tenant scoping still apply). When set, auto-CRUD refuses a request
	// whose context lacks the permission with 403. Roles + policy must be
	// present in the request context — wire them once with access.Middleware
	// (or battery/auth). See framework/docs/content/access-control.md.
	Access AccessControl

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

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"`
	SoftDelete  bool               `json:"soft_delete,omitempty"`
	MultiTenant bool               `json:"multi_tenant,omitempty"`
	// OwnerField names the DB column that holds the row's owner id
	// (e.g. "user_id"). When set AND an owner extractor is registered
	// by a battery, auto-CRUD scopes List/Get/Update/Delete by the
	// current request's owner and auto-stamps Create. Mirrors
	// EntityConfig.OwnerField; leave empty to keep pre-existing behaviour.
	OwnerField   string         `json:"owner_field,omitempty"`
	Timestamps   *bool          `json:"timestamps,omitempty"`
	CRUD         *bool          `json:"crud,omitempty"`
	MCP          bool           `json:"mcp,omitempty"`
	CursorField  string         `json:"cursor_field,omitempty"`
	CursorFields []string       `json:"cursor_fields,omitempty"`
	Indices      []Index        `json:"indices,omitempty"`
	Properties   map[string]any `json:"properties,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"`
	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 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.
	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 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