blob

type Blob struct {
	// ID is the unique identifier for this blob.
	ID string `json:"id"`

	// LSHBucket is the LSH hash bucket this vector belongs to.
	// This is visible to storage (enables bucket-based retrieval).
	LSHBucket string `json:"lsh_bucket"`

	// Ciphertext is the encrypted vector data.
	// Format: nonce (12 bytes) || ciphertext || tag (16 bytes)
	Ciphertext []byte `json:"ciphertext"`

	// MetadataCiphertext is optional encrypted metadata.
	// Can store additional info like document title, source, etc.
	MetadataCiphertext []byte `json:"metadata_ciphertext,omitempty"`

	// Dimension is the vector dimension (visible, needed for decryption).
	Dimension int `json:"dimension"`

	// CreatedAt is when this blob was created.
	CreatedAt time.Time `json:"created_at"`

	// Version for future schema changes.
	Version int `json:"version"`
}

type BucketInfo struct {
	// Bucket is the LSH bucket identifier.
	Bucket string `json:"bucket"`

	// Count is the number of blobs in this bucket.
	Count int `json:"count"`

	// TotalSize is the total size of all blobs in bytes.
	TotalSize int64 `json:"total_size"`
}

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

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

type ReadOnlyStore interface {
	Get(ctx context.Context, id string) (*Blob, error)
	GetBatch(ctx context.Context, ids []string) ([]*Blob, error)
	GetBucket(ctx context.Context, bucket string) ([]*Blob, error)
	GetBuckets(ctx context.Context, buckets []string) ([]*Blob, error)
	GetSuperBuckets(ctx context.Context, superBucketIDs []int) ([]*Blob, error)
	ListBuckets(ctx context.Context) ([]string, error)
	Stats(ctx context.Context) (*StoreStats, error)
}

type Store interface {
	// Put stores a blob. Returns ErrBlobExists if ID already exists.
	Put(ctx context.Context, blob *Blob) error

	// PutBatch stores multiple blobs atomically.
	PutBatch(ctx context.Context, blobs []*Blob) error

	// Get retrieves a blob by ID. Returns ErrBlobNotFound if not found.
	Get(ctx context.Context, id string) (*Blob, error)

	// GetBatch retrieves multiple blobs by ID.
	// Returns nil for IDs that don't exist.
	GetBatch(ctx context.Context, ids []string) ([]*Blob, error)

	// GetBucket retrieves all blobs in a bucket.
	// Returns empty slice if bucket doesn't exist.
	GetBucket(ctx context.Context, bucket string) ([]*Blob, error)

	// GetBuckets retrieves blobs from multiple buckets.
	GetBuckets(ctx context.Context, buckets []string) ([]*Blob, error)

	// GetSuperBuckets retrieves all blobs from the specified super-bucket IDs.
	// Super-bucket keys are formatted as "XX" (2-digit zero-padded).
	// This is the primary method for fetching vectors after removing sub-buckets.
	GetSuperBuckets(ctx context.Context, superBucketIDs []int) ([]*Blob, error)

	// Delete removes a blob by ID. No error if blob doesn't exist.
	Delete(ctx context.Context, id string) error

	// DeleteBatch removes multiple blobs by ID.
	DeleteBatch(ctx context.Context, ids []string) error

	// ListBuckets returns all bucket identifiers.
	ListBuckets(ctx context.Context) ([]string, error)

	// BucketInfo returns information about a specific bucket.
	BucketInfo(ctx context.Context, bucket string) (*BucketInfo, error)

	// Stats returns overall store statistics.
	Stats(ctx context.Context) (*StoreStats, error)

	// Close closes the store connection.
	Close() error
}

type StoreStats struct {
	// TotalBlobs is the total number of blobs.
	TotalBlobs int64 `json:"total_blobs"`

	// TotalBuckets is the number of unique buckets.
	TotalBuckets int64 `json:"total_buckets"`

	// TotalSize is the total storage size in bytes.
	TotalSize int64 `json:"total_size"`

	// AvgBlobsPerBucket is the average number of blobs per bucket.
	AvgBlobsPerBucket float64 `json:"avg_blobs_per_bucket"`
}