datamanager

type BatchWriteResult struct {
	Results   []WriteResult // Individual write results
	Succeeded int           // Number of successful writes
	Failed    int           // Number of failed writes
	Duration  time.Duration // Total operation duration
}

type BucketConfig struct {
	Name     string        `default:"ENTITY_STATES"`
	TTL      time.Duration `default:"0s"` // 0 = no expiry
	History  int           `default:"5"`
	Replicas int           `default:"3"`
}

type BufferConfig struct {
	// Buffer capacity
	Capacity int `json:"capacity,omitempty" default:"10000"`

	// Batching settings - groups writes for efficient processing
	BatchingEnabled bool          `json:"batching_enabled" default:"true"`
	FlushInterval   time.Duration `json:"flush_interval,omitempty" default:"50ms"` // How often to flush the buffer
	MaxBatchSize    int           `json:"max_batch_size,omitempty" default:"100"`  // Max writes per batch
	MaxBatchAge     time.Duration `json:"max_batch_age,omitempty" default:"100ms"` // Max age before forced flush

	// Overflow policy when buffer is full
	// "drop_oldest" (default) - drop oldest items to make room (NATS MaxAckPending provides backpressure)
	// "drop_newest" - drop incoming items when full
	// "block" - wait for space (WARNING: can cause IndexManager deadlock, use only with careful tuning)
	OverflowPolicy string `json:"overflow_policy,omitempty" default:"drop_oldest"` // drop_oldest, drop_newest, block
}

type CacheConfig struct {
	// L1 Cache (Hot - LRU)
	L1Hot L1CacheConfig

	// L2 Cache (Warm - TTL)
	L2Warm L2CacheConfig

	// Metrics configuration
	Metrics   bool   `default:"true"`
	Component string `default:"data_manager"`
}

type CacheStats struct {
	// L1 Stats
	L1Hits      int64   `json:"l1_hits"`
	L1Misses    int64   `json:"l1_misses"`
	L1Size      int     `json:"l1_size"`
	L1HitRatio  float64 `json:"l1_hit_ratio"`
	L1Evictions int64   `json:"l1_evictions"`

	// L2 Stats
	L2Hits      int64   `json:"l2_hits"`
	L2Misses    int64   `json:"l2_misses"`
	L2Size      int     `json:"l2_size"`
	L2HitRatio  float64 `json:"l2_hit_ratio"`
	L2Evictions int64   `json:"l2_evictions"`

	// Overall Stats
	TotalHits       int64   `json:"total_hits"`
	TotalMisses     int64   `json:"total_misses"`
	OverallHitRatio float64 `json:"overall_hit_ratio"`
	KVFetches       int64   `json:"kv_fetches"`

	// Invalidation Stats
	InvalidationsTotal   int64 `json:"invalidations_total"`
	InvalidationsBatched int64 `json:"invalidations_batched"`
}

type Config struct {
	// Buffer configuration (from EntityStore)
	BufferConfig BufferConfig `json:"buffer,omitempty"`

	// KV bucket configuration
	BucketConfig BucketConfig `json:"bucket,omitempty"`

	// Cache configuration (from EntityStore)
	Cache CacheConfig

	// Edge configuration (from EdgeManager)
	Edge EdgeConfig

	// Worker pool configuration
	Workers int `default:"5"`

	// Operation timeouts
	WriteTimeout time.Duration `default:"5s"`
	ReadTimeout  time.Duration `default:"2s"`

	// Retry configuration
	MaxRetries int           `default:"10"`
	RetryDelay time.Duration `default:"100ms"`
}

type DataConsistency interface {
	CleanupIncomingReferences(ctx context.Context, deletedEntityID string, outgoingTriples []message.Triple) error
	CheckOutgoingTriplesConsistency(ctx context.Context, entityID string, entity *gtypes.EntityState, status *EntityIndexStatus)
	HasRelationshipToEntity(entity *gtypes.EntityState, targetEntityID string, predicate string) bool
}

type DataLifecycle interface {
	// Run starts the DataManager and blocks until context is cancelled.
	// If onReady is provided, it is called once initialization completes successfully.
	Run(ctx context.Context, onReady func()) error
	FlushPendingWrites(ctx context.Context) error
	GetPendingWriteCount() int
	GetCacheStats() CacheStats
}

type Dependencies struct {
	KVBucket        jetstream.KeyValue      // NATS KV bucket for persistence
	MetricsRegistry *metric.MetricsRegistry // Framework metrics registry
	Logger          *slog.Logger            // Structured logging
	Config          Config                  // Configuration
}

type EdgeConfig struct {
	// Edge validation settings
	ValidateEdgeTargets bool `default:"true"`
	AtomicOperations    bool `default:"true"`
}

type EntityCreatedCallback func(entityID string)

type EntityIndexStatus struct {
	OutgoingEdgesConsistent bool     `json:"outgoing_edges_consistent"`
	InconsistentEdges       []string `json:"inconsistent_edges,omitempty"`
}

type EntityManager interface {
	EntityReader
	EntityWriter

	CreateEntityWithTriples(ctx context.Context, entity *gtypes.EntityState, triples []message.Triple) (*gtypes.EntityState, error)
	UpdateEntityWithTriples(ctx context.Context, entity *gtypes.EntityState, addTriples []message.Triple, removePredicates []string) (*gtypes.EntityState, error)
	BatchWrite(ctx context.Context, writes []EntityWrite) error
	List(ctx context.Context, pattern string) ([]string, error)
	// ListWithPrefix returns entity IDs that have the given prefix.
	// Used for hierarchical entity queries like finding siblings in PathRAG.
	ListWithPrefix(ctx context.Context, prefix string) ([]string, error)
}

type EntityReader interface {
	GetEntity(ctx context.Context, id string) (*gtypes.EntityState, error)
	ExistsEntity(ctx context.Context, id string) (bool, error)
	BatchGet(ctx context.Context, ids []string) ([]*gtypes.EntityState, error)
	// ListWithPrefix returns entity IDs that have the given prefix.
	// Used for hierarchical entity queries like finding siblings in PathRAG.
	ListWithPrefix(ctx context.Context, prefix string) ([]string, error)
}

type EntityWrite struct {
	Operation Operation           // create|update|delete
	Entity    *gtypes.EntityState // Entity data (nil for delete)
	Triples   []message.Triple    // Triples to add (for create/update)
	Callback  func(error)         // Optional completion callback
	RequestID string              // Optional request ID for tracing
	Timestamp time.Time           // When request was created
	Strategy  WriteStrategy       // CAS vs Put for updates (default: CAS)
}

type EntityWriter interface {
	CreateEntity(ctx context.Context, entity *gtypes.EntityState) (*gtypes.EntityState, error)
	UpdateEntity(ctx context.Context, entity *gtypes.EntityState) (*gtypes.EntityState, error)
	// UpsertEntity atomically creates or updates an entity using Put semantics.
	// This is the preferred method for streaming data where idempotency is required.
	// It avoids TOCTOU races that occur with separate GetEntity → Create/Update patterns.
	UpsertEntity(ctx context.Context, entity *gtypes.EntityState) (*gtypes.EntityState, error)
	DeleteEntity(ctx context.Context, id string) error
}

type L1CacheConfig struct {
	Type      string `default:"lru"`
	Size      int    `default:"1000"`
	Metrics   bool   `default:"true"`
	Component string `default:"entity_l1"`
}

type L2CacheConfig struct {
	Type            string        `default:"ttl"`
	Size            int           `default:"10000"`
	TTL             time.Duration `default:"5m"`
	CleanupInterval time.Duration `default:"1m"`
	Metrics         bool          `default:"true"`
	Component       string        `default:"entity_l2"`
}

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

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

type Operation string

type TripleManager interface {
	AddTriple(ctx context.Context, triple message.Triple) error
	RemoveTriple(ctx context.Context, subject, predicate string) error
	CreateRelationship(ctx context.Context, fromEntityID, toEntityID string, predicate string, metadata map[string]any) error
	DeleteRelationship(ctx context.Context, fromEntityID, toEntityID string, predicate string) error
}

type WriteResult struct {
	EntityID string              // ID of the entity written
	Version  int64               // Final version after write
	Created  bool                // Whether entity was created (vs updated)
	Entity   *gtypes.EntityState // Final entity state
	Error    error               // Error if operation failed
}

type WriteStrategy int