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
	AttrName        string                         // logical attribute name (used for EAV column alias in unified CTE)
}

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 ConsistencyMode string

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 preference for routing queries to the hot (Postgres) tier.
	// When true, routing logic prefers direct Postgres execution over federated DuckDB
	// queries when both paths are available. This is a routing hint, not a merge semantic.
	// Merge conflict resolution always uses deterministic tier priority (Hot > Warm > Cold).
	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

	// KeysetCursor enables keyset-based pagination as an alternative to offset.
	// When non-nil, the repository generates keyset WHERE clauses instead of (or
	// in addition to) LIMIT/OFFSET. The cursor carries the last-seen row's sort
	// column values and the pagination direction (after/before).
	KeysetCursor *KeysetCursor
}

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

	// KeysetEnabled makes the repository prefer the keyset execution path over offset-based
	// pagination when a KeysetCursor is supplied on the query.
	KeysetEnabled 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

	// ConsistencyMode controls the freshness/availability contract.
	// Defaults to "strict" when empty.
	ConsistencyMode ConsistencyMode
}

type KeysetColumn struct {
	// Attribute is the attribute name (e.g. "trade_time", "row_id").
	Attribute string
	// Direction is the sort direction for this column.
	Direction forma.SortOrder
}

type KeysetCursor struct {
	// Columns defines the column order of the cursor values. This should match
	// the query's sort order plus a row_id tiebreaker.
	Columns []KeysetColumn
	// Values are the last-row column values, in the same order as Columns.
	Values []interface{}
	// Mode indicates whether to fetch rows after or before the cursor.
	Mode KeysetCursorMode
}

type KeysetCursorMode string

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., MergeStrategyLastWriteWins.
	Strategy MergeStrategy

	// 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 MergeStrategy 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
	ExecutionPlan *ExecutionPlan
}

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 SchemaProjection struct {
	// S3SourceSelect is the SELECT projection for the s3_source CTE:
	//   row_id, created_at, ver_ts, deleted_ts, attr_col_1, attr_col_2, ...
	S3SourceSelect string

	// PGSourceSelect is the SELECT projection for the pg_source CTE, including
	// COALESCE expressions for entity_main columns and EAV pivot expressions.
	PGSourceSelect string

	// PGGroupBy is the GROUP BY clause for the pg_source CTE.
	PGGroupBy string

	// EAVPivotSelect is the EAV subquery SELECT for the pg_source LEFT JOIN,
	// containing MAX(CASE WHEN attr_id = X THEN value_Y END) AS attr_name lines.
	EAVPivotSelect string

	// EAVPivotAttrs is the comma-separated list of attr_ids for the EAV pivot WHERE.
	EAVPivotAttrs string

	// OuterSelect is the final outer SELECT that maps unified columns back to
	// entity_main column descriptors.
	OuterSelect string

	// UnifiedColumnNames lists the canonical column names produced by both
	// s3_source and pg_source (in order).
	UnifiedColumnNames []string

	// UnifiedColumnTypes maps column name to DuckDB type for CAST expressions.
	UnifiedColumnTypes map[string]forma.ValueType

	// AttrToMainColumn maps attribute name to entity_main column name.
	AttrToMainColumn map[string]string

	// EAVAttrs lists attribute names that are EAV-only (no column binding).
	EAVAttrs []string

	// EAVAttrsJSON is the JSON object expression for EAV attributes in the
	// outer SELECT, e.g. json_object('attr_id', '8', 'value', exchange, ...).
	EAVAttrsJSONSelect string

	// HasEAVAttrs is true if the schema has any EAV-only attributes.
	HasEAVAttrs bool
	// contains filtered or unexported fields
}

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
}