internal

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

type AttributeOrder struct {
	AttrID          int16
	ValueType       forma.ValueType
	SortOrder       forma.SortOrder
	StorageLocation forma.AttributeStorageLocation // main or eav
	ColumnName      string                         // main table column name if StorageLocation == main
}

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

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

type DBPool interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}

type DataSourcePlan struct {
	// Tier indicates the logical data tier (hot/warm/cold).
	Tier DataTier

	// Engine indicates the execution engine, e.g., "postgres" or "duckdb".
	Engine string

	// SQL optionally contains the generated SQL fragment or rendered template used.
	// For privacy/performance reasons this may be truncated by the repository.
	SQL string

	// RowEstimate is the planner's estimated rows to be scanned/returned (if available).
	RowEstimate int64

	// PredicatePushdown indicates whether predicates were pushed to the source.
	PredicatePushdown bool

	// ActualRows contains the actual rows returned from this source (filled post-execution).
	ActualRows int64

	// DurationMs measures execution time for this source in milliseconds.
	DurationMs int64

	// Reason provides human-readable explanation for selection/behavior.
	Reason string
}

type DataTier string

type DualClauses struct {
	PgClause     string // existing EAV-based clause (EXISTS...)
	PgArgs       []any
	PgMainClause string // predicates that can be pushed into entity_main (m.*)
	PgMainArgs   []any

	DuckClause string
	DuckArgs   []any
}

type DuckDBClient struct {
	DB *sql.DB
	// contains filtered or unexported fields
}

type DuckDBRenderHints struct {
	// S3ParquetPathTemplate is a template (with placeholders) for locating parquet files in S3.
	// Example: "s3://bucket/path/schema_{{.SchemaID}}/data.parquet"
	S3ParquetPathTemplate string

	// TimeEncodingHint indicates how date/time values should be encoded in DuckDB side.
	// e.g. "unix_ms" or "iso8601"
	TimeEncodingHint string
}

type EAVRecord struct {
	SchemaID     int16
	RowID        uuid.UUID // UUID v7, identifies data row
	AttrID       int16     // Attribute ID from schema definition
	ArrayIndices string    // Comma-separated array indices (e.g., "0", "1,2", or "" for non-arrays)
	ValueText    *string   // For valueType: "text"
	ValueNumeric *float64  // For valueType: "numeric"
}

type EntityAttribute struct {
	SchemaID     int16
	RowID        uuid.UUID // UUID v7, identifies data row
	AttrID       int16
	ArrayIndices string
	ValueType    forma.ValueType
	Value        any
}

type ExecutionPlan struct {
	// Routing decision snapshot (which tiers were considered/selected)
	Routing RoutingDecision

	// Per-source plans for each data source touched by the federated execution.
	Sources []DataSourcePlan

	// Merge describes the merge-on-read strategy applied to results across tiers.
	Merge MergePlan

	// Timings: coarse-grained durations in milliseconds for major stages.
	// Keys typically: "translate", "postgres_fetch", "duckdb_fetch", "merge", "total"
	Timings map[string]int64

	// Notes and warnings captured during planning/execution.
	Notes []string
}

type FederatedAttributeQuery struct {
	AttributeQuery

	// PreferredTiers is an ordered list of preferred data tiers to query.
	// Example: []DataTier{DataTierHot, DataTierWarm, DataTierCold}
	PreferredTiers []DataTier

	// PreferHot indicates strong preference for reading from the hot (Postgres) tier
	// when the same data exists in multiple tiers.
	PreferHot bool

	// UseMainAsAnchor controls whether the main table (entity_main) should be used
	// as the anchor for predicate pushdown. This mirrors existing repository logic.
	UseMainAsAnchor bool

	// DuckDBHints carries optional DuckDB-specific rendering hints, e.g. external
	// parquet path templates or casting preferences.
	DuckDBHints *DuckDBRenderHints
}

type FederatedQueryOptions struct {
	// MaxRows limits the number of rows read from remote/columnar sources per shard.
	MaxRows int

	// Parallelism controls how many parallel DuckDB scan workers to use.
	Parallelism int

	// AllowPartialDegradedMode if true will allow executing the query with only a subset
	// of data tiers available (useful for the early MVP).
	AllowPartialDegradedMode bool

	// IncludeExecutionPlan when true instructs the repository to collect an execution plan
	// for debugging/observability. If set, the repository will allocate and populate
	// ExecutionPlan and assign it to ExecutionPlan (below) so callers may inspect it.
	IncludeExecutionPlan bool

	// ExecutionPlan is populated by the repository when IncludeExecutionPlan==true.
	// Callers should pass a non-nil opts pointer and inspect this field after call.
	ExecutionPlan *ExecutionPlan
}

type ListOperatorMapping struct {
	// Operator is the DSL operator name (equals, contains, starts_with, gt, etc.)
	Operator string
	// DuckDBExpr is a template for the DuckDB expression.
	// Placeholders: {{.Column}} for the column name, {{.Value}} for the parameter.
	DuckDBExpr string
	// RequiresLambda indicates if the expression uses a lambda (x -> predicate)
	RequiresLambda bool
}

type MergePlan struct {
	// Strategy name, e.g., "last-write-wins"
	Strategy string

	// PreferHot indicates whether preferHot tiebreaker was used.
	PreferHot bool

	// DedupKeys lists the keys used for deduplication (typically SchemaID:RowID).
	DedupKeys []string

	// DurationMs time spent merging in milliseconds.
	DurationMs int64

	// Notes optional additional details about attribute-level merging.
	Notes []string
}

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

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

type PersistentRecord struct {
	SchemaID        int16
	RowID           uuid.UUID
	TextItems       map[string]string // e.g., "text_01" -> "Hello"
	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 // EAV attributes not in hot table
}

type PersistentRecordFederatedQuerier interface {
	// QueryPersistentRecordsFederated performs a federated query across configured data tiers
	// (Postgres hot and DuckDB/S3 warm/cold). Implementations MUST preserve backwards
	// compatibility for OLTP-only callers: if the federated query hints indicate hot-only
	// execution, this SHOULD delegate to QueryPersistentRecords.
	QueryPersistentRecordsFederated(ctx context.Context, tables StorageTables, fq *FederatedAttributeQuery, opts *FederatedQueryOptions) (*PersistentRecordPage, error)
}

type PersistentRecordKey struct {
	SchemaID int16
	RowID    uuid.UUID
}

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

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)
}

type PersistentRecordRepository interface {
	PersistentRecordWriter
	PersistentRecordReader
	PersistentRecordFederatedQuerier
}

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 RelationDescriptor struct {
	ChildSchema        string
	ChildPath          string
	ParentSchema       string
	ParentPath         string
	ForeignKeyAttr     string
	ParentIDAttr       string
	ForeignKeyRequired bool
}

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

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

type SQLGenerator struct{}

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

type SchemaMetadata struct {
	SchemaName    string                    `json:"schema_name"`
	SchemaID      int16                     `json:"schema_id"`
	SchemaVersion int                       `json:"schema_version"`
	Attributes    []forma.AttributeMetadata `json:"attributes"`
}

type Set[T comparable] struct {
	// contains filtered or unexported fields
}

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

type Transformer interface {
	// Single object conversion
	ToAttributes(ctx context.Context, schemaID int16, rowID uuid.UUID, jsonData any) ([]EntityAttribute, error)
	FromAttributes(ctx context.Context, attributes []EntityAttribute) (map[string]any, error)

	// Batch operations
	BatchToAttributes(ctx context.Context, schemaID int16, jsonObjects []any) ([]EntityAttribute, error)
	BatchFromAttributes(ctx context.Context, attributes []EntityAttribute) ([]map[string]any, error)

	// Validation
	ValidateAgainstSchema(ctx context.Context, jsonSchema any, jsonData any) error
}