model

type AtomicBatchPersistentRecordRepository interface {
	BatchInsertPersistentRecords(ctx context.Context, tables StorageTables, records []*PersistentRecord) error
	BatchUpdatePersistentRecords(ctx context.Context, tables StorageTables, records []*PersistentRecord) error
	BatchDeletePersistentRecords(ctx context.Context, tables StorageTables, keys []PersistentRecordKey) error
}

type AttributeOrder struct {
	AttrID          int16
	ValueType       forma.ValueType
	SortOrder       forma.SortOrder
	StorageLocation forma.AttributeStorageLocation
	ColumnName      string
	AttrName        string
}

type AttributeQuery struct {
	SchemaID        int16            `json:"schemaId"`
	Condition       forma.Condition  `json:"condition,omitempty"`
	OrderBy         []forma.OrderBy  `json:"orderBy"`
	AttributeOrders []AttributeOrder `json:"attributeOrders"`
	Limit           int              `json:"limit"`
	Offset          int              `json:"offset"`
}

type ColumnDescriptor struct {
	Name string
	Kind ColumnKind
}

type ColumnKind int

type ConsistencyMode string

type DataSourcePlan struct {
	Tier   DataTier
	Engine string
	SQL    string
	// Params holds the string forms of the bind parameters for SQL, in
	// order. Populated only when FederatedQueryOptions.IncludeExecutionPlan
	// is set, so diagnostic artifacts can replay the exact query (#173).
	Params            []string
	RowEstimate       int64
	PredicatePushdown bool
	ActualRows        int64
	DurationMs        int64
	Reason            string
}

type DataTier string

type DuckDBRenderHints struct {
	S3ParquetPathTemplate string
	TimeEncodingHint      string
}

type EAVRecord struct {
	SchemaID     int16
	RowID        uuid.UUID
	AttrID       int16
	ArrayIndices string
	ValueText    *string
	ValueNumeric *float64
	// ValueInt64 is an exact int64 sidecar for bigint and epoch-ms date
	// values. It is in-memory only: eav_data persistence and the EAV read
	// paths keep the float64 ValueNumeric contract (2^53 ceiling), while
	// main-column routing (storeInMainColumn) and read-back prefer
	// ValueInt64 so column-bound bigint/unix_ms values carry the full
	// int64 range without a float64 hop (#205).
	ValueInt64 *int64
}

type EntityAttribute struct {
	SchemaID     int16
	RowID        uuid.UUID
	AttrID       int16
	ArrayIndices string
	ValueType    forma.ValueType
	Value        any
}

type ExecutionPlan struct {
	Routing RoutingDecision
	Sources []DataSourcePlan
	Merge   MergePlan
	Timings map[string]int64
	Notes   []string
}

type FederatedAttributeQuery struct {
	AttributeQuery
	PreferredTiers  []DataTier
	PreferHot       bool
	UseMainAsAnchor bool
	DuckDBHints     *DuckDBRenderHints
	KeysetCursor    *KeysetCursor
}

type FederatedQueryEngine interface {
	Query(ctx context.Context, tables StorageTables, fq *FederatedAttributeQuery, opts *FederatedQueryOptions) (*PersistentRecordPage, error)
}

type FederatedQueryOptions struct {
	MaxRows                  int
	Parallelism              int
	AllowPartialDegradedMode bool
	KeysetEnabled            bool
	IncludeExecutionPlan     bool
	ExecutionPlan            *ExecutionPlan
	ConsistencyMode          ConsistencyMode
	// PartialScan is an engine out-parameter like ExecutionPlan, but NOT
	// gated on IncludeExecutionPlan: the #348 public partial marker must
	// reach callers that never asked for a plan. The last executed DuckDB
	// pass overwrites it, so it describes the pass that produced the page,
	// and Query resets it at entry, so after any call — including a
	// postgres-only answer that never runs a pass — it describes that call
	// even when one options value is reused across queries.
	// Being an out-parameter, it has nowhere to land when the caller passes
	// nil options: such a call drops the marker, so a caller that needs it
	// must pass a non-nil *FederatedQueryOptions.
	PartialScan *PartialScan
}

type KeysetColumn struct {
	Attribute string
	Direction forma.SortOrder
}

type KeysetCursor struct {
	Columns []KeysetColumn
	Values  []interface{}
	Mode    KeysetCursorMode
}

type KeysetCursorMode string

type MergePlan struct {
	Strategy   MergeStrategy
	PreferHot  bool
	DedupKeys  []string
	DurationMs int64
	Notes      []string
}

type MergeStrategy string

type PartialScan struct {
	ExcludedObjects []string
}

type PersistentRecord struct {
	SchemaID        int16
	RowID           uuid.UUID
	TextItems       map[string]string
	Int16Items      map[string]int16
	Int32Items      map[string]int32
	Int64Items      map[string]int64
	Float64Items    map[string]float64
	UUIDItems       map[string]uuid.UUID
	CreatedAt       int64
	UpdatedAt       int64
	DeletedAt       *int64
	OtherAttributes []EAVRecord
}

type PersistentRecordKey struct {
	SchemaID int16
	RowID    uuid.UUID
}

type PersistentRecordPage struct {
	Records       []*PersistentRecord
	TotalRecords  int64
	TotalPages    int
	CurrentPage   int
	ExecutionPlan *ExecutionPlan
	Partial       *PartialScan
}

type PersistentRecordQuery struct {
	Tables          StorageTables
	SchemaID        int16
	Condition       forma.Condition
	AttributeOrders []AttributeOrder
	Limit           int
	Offset          int
}

type PersistentRecordReader interface {
	GetPersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) (*PersistentRecord, error)
	QueryPersistentRecords(ctx context.Context, query *PersistentRecordQuery) (*PersistentRecordPage, error)
	// QueryPersistentRecordsByAttrValues fetches full records whose attribute
	// equals any of the given values via one set-based lookup (#268). It exists
	// for internal batch lookups (relation enrichment); it must never expand to
	// an OR-of-N condition per value.
	QueryPersistentRecordsByAttrValues(ctx context.Context, tables StorageTables, schemaID int16, attr string, values []string, limit int) (*PersistentRecordPage, error)
}

type PersistentRecordRepository interface {
	PersistentRecordWriter
	PersistentRecordReader
}

type PersistentRecordTransformer interface {
	ToPersistentRecord(ctx context.Context, schemaID int16, rowID uuid.UUID, jsonData any) (*PersistentRecord, error)
	FromPersistentRecord(ctx context.Context, record *PersistentRecord) (map[string]any, error)
}

type PersistentRecordWriter interface {
	InsertPersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
	UpdatePersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
	DeletePersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) error
}

type RoutingDecision struct {
	Tiers           []DataTier
	UseDuckDB       bool
	Reason          string
	MaxScanRows     int
	QueryTimeout    time.Duration
	AllowS3Fallback bool
}

type StorageTables struct {
	EntityMain     string
	EAVData        string
	ChangeLog      string
	SchemaRegistry string
}