registry

type AnalyticsSpec struct {
	// Include is the allow-list of payload field names co-located in the
	// analytics store. Ignored when IncludeAll is true.
	Include []string
	// IncludeAll ships the whole (unredacted) payload. Use with care — it
	// widens the trust boundary to every column.
	IncludeAll bool
	// Hash names payload fields whose VALUE is replaced with a stable salted
	// hash before it crosses the trust boundary — pseudonymization. The raw
	// value never lands, but equal values hash equally, so operators can still
	// count-distinct / group-by / join on the field across the fleet without
	// co-locating the sensitive value. A hashed field is implicitly included
	// (it need not also appear in Include). Requires Config.Analytics.HashSalt.
	Hash []string
}

type Binding struct {
	Table         string
	Columns       []string
	PK            string
	TenantColumn  string
	VersionColumn string
	// contains filtered or unexported fields
}

type CRDTSpec struct {
	Engine        string        // engine reference, e.g. "grove-crdt"
	SnapshotEvery int           // compact after this many updates
	QuietWindow   time.Duration // idle window before materialization

	// ArchiveHistory opts this entity's documents into offloading sealed
	// update history to the blob plane on Compact (latest state stays in the
	// DB). nil = inherit the global Config.Documents.ArchiveHistory default;
	// a non-nil pointer overrides it per entity.
	ArchiveHistory *bool
}

type CacheSpec struct {
	TTL    time.Duration
	Scoped bool
}

type ColumnType int

type DistillSpec struct {
	SourceFields []string
	Text         func(vals map[string]any) string
	Scopes       []string
	Budget       int
}

type DynamicColumn struct {
	Name    string
	Type    ColumnType
	NotNull bool
	// Default is an optional SQL default EXPRESSION (e.g. "now()", "'pending'",
	// "0"). It is interpolated verbatim into DDL and is intentionally NOT
	// identifier-validated (it is an expression, not an identifier), so it must
	// be a trusted, control-plane value — never a user-supplied string. Same
	// trust level as hand-written migration SQL.
	Default string
}

type DynamicIndex struct {
	Name    string
	Columns []string
	Unique  bool
}

type DynamicSchema struct {
	Table   string
	Columns []DynamicColumn
	Indexes []DynamicIndex

	// NoTypeCheck opts the entire entity out of application-level payload type
	// validation on the command plane. Column values are then passed through
	// unchanged and only the database column types enforce shape. Zero value
	// (false) = validate.
	NoTypeCheck bool
}

type EdgeSpec struct {
	Field  string // FK column on this entity's table
	Rel    string // relationship type, e.g. "LOCATED_AT"
	Target string // registry name of the target entity
}

type EmbedSpec struct {
	Fields []string
	Text   func(vals map[string]any) string
}

type Entity struct {
	Spec    EntitySpec
	Binding *Binding
}

type EntitySpec struct {
	Name      string
	Kind      Kind
	Model     any
	GraphNode string         // graph label; empty = not projected to the graph
	GraphEdge *GraphEdgeSpec // when set, the entity projects as a relationship
	Edges     []EdgeSpec
	Search    SearchSpec
	Subscribe []Scope
	CRDT      *CRDTSpec

	// Schema declares a runtime-defined ("dynamic") entity instead of Model.
	// Exactly one of Model or Schema must be set.
	Schema *DynamicSchema

	// Validate, when set, runs after structural validation on every
	// create/update/upsert with the column-keyed payload. Fabriq attaches
	// no meaning to the values; consumers enforce their own invariants
	// (enum membership, checksums, cross-field rules).
	Validate func(vals map[string]any) error

	// Live opts the entity into the maintained-result-set live query engine.
	// Nil (the zero value) means live queries are disabled for this entity.
	Live *LiveSpec

	// Cache opts the entity into the read-through row cache. Nil = not cached.
	Cache *CacheSpec

	// Embed opts the entity into vector embedding (auto-indexing). Nil = not embedded.
	Embed *EmbedSpec

	// Distill opts the entity into context distillation: each row gets an
	// L0 digest summary; declared Scopes form L1 backbone nodes. Nil = not
	// distilled. The distillation layer supplies the Summarizer/Guard.
	Distill *DistillSpec

	// Analytics opts the entity into the cross-tenant analytics sink. Nil
	// (the zero value) means the entity is NEVER co-located in the shared
	// analytics store — deny-by-default. When set, only the declared fields
	// (or the whole payload if IncludeAll) cross the trust boundary.
	Analytics *AnalyticsSpec

	// Insights opts the entity into the per-tenant customer-facing analytics
	// store (projected facts). Nil = not projected. Distinct from Analytics
	// (the cross-tenant operator sink) — Insights stays inside the tenant DB.
	Insights *InsightsSpec

	// Metrics declares named, typed cube queries for this entity's Source.
	Metrics []MetricSpec
}

type GraphEdgeSpec struct {
	TypeField   string
	SourceField string
	TargetField string
	SourceLabel string
	TargetLabel string
	PropFields  []string
}

type InsightsSpec struct {
	// Measures are numeric columns aggregatable via Sum/Avg/Min/Max in a cube
	// Query. Each must be a column of the entity.
	Measures []string
	// Dimensions are columns usable as group-by keys. Each must be a column.
	Dimensions []string
}

type Kind int

type LiveSpec struct {
	Filterable []string // columns allowed in Where (empty = all)
	Sortable   []string // columns allowed in Sort (empty = all)
	MaxWindow  int      // cap on Limit (0 = engine default)
}

type MetricMeasure struct {
	Kind  string
	Field string
	As    string
	// Percentile is the fraction (0,1) for a "percentile" Kind measure, e.g.
	// 0.95 for p95 — mirrors query.Measure.Percentile. Required when Kind is
	// "percentile"; ignored otherwise. Threaded through to query.Measure by
	// core/insights/resolve.go's toQueryMeasures.
	Percentile float64
}

type MetricSpec struct {
	Name          string
	Source        string          // event name or entity name
	Measures      []MetricMeasure // at least one
	Dimensions    []string
	DefaultBucket time.Duration // optional default TimeBucket

	// Rollup opts this metric into materialization (phase 2b). Nil (the zero
	// value) means the metric stays live-only, computed on demand from raw
	// events/facts on every query. Rollups are event-sourced only (Source must
	// NOT name a registered entity). As of phase 2b-2, a Rollup metric may
	// also carry a non-additive "sketch" measure (count_distinct, percentile):
	// these are stored as toolkit-typed columns (hyperloglog/tdigest — see
	// adapters/postgres's rollupTableDDL) rather than plain NUMERIC, and
	// require timescaledb_toolkit to be available in the target database
	// (adapters/postgres's toolkitAvailable boot-check fails loudly if not).
	// Rollup-served count_distinct/percentile are approximate; the pure-live
	// path stays exact.
	Rollup *RollupSpec
}

type Option func(*Registry)

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

type RollupSpec struct {
	// Bucket is the rollup grain (e.g. time.Hour). Required, must be > 0,
	// and must evenly divide 24h (Validate rejects anything else) — the
	// stitched-query boundary math truncates on Go's zero-time origin and
	// only lines up with Postgres time_bucket's day-aligned grid when the
	// grain divides a day evenly.
	Bucket time.Duration

	// SealGrace delays sealing a bucket past its end time, so events that
	// arrive slightly late still land in the correct bucket. Zero means the
	// maintainer applies its own sane default.
	SealGrace time.Duration

	// RerollWindow is how far back (in buckets) the maintainer recomputes on
	// every pass, to absorb events that arrived after a bucket was already
	// sealed. Zero means the maintainer applies its own sane default.
	RerollWindow time.Duration
}

type Scope struct {
	// Name appears in channel names: changes:{tenant}:{name}:{id}.
	Name string

	// Field is the model column whose value provides the channel id for
	// containing-scope channels (e.g. "site_id" for a by-site scope).
	// Empty for the ByID and ByTenant builtins.
	Field string
}

type SearchSpec struct {
	Index  string   // logical index base name; tenant routing is derived
	Fields []string // columns included in the indexed document
}