storage

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

type AdaptedTableSpec struct {
	Entity     string      `json:"entity"`      // Entity type name
	Columns    []ColumnDef `json:"columns"`     // Ordered column definitions
	SchemaHash string      `json:"schema_hash"` // SHA-256 of canonical schema JSON
	HasExtra   bool        `json:"has_extra"`   // Whether _extra overflow column is present
	Indexes    []IndexDef  `json:"indexes"`     // Indexes to create
}

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

type AggregateQueryable interface {
	// AggregateQuery executes a pre-built aggregate SQL query and returns
	// the grouped results as maps. Unlike QueryWithPlan (which scans
	// data+_version blobs), this scans arbitrary columns/expressions
	// and returns them by alias.
	AggregateQuery(ctx context.Context, sql string, args []interface{}, aliases []string) ([]map[string]interface{}, error)

	// IsAdaptedEntity reports whether the given entity uses an adapted
	// table (column-per-field storage). The OQL planner uses this to
	// decide whether aggregate push-down is possible.
	IsAdaptedEntity(entity string) bool

	// AdaptedColumnInfo returns the SQL column name for a JSON field in
	// an adapted entity. Returns ("", false) if the entity is not adapted
	// or the field is not a known column. For decimal columns, also returns
	// the scale so the caller can denormalise aggregated values.
	AdaptedColumnInfo(entity, jsonField string) (colName string, scale int, isDecimal bool, ok bool)

	// AdaptedTableName returns the SQL table name for an adapted entity.
	// Returns ("", false) if the entity is not adapted.
	AdaptedTableName(entity string) (string, bool)

	// StorageDialectFor returns the StorageDialect for the given entity,
	// or nil if the entity is not adapted. This allows SQL generators to
	// access dialect methods without importing backend-specific types.
	StorageDialectFor(entity string) StorageDialect
}

type Batcher interface {
	BatchCreate(ctx context.Context, entity string, items []map[string]interface{}) ([]int, error)
	BatchDelete(ctx context.Context, entity string, ids []int) error
}

type ColumnChange struct {
	Name       string
	OldSQLType string
	NewSQLType string
	OldType    string
	NewType    string
}

type ColumnDef struct {
	Name      string `json:"name"`       // Column name (e.g., "age", "REF_author_entity")
	JSONField string `json:"json_field"` // Original JSON field name (e.g., "age", "author")
	Type      string `json:"type"`       // JSON Schema type: string, integer, number, boolean, array, object
	Format    string `json:"format"`     // JSON Schema format: "", "decimal", "ref", "email", etc.
	SQLType   string `json:"sql_type"`   // Backend-specific SQL type (e.g., "TEXT", "INTEGER", "REAL")
	Required  bool   `json:"required"`   // Whether the field is in the schema's required array
	Precision int    `json:"precision"`  // For decimal: total significant digits
	Scale     int    `json:"scale"`      // For decimal: digits after decimal point
	IsREF     bool   `json:"is_ref"`     // True if this column is part of a REF decomposition
}

type CommitAppend struct {
	Entity string                 `json:"entity"`
	ID     *int                   `json:"id,omitempty"`
	Data   map[string]interface{} `json:"data"`
}

type CommitAppendResult struct {
	Entity string `json:"entity"`
	ID     int    `json:"id"`
}

type CommitRequest struct {
	Update CommitUpdate   `json:"update"`
	Append []CommitAppend `json:"append"`
}

type CommitResult struct {
	Update   CommitUpdateResult   `json:"update"`
	Appended []CommitAppendResult `json:"appended"`
}

type CommitUpdate struct {
	Entity  string                 `json:"entity"`
	ID      int                    `json:"id"`
	Version *int                   `json:"version,omitempty"`
	Data    map[string]interface{} `json:"data"`
}

type CommitUpdateResult struct {
	Entity  string `json:"entity"`
	ID      int    `json:"id"`
	Created bool   `json:"created"`
	Version int    `json:"version"`
}

type EntityLister interface {
	ListEntities(ctx context.Context) ([]string, error)
}

type FieldIntrospector interface {
	// JSONType returns the JSON Schema type string:
	// "string", "integer", "number", "boolean", "array", "object"
	JSONType() string

	// Format returns the declared format ("email", "decimal", "ref", "")
	Format() string

	// EnumValues returns the declared enum values, or nil if none.
	EnumValues() []string

	// Meta returns a metadata value by key (e.g., "decimalPrecision").
	// Returns (nil, false) if the key is not set.
	Meta(key string) (interface{}, bool)
}

type FieldQueryable interface {
	// ListWithFields returns all records for an entity type, but each
	// record contains only the specified fields plus _version. Fields
	// not present in a particular record's JSON are omitted from the
	// returned map (no null padding).
	//
	// For adapted entities this falls through to the regular List path
	// (adapted tables already select native columns efficiently).
	ListWithFields(ctx context.Context, entity string, fields []string) ([]map[string]interface{}, error)

	// QueryWithFields executes a pre-built SQL query (WHERE push-down)
	// and returns results with only the specified fields extracted from
	// the data blob. Like QueryWithPlan but avoids full deserialisation.
	QueryWithFields(ctx context.Context, sqlQuery string, args []interface{}, fields []string) ([]map[string]interface{}, error)
}

type FilterableStore interface {
	FieldQueryable

	// ListWithFieldsAndFilter returns records for an entity type,
	// extracting only the specified fields and applying the predicate
	// set during tokenisation. Rows that fail the predicates are never
	// materialised as maps.
	//
	// The caller must ensure that fields includes all columns needed
	// for the SELECT list. Predicate fields may or may not overlap
	// with output fields.
	ListWithFieldsAndFilter(ctx context.Context, entity string, fields []string, preds *jsonic.PredicateSet) ([]map[string]interface{}, error)
}

type GraphEdge struct {
	SourceEntity string
	SourceID     int
	TargetEntity string
	TargetID     int
	Relationship string
}

type GraphEdgeScanner interface {
	ScanGraphEdges(ctx context.Context, tenantID uint16, fn func(GraphEdge) error) error
}

type GraphIntegrity interface {
	VerifyGraphIntegrity(ctx context.Context) error
	RebuildGraph(ctx context.Context) error
}

type GraphNeighbors interface {
}

type IDGenerator interface {
	NextID(ctx context.Context, entity string) (int, error)
}

type IndexDef struct {
	Name    string   `json:"name"`    // Index name
	Columns []string `json:"columns"` // Column names
	Unique  bool     `json:"unique"`  // Whether the index is unique
}

type InfoProvider interface {
	Info() StoreInfo
}

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

type Migrator interface {
	Migrate(ctx context.Context) error
	Version(ctx context.Context) (int, error)
}

type PagedLister interface {
	// ListPaged returns a single page of entities, plus the total count.
	// limit and offset are applied at the storage layer (SQL LIMIT/OFFSET).
	ListPaged(ctx context.Context, entity string, limit, offset int) (*PagedResult, error)
}

type PagedResult struct {
	Data       []map[string]interface{}
	TotalItems int
}

type QueryCapabilities struct {
	Where   bool // Can filter with json_extract predicates
	OrderBy bool // Can sort by json_extract fields
	Limit   bool // Can apply TOP/LIMIT
	Count   bool // Can return entity count without full scan
}

type Queryable interface {
	// Capabilities reports which query operations this backend handles
	// natively. The planner will not attempt to push down an operation
	// unless the corresponding capability is true.
	Capabilities() QueryCapabilities

	// CountEntities returns the number of records for an entity type
	// without fetching the records themselves. Used by the planner to
	// determine whether push-down is worthwhile (the fixed overhead of
	// a push-down query exceeds Go-side cost for small datasets).
	CountEntities(ctx context.Context, entity string) (int, error)

	// QueryWithPlan executes a pre-built SQL query with parameterised
	// arguments and returns the results as maps, in the same format as
	// List(). The SQL is generated by the OQL planner's SQL generator
	// and always selects from the data column with json_extract().
	QueryWithPlan(ctx context.Context, sql string, args []interface{}) ([]map[string]interface{}, error)
}

type SQLiteConfig struct {
	DBPath            string
	EnableWAL         bool // Write-Ahead Logging for better concurrency
	EnableForeignKeys bool
	CacheSize         int    // Page cache size in KB
	BusyTimeout       int    // Milliseconds to wait on locked database
	FullTextEnabled   bool   // Enable FTS5 full-text search indexing
	GraphEnabled      bool   // Enable graph edge table maintenance
	TenantID          uint16 // 0 = no tenant scoping

	// Performance tuning (zero = use backend defaults)
	//   SQLite defaults: MaxOpenConns=1 (WAL single-writer),
	//   MaxIdleConns=1, ReadPoolSize=NumCPU.
	MaxOpenConns        int // Max open write connections (0 = backend default)
	MaxIdleConns        int // Max idle write connections (0 = backend default)
	ReadPoolSize        int // Max open read connections (0 = backend default)
	ContentionThreshold int // Adaptive lock threshold 0-100 (default 95)
}

type SQLiteStorageDialect struct{}

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

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

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

type SchemaDiff struct {
	Added   []ColumnDef    // Columns in new but not in old
	Dropped []ColumnDef    // Columns in old but not in new
	Changed []ColumnChange // Columns present in both but with incompatible type changes

	IndexesAdded   []IndexDef // Indexes in new but not in old
	IndexesDropped []IndexDef // Indexes in old but not in new

	HasExtraChanged bool // Whether _extra presence changed
	NewHasExtra     bool // The new HasExtra value (only meaningful if HasExtraChanged)
}

type SchemaIntrospector interface {
	// FieldNames returns all declared field names, sorted alphabetically.
	FieldNames() []string

	// GetField returns the field descriptor for a named field.
	// Returns nil if the field does not exist.
	GetField(name string) FieldIntrospector

	// IsRequired reports whether a field is required.
	IsRequired(name string) bool

	// AllowsAdditional reports whether the schema accepts fields not
	// declared in its field list. Returns true if additionalProperties
	// is absent or true; false if explicitly set to false.
	AllowsAdditional() bool
}

type Searcher interface {
	Search(ctx context.Context, entity string, field string, query string, matchType string) ([]map[string]interface{}, error)
}

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

type StorageDialect interface {
	// Name returns the dialect identifier ("sqlite", "postgres", etc.).
	Name() string

	// Placeholder returns a parameter placeholder for the n-th argument
	// (1-based). SQLite: "?", PostgreSQL: "$1", "$2", etc.
	Placeholder(n int) string

	// ColumnType maps a JSON Schema type + format to the backend's native
	// SQL column type. Examples:
	//   ("string", "")        → "TEXT"
	//   ("integer", "")       → "INTEGER" (SQLite) / "BIGINT" (PostgreSQL)
	//   ("number", "")        → "REAL" (SQLite) / "DOUBLE PRECISION" (PostgreSQL)
	//   ("number", "decimal") → "TEXT" (SQLite) / "NUMERIC(p,s)" (PostgreSQL)
	//   ("boolean", "")       → "INTEGER" (SQLite) / "BOOLEAN" (PostgreSQL)
	//   ("array", "")         → "TEXT" (SQLite) / "JSONB" (PostgreSQL)
	//   ("object", "")        → "TEXT" (SQLite) / "JSONB" (PostgreSQL)
	//
	// For decimals, precision and scale are provided for backends that
	// support native fixed-point (PostgreSQL NUMERIC). Backends that store
	// decimals as text (SQLite) may ignore them.
	ColumnType(jsonType, format string, precision, scale int) string

	// CreateTableSQL generates the CREATE TABLE statement for an adapted
	// table. Implementations must include system columns (id, tenant_id,
	// _extra if hasExtra, _version, created_at, updated_at) and the
	// primary key.
	CreateTableSQL(spec *AdaptedTableSpec) string

	// CreateIndexSQL generates CREATE INDEX statements for the adapted
	// table's indexes.
	CreateIndexSQL(spec *AdaptedTableSpec) []string

	// InsertSQL generates an INSERT statement with the appropriate
	// placeholders. Returns the SQL string and the expected argument
	// order (column names). The caller provides the actual values.
	InsertSQL(spec *AdaptedTableSpec, hasExtra bool) (sql string, columns []string)

	// SelectSQL generates a SELECT statement for a single row by
	// tenant_id and id.
	SelectSQL(spec *AdaptedTableSpec) string

	// SelectAllSQL generates a SELECT statement for all rows in a tenant,
	// ordered by id.
	SelectAllSQL(spec *AdaptedTableSpec) string

	// UpdateSQL generates an UPDATE statement with the appropriate
	// placeholders. The versionCheck parameter controls whether a
	// _version = ? clause is appended to the WHERE.
	UpdateSQL(spec *AdaptedTableSpec, versionCheck bool) string

	// DeleteSQL generates a DELETE statement for a single row.
	DeleteSQL(spec *AdaptedTableSpec) string

	// ExistsSQL generates an EXISTS check for a single row.
	ExistsSQL(spec *AdaptedTableSpec) string

	// MetadataTableSQL generates the DDL for the adapted_table_schemas
	// metadata table.
	MetadataTableSQL() string

	// NormaliseDecimal transforms a validated decimal string into the
	// storage representation for this backend. SQLite scales to int64.
	// PostgreSQL returns the value unchanged.
	NormaliseDecimal(value string, precision, scale int) (string, error)

	// DenormaliseDecimal transforms the stored representation back to
	// a client-facing string. SQLite divides by 10^scale and formats.
	// PostgreSQL returns the value unchanged.
	DenormaliseDecimal(value string, precision, scale int) string

	// SupportsNativeDecimalAggregation reports whether the backend
	// handles SUM/AVG on decimal columns with exact arithmetic.
	// If false, OQL aggregates in Go using shopspring/decimal.
	SupportsNativeDecimalAggregation() bool
}

type Store interface {
	// Config returns the store's configuration.
	Config() StoreConfig

	// Entity CRUD operations
	Create(ctx context.Context, entity string, data map[string]interface{}) (int, error)
	Get(ctx context.Context, entity string, id int) (map[string]interface{}, error)
	Update(ctx context.Context, entity string, id int, data map[string]interface{}) error
	Patch(ctx context.Context, entity string, id int, data map[string]interface{}) error
	// PatchValidated is like Patch but runs a validation function against the
	// merged data inside the transaction. If the validator returns an error,
	// the transaction is rolled back and the error is returned to the caller.
	// This avoids TOCTOU races where a Get-merge-Update sequence can observe
	// stale data between the Get and the Update.
	PatchValidated(ctx context.Context, entity string, id int, data map[string]interface{}, validate func(merged map[string]interface{}) error) error
	Delete(ctx context.Context, entity string, id int) error
	// Save upserts an entity with the caller-specified ID: creates it if it
	// does not exist, overwrites it if it does. Returns (true, nil) when a
	// new record was created and (false, nil) when an existing record was
	// replaced. Never returns an error solely because the ID already exists.
	Save(ctx context.Context, entity string, id int, data map[string]interface{}) (bool, error)

	// Commit performs an atomic upsert + one or more inserts in a single
	// storage transaction. The upsert (req.Update) supports optional
	// optimistic concurrency via Version. Each entry in req.Append is an
	// unconditional insert; a duplicate explicit ID returns ErrAlreadyExists
	// and rolls back the entire commit. Returns ErrConflict when the Update
	// version check fails.
	Commit(ctx context.Context, req CommitRequest) (CommitResult, error)

	// Query operations
	List(ctx context.Context, entity string) ([]map[string]interface{}, error)
	Exists(ctx context.Context, entity string, id int) bool
	Search(ctx context.Context, entity string, field string, query string, matchType string) ([]map[string]interface{}, error)

	// Full-text search (optional - may return empty if not supported)
	FullTextSearch(ctx context.Context, query string, entity string) ([]map[string]interface{}, error)

	// Ping verifies that the storage backend is reachable. Returns nil on
	// success. Used by health and readiness probes.
	Ping(ctx context.Context) error

	// Lifecycle
	Close() error
}

type StoreConfig struct {
	Type            string // "sqlite", "jsonfile"
	DBPath          string // SQLite database file path
	BaseDir         string // JSONFile base directory
	Schema          string // JSONFile schema subdirectory
	FullTextEnabled bool   // controls FTS indexing in backend
	GraphEnabled    bool   // controls graph edge table maintenance
	TenantID        uint16 // 0 = no tenant scoping

	// Performance tuning (SQLite-specific; zero = use defaults)
	SQLiteCacheSize           int // Page cache size in KB
	SQLiteBusyTimeout         int // Milliseconds to wait on locked database
	SQLiteMaxOpenConns        int // Max open database connections
	SQLiteMaxIdleConns        int // Max idle database connections
	SQLiteReadPoolSize        int // Max open read connections (0 = auto)
	SQLiteContentionThreshold int // Adaptive lock threshold 0-100
}

type StoreFactory func(config map[string]interface{}) (Store, error)

type StoreInfo struct {
	Type                string // "jsonfile", "sqlite", "postgres", etc.
	Version             string
	SupportsSearch      bool
	SupportsBatch       bool
	SupportsTransaction bool
}

type TenantIDLister interface {
	GraphTenantIDs(ctx context.Context) ([]uint16, error)
}