query

type Cond struct {
	Column string
	Op     Op
	Value  any    // a slice for In/NotIn; ignored for IsNull/IsNotNull
	Or     []Cond // when non-empty, an OR group (Column/Op/Value ignored)
}

type Delta struct {
	// StreamID is the transport position (Redis stream entry ID). It maps
	// 1:1 onto the SSE "id:" field so Last-Event-ID resume works.
	StreamID string `json:"stream_id"`

	// Channel the delta was delivered on.
	Channel string `json:"channel"`

	TenantID  string          `json:"tenant_id"`
	Aggregate string          `json:"aggregate"`
	AggID     string          `json:"agg_id"`
	Version   int64           `json:"version"`
	Type      string          `json:"type"`
	At        time.Time       `json:"at"`
	Payload   json.RawMessage `json:"payload"`
}

type Fabric interface {
	// Exec runs one command: the only write path for aggregates.
	Exec(ctx context.Context, cmd command.Command) (command.Result, error)

	// ExecBatch runs N commands in one transaction, ordered, all-or-nothing.
	ExecBatch(ctx context.Context, cmds []command.Command) ([]command.Result, error)

	Relational() RelationalQuerier
	Graph() GraphQuerier
	Search() SearchQuerier
	Timeseries() TSQuerier
	Vector() VectorQuerier
	Spatial() SpatialQuerier
	Document() document.Store
	Blob() blob.Store

	// Subscribe resolves the scope to a channel server-side (authz hook
	// included) and returns a conflated delta stream.
	Subscribe(ctx context.Context, scope SubscribeScope) (<-chan Delta, error)

	// WaitForProjection blocks until the named projection has applied the
	// aggregate at or beyond version, or the context deadline expires
	// (ErrProjectionLag). It is the read-your-writes helper for callers
	// that need a projection-backed query right after a command.
	WaitForProjection(ctx context.Context, projection, aggregate, aggID string, version int64) error
}

type Geometry struct {
	WKT  string
	SRID int
}

type GraphQuerier interface {
	// Query runs a read-only openCypher query. into may be *[]string for
	// single-column id traversals, or a pointer to a slice of structs for
	// multi-column rows (adapter-mapped).
	Query(ctx context.Context, cypher string, params map[string]any, into any) error

	// TraverseAndHydrate runs a traversal that RETURNs ids, then hydrates
	// the rows from Postgres in one batched relational query. The target
	// entity is inferred from into's element type via the registry. Never
	// N+1.
	TraverseAndHydrate(ctx context.Context, cypher string, params map[string]any, into any) error

	// ApplyMutations applies engine-neutral projection mutations to the
	// named target graph (projection consumers and rebuilds only).
	ApplyMutations(ctx context.Context, target string, muts []projection.Mutation) error
}

type ListQuery struct {
	// Where: conditions ANDed together. Use the constructors; Eqs(map)
	// is the terse equality shorthand.
	Where Where
	// OrderBy: one or more comma-separated "col [ASC|DESC]" terms, e.g.
	// "sort_order ASC, created_at ASC". Empty orders by id.
	OrderBy string
	Limit   int
	Offset  int
}

type Op string

type Point struct {
	Key     string // series key within the tenant, e.g. tag id
	At      time.Time
	Value   float64
	Quality int
}

type RangeQuery struct {
	Series string
	Key    string
	From   time.Time
	To     time.Time
	Bucket time.Duration // 0 = raw points
	Agg    string        // "avg", "min", "max", "last" (when Bucket > 0)
}

type RelationalQuerier interface {
	// Get loads one aggregate row by id into a model pointer.
	Get(ctx context.Context, entity, id string, into any) error

	// GetMany loads many rows in ONE batched query (WHERE id = ANY($1)) —
	// the dataloader-style hydration primitive. Order follows ids; missing
	// rows are skipped.
	GetMany(ctx context.Context, entity string, ids []string, into any) error

	// List pages through an entity's rows with a structured, engine-neutral
	// filter (Where/Filter), ordering and pagination. The filter covers
	// grove's builder expressiveness — operators, IN, LIKE, null checks,
	// OR groups — without leaking engine types; reads it cannot express
	// drop to the raw Query escape hatch.
	List(ctx context.Context, entity string, q ListQuery, into any) error

	// Query is the raw SQL escape hatch (still tenant-guarded). Use it for
	// reads the structured filter cannot express; writes belong to Exec.
	Query(ctx context.Context, into any, sql string, args ...any) error
}

type Repo[T any] struct {
	// contains filtered or unexported fields
}

type SearchQuerier interface {
	// Search runs a query against an entity's declared search fields.
	Search(ctx context.Context, q SearchQuery, into any) error

	// ApplyMutations applies DocIndex/DocDeindex mutations to the named
	// target index (projection consumers and rebuilds only).
	ApplyMutations(ctx context.Context, target string, muts []projection.Mutation) error
}

type SearchQuery struct {
	Entity string
	Query  string
	// Filter narrows results with the same Cond vocabulary as relational
	// List (Eq/In/Gt/…/Or), applied by engines in non-scoring filter
	// context. Columns must be indexed fields.
	Filter Where
	// Sort is an indexed column, optionally suffixed " DESC". Empty sorts
	// by relevance score.
	Sort string
	// Limit caps the page size (adapter default when <= 0); Offset skips
	// that many leading hits.
	Limit  int
	Offset int
}

type SearchRequest struct {
	Query  string
	Filter Where
	Sort   string
	Limit  int
	Offset int
}

type SpatialMatch struct {
	ID        string
	DistanceM float64 // metres
	Meta      map[string]any
}

type SpatialQuerier interface {
	// Upsert stores or replaces the geometry for (tenant, entity, id).
	Upsert(ctx context.Context, entity, id string, geom Geometry, meta map[string]any) error
	// Within returns entities whose geometry lies within q.RadiusM of q.Center,
	// nearest-first, scanned into *[]SpatialMatch.
	Within(ctx context.Context, q SpatialQuery, into any) error
	// Delete removes the geometry for (tenant, entity, id).
	Delete(ctx context.Context, entity, id string) error
}

type SpatialQuery struct {
	Entity  string
	Center  Geometry
	RadiusM float64 // radius in metres
	K       int     // cap; <=0 → adapter default
}

type SubscribeScope struct {
	// Entity is the registry entity name.
	Entity string `json:"entity"`

	// Scope is a scope name declared in the entity's spec ("id", "site",
	// "tenant", ...).
	Scope string `json:"scope"`

	// ID is the scope id (aggregate id for "id" scopes, container id for
	// field scopes). Ignored for tenant scope — the tenant always comes
	// from the authenticated context.
	ID string `json:"id,omitempty"`
}

type TSQuerier interface {
	BulkWrite(ctx context.Context, series string, points []Point) error
	Range(ctx context.Context, q RangeQuery, into any) error
}

type VectorMatch struct {
	ID    string
	Score float64 // cosine similarity, higher is closer
	Meta  map[string]any
}

type VectorQuerier interface {
	Upsert(ctx context.Context, entity, id string, embedding []float32, meta map[string]any) error
	Similar(ctx context.Context, q VectorQuery, into any) error
	// Delete removes the embedding for (tenant, entity, id). Deleting a missing
	// id is a no-op. Mirrors SpatialQuerier.Delete.
	Delete(ctx context.Context, entity, id string) error
	// Get returns the stored embedding for (entity, id), or a *fabriqerr.NotFoundError
	// when absent. Mirrors RelationalQuerier.Get's get-by-id + NotFound convention.
	Get(ctx context.Context, entity, id string) ([]float32, error)
	// DeleteByMeta removes every embedding for (tenant, entity) whose meta
	// contains all key/value pairs in filter (AND-of-equals). An empty filter
	// deletes ALL embeddings for (tenant, entity) — scope intentionally.
	DeleteByMeta(ctx context.Context, entity string, filter map[string]string) error
}

type VectorQuery struct {
	Entity    string
	Embedding []float32
	K         int
	// Filter restricts matches to embeddings whose meta contains all of these
	// key/value pairs (exact-match, AND-of-equals). Empty/nil = no filter.
	Filter map[string]string
}

type Where []Cond