storage

type AuditLog struct {
	ID        string         `json:"id"`
	TenantID  string         `json:"tenant_id,omitempty"`
	SessionID string         `json:"session_id"`
	Actor     string         `json:"actor"`
	Action    string         `json:"action"`
	Resource  string         `json:"resource"`
	Detail    map[string]any `json:"detail,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

type BatchIngester interface {
	// AppendEvents appends many ledger events atomically in one batch. Like
	// AppendEvent it is idempotent on the event id.
	AppendEvents(ctx context.Context, events []*Event) error
	// InsertTraces inserts many trace spans in one batch.
	InsertTraces(ctx context.Context, traces []*Trace) error
}

type Checkpoint struct {
	ID        string         `json:"id"`
	TenantID  string         `json:"tenant_id,omitempty"`
	SessionID string         `json:"session_id"`
	RunID     string         `json:"run_id"`
	NodeID    string         `json:"node_id"`
	State     map[string]any `json:"state"`
	SeqNum    int64          `json:"seq_num"`
	CreatedAt time.Time      `json:"created_at"`
}

type CheckpointPage struct {
	Checkpoints []*Checkpoint `json:"checkpoints"`
	NextCursor  string        `json:"next_cursor,omitempty"`
}

type Config struct {
	// Storage backend: "sqlite", "postgres", "mysql", "redis", "mongo", "dynamo"
	Backend string `json:"backend" yaml:"backend"`

	// DSN / connection string for the storage backend.
	DSN string `json:"dsn" yaml:"dsn"`

	// VectorBackend: "qdrant", "redisvector", "milvus", "weaviate", "pinecone"
	VectorBackend string `json:"vector_backend" yaml:"vector_backend"`

	// VectorDSN / connection for vector store.
	VectorDSN string `json:"vector_dsn" yaml:"vector_dsn"`
}

type Embedding struct {
	ID       string         `json:"id"`
	Vector   []float32      `json:"vector"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Content  string         `json:"content,omitempty"`
}

type Event struct {
	ID        string    `json:"id"`
	TenantID  string    `json:"tenant_id,omitempty"`
	SessionID string    `json:"session_id"`
	SeqNum    int64     `json:"seq_num"`
	Type      string    `json:"type"`
	Payload   any       `json:"payload"`
	CreatedAt time.Time `json:"created_at"`
}

type EventPage struct {
	Events     []*Event `json:"events"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

type FileInfo struct {
	Path      string    `json:"path"`
	Size      int       `json:"size"`
	UpdatedAt time.Time `json:"updated_at"`
}

type MemoryRecord struct {
	ID        string    `json:"id"`
	TenantID  string    `json:"tenant_id,omitempty"`
	SessionID string    `json:"session_id,omitempty"` // empty = long-term
	AgentID   string    `json:"agent_id"`
	UserID    string    `json:"user_id,omitempty"`
	Kind      string    `json:"kind"` // short_term, long_term
	Key       string    `json:"key"`
	Value     any       `json:"value"`
	CreatedAt time.Time `json:"created_at"`
}

type Paginator interface {
	ListEventsPaged(ctx context.Context, sessionID string, afterSeq int64, limit int, cursor string) (*EventPage, error)
	ListTracesPaged(ctx context.Context, sessionID string, limit int, cursor string) (*TracePage, error)
	ListCheckpointsPaged(ctx context.Context, sessionID string, limit int, cursor string) (*CheckpointPage, error)
}

type Retention interface {
	// TrimEvents deletes events created strictly before olderThan.
	TrimEvents(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimTraces deletes traces started strictly before olderThan.
	TrimTraces(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimAuditLogs deletes audit logs created strictly before olderThan.
	TrimAuditLogs(ctx context.Context, olderThan time.Time) (int64, error)
	// TrimCheckpoints keeps only the most recent keep checkpoints (by seq_num)
	// for the given session and deletes the rest. keep <= 0 is a no-op.
	TrimCheckpoints(ctx context.Context, sessionID string, keep int) (int64, error)
}

type RetentionPolicy struct {
	// MaxAge deletes events, traces and audit logs older than now-MaxAge.
	// Zero disables age-based trimming.
	MaxAge time.Duration `json:"max_age,omitempty"`
	// KeepCheckpointsPerSession limits checkpoints retained per session.
	// Zero disables checkpoint trimming.
	KeepCheckpointsPerSession int `json:"keep_checkpoints_per_session,omitempty"`
}

type RetentionResult struct {
	Events      int64 `json:"events"`
	Traces      int64 `json:"traces"`
	AuditLogs   int64 `json:"audit_logs"`
	Checkpoints int64 `json:"checkpoints"`
}

type SearchOption func(*SearchOptions)

type SearchOptions struct {
	// Filter restricts results to embeddings whose metadata matches every
	// key/value pair (exact match, AND semantics). A nil or empty Filter matches
	// everything. Adapters that store metadata structurally (qdrant, pgvector,
	// pinecone, chromadb) apply it server-side so top-k is computed over the
	// matching subset; adapters that store metadata as an opaque blob (lancedb,
	// milvus, weaviate, redisvector) apply it client-side over the returned
	// window (which may under-return under a highly selective filter).
	Filter map[string]any
}

type SearchResult struct {
	Embedding
	Score float32 `json:"score"`
}

type Session struct {
	ID        string         `json:"id"`
	TenantID  string         `json:"tenant_id,omitempty"`
	AgentID   string         `json:"agent_id"`
	Status    string         `json:"status"` // running, paused, completed, failed
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
}

type SessionDeleter interface {
	DeleteSession(ctx context.Context, id string) error
}

type SessionFileStore interface {
	// PutFile creates or overwrites the file at path with content.
	PutFile(ctx context.Context, sessionID, path string, content []byte) error
	// GetFile returns the content of the file at path, or an error if it does
	// not exist.
	GetFile(ctx context.Context, sessionID, path string) ([]byte, error)
	// ListFiles returns metadata for every file in the session whose path has
	// the given prefix (empty prefix lists all), ordered by path.
	ListFiles(ctx context.Context, sessionID, prefix string) ([]FileInfo, error)
	// DeleteFile removes the file at path. Deleting a missing file is not an
	// error (idempotent).
	DeleteFile(ctx context.Context, sessionID, path string) error
}

type SessionStatusUpdater interface {
	// UpdateSessionStatus sets the session's Status and UpdatedAt. It returns
	// an error if the session does not exist (or is not visible to the
	// context's tenant), mirroring GetSession's not-found behavior.
	UpdateSessionStatus(ctx context.Context, sessionID, status string, updatedAt time.Time) error
}

type Storage interface {
	// Sessions
	CreateSession(ctx context.Context, s *Session) error
	GetSession(ctx context.Context, id string) (*Session, error)
	UpdateSession(ctx context.Context, s *Session) error
	ListSessions(ctx context.Context, agentID string, limit, offset int) ([]*Session, error)

	// Memory
	PutMemory(ctx context.Context, m *MemoryRecord) error
	GetMemory(ctx context.Context, agentID, key string) (*MemoryRecord, error)
	ListMemory(ctx context.Context, agentID string, kind string) ([]*MemoryRecord, error)
	DeleteMemory(ctx context.Context, id string) error

	// Audit logs
	AppendAuditLog(ctx context.Context, log *AuditLog) error
	ListAuditLogs(ctx context.Context, sessionID string, limit, offset int) ([]*AuditLog, error)

	// Traces
	InsertTrace(ctx context.Context, t *Trace) error
	GetTrace(ctx context.Context, id string) (*Trace, error)
	ListTraces(ctx context.Context, sessionID string) ([]*Trace, error)

	// Event ledger (append-only)
	AppendEvent(ctx context.Context, e *Event) error
	ListEvents(ctx context.Context, sessionID string, afterSeq int64) ([]*Event, error)

	// Checkpoints
	SaveCheckpoint(ctx context.Context, cp *Checkpoint) error
	GetCheckpoint(ctx context.Context, id string) (*Checkpoint, error)
	GetLatestCheckpoint(ctx context.Context, sessionID string) (*Checkpoint, error)
	ListCheckpoints(ctx context.Context, sessionID string) ([]*Checkpoint, error)

	// Lifecycle
	Migrate(ctx context.Context) error
	Close() error
}

type Trace struct {
	ID        string    `json:"id"`
	TenantID  string    `json:"tenant_id,omitempty"`
	SessionID string    `json:"session_id"`
	ParentID  string    `json:"parent_id,omitempty"`
	Name      string    `json:"name"`
	Kind      string    `json:"kind"` // node, tool_call, model_call, approval
	Input     any       `json:"input,omitempty"`
	Output    any       `json:"output,omitempty"`
	Error     string    `json:"error,omitempty"`
	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at,omitempty"`
}

type TracePage struct {
	Traces     []*Trace `json:"traces"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

type VectorStore interface {
	// Upsert inserts or updates embeddings in the given collection.
	Upsert(ctx context.Context, collection string, embeddings []Embedding) error

	// Search performs similarity search and returns top-k results. Optional
	// SearchOptions (e.g. WithFilter) scope the search; adapters apply any filter
	// so that top-k is selected over the matching subset.
	Search(ctx context.Context, collection string, query []float32, topK int, opts ...SearchOption) ([]SearchResult, error)

	// Delete removes embeddings by IDs.
	Delete(ctx context.Context, collection string, ids []string) error

	// CreateCollection ensures a collection exists.
	CreateCollection(ctx context.Context, name string, dimension int) error

	// Close releases resources.
	Close() error
}