spi

type AggregateExpr struct {
	Op    AggregateOp
	Field string // scalar JSONPath
	// Alias is the response key. If blank, the server synthesizes
	// <op>_<field>.
	Alias string
}

type AggregateOp string

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

type AsyncSearchStore interface {
	// CreateJob persists a new job row. Epoch is always persisted as 1,
	// regardless of the value set on job.Epoch by the caller.
	CreateJob(ctx context.Context, job *SearchJob) error

	GetJob(ctx context.Context, jobID string) (*SearchJob, error)

	// UpdateJobStatus fences on epoch (ErrStaleClaim on mismatch) and refuses
	// a terminal job (ErrAlreadyTerminal). Against a missing job it returns
	// ErrNotFound. A zero finishTime is stored as absent (NULL/nil).
	UpdateJobStatus(ctx context.Context, jobID string, epoch int64, status string, resultCount int, errMsg string, finishTime time.Time, calcTimeMs int64) error

	// SaveResults streams entityIDs into the job's persisted result set.
	// Exactly one call is made per claim epoch; yield order is preserved as
	// GetResultIDs order. Implementations batch internally as they see fit,
	// but the result sequence position must increase strictly across chunks.
	// The store observes ctx cancellation. A nil return means everything
	// yielded was durably stored — it is NOT a statement about job success,
	// which is recorded separately via UpdateJobStatus.
	//
	// Fences on epoch (ErrStaleClaim) and terminal status (ErrAlreadyTerminal,
	// checked at least at chunk boundaries), matching UpdateJobStatus. A
	// missing job returns ErrNotFound.
	//
	// The fence is a property of the CALL, not of the rows it carries: an
	// entityIDs sequence that yields nothing MUST still be fenced, and MUST
	// still report ErrStaleClaim / ErrAlreadyTerminal / ErrNotFound where a
	// non-empty sequence would have. A search matching zero entities is an
	// ordinary outcome, so short-circuiting on "nothing to write" is exactly
	// the case where a reclaimed executor is most likely to learn — or fail to
	// learn — that it has been fenced off.
	SaveResults(ctx context.Context, jobID string, epoch int64, entityIDs iter.Seq[string]) error

	// GetResultIDs requires offset >= 0 && limit >= 1; a violation returns an
	// error, never a panic. Reading a non-terminal job answers with the
	// results saved so far.
	GetResultIDs(ctx context.Context, jobID string, offset, limit int) (entityIDs []string, total int, err error)

	DeleteJob(ctx context.Context, jobID string) error

	// ReapExpired deletes eligible expired jobs. Cross-tenant: obtain with a
	// background/tenant-less context, as with ScheduledTaskStore.ScanDue
	// (persistence.go:19-24).
	ReapExpired(ctx context.Context, ttl time.Duration) (int, error)

	// Cancel marks the job CANCELLED and stamps the given finishTime on the
	// job it transitions. Idempotent: cancelling a job already in a
	// terminal state returns nil AND does not overwrite the existing finish
	// time. Cancelling a non-existent job returns ErrNotFound. The finish
	// time is caller-supplied so all backends record the same instant — the
	// engine is the single clock.
	Cancel(ctx context.Context, jobID string, finishTime time.Time) error

	// Heartbeat stamps HeartbeatTime, fenced by epoch. Returns ErrStaleClaim
	// if epoch does not match the job's current Epoch, ErrAlreadyTerminal if
	// the job is already terminal, and ErrNotFound if the job does not exist.
	Heartbeat(ctx context.Context, jobID string, epoch int64) error

	// ClaimStale atomically claims up to limit RUNNING jobs whose heartbeat
	// (HeartbeatTime, or CreateTime as the baseline when HeartbeatTime is
	// nil) is older than staleAfter. It never claims a terminal job. Claiming
	// bumps Epoch and stamps HeartbeatTime from the store's current clock,
	// strictly later than the stamp it found stale; concurrent claimers
	// obtain disjoint sets of jobs. The staleness stamp and the staleness
	// comparison use the same clock domain (store-side, where the store has
	// one).
	// A released job (see Release) is eligible regardless of staleAfter;
	// claiming it clears the released mark and does NOT increment
	// StaleClaims. A job claimed because its heartbeat went stale has
	// StaleClaims incremented, atomically with the claim.
	// Cross-tenant, like ReapExpired: obtain with a background/tenant-less
	// context, as with ScheduledTaskStore.ScanDue (persistence.go:19-24).
	ClaimStale(ctx context.Context, staleAfter time.Duration, limit int) ([]*SearchJob, error)

	// ClearResults deletes the job's persisted result IDs. Idempotent.
	ClearResults(ctx context.Context, jobID string) error

	// Release relinquishes the caller's claim on a RUNNING job without
	// finishing it: the job stays RUNNING and becomes eligible for
	// ClaimStale immediately, regardless of staleAfter, so a live node can
	// take it over without waiting for the heartbeat to age out. Fenced by
	// epoch like every executor-side write: ErrStaleClaim if epoch is not
	// the job's current Epoch, ErrAlreadyTerminal if the job is terminal,
	// ErrNotFound if it does not exist. Idempotent at the same epoch.
	// Release does NOT bump Epoch and does NOT increment StaleClaims — a
	// release is a graceful handoff, not an attempt. The released mark
	// survives a later Heartbeat at the same epoch (a stray stamp from a
	// node that is going away cannot resurrect the job) and is cleared by
	// the ClaimStale that takes the job. Tenant-scoped, like Heartbeat.
	Release(ctx context.Context, jobID string, epoch int64) error
}

type Branch interface{ Kind() NodeKind }

type ChangeLevel string

type ClusterBroadcaster interface {
	Broadcast(topic string, payload []byte)
	Subscribe(topic string, handler func(payload []byte))
}

type CompositeUniqueKeyCapable interface {
	SupportsCompositeUniqueKeys() bool
}

type ConfigVar struct {
	Name        string
	Description string
	Default     string
	Required    bool
}

type DataType int

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

type DescribablePlugin interface {
	Plugin
	ConfigVars() []ConfigVar
}

type Entity struct {
	Meta EntityMeta
	Data []byte
}

type EntityMeta struct {
	ID                      string
	TenantID                TenantID
	ModelRef                ModelRef
	State                   string
	Version                 int64
	CreationDate            time.Time
	LastModifiedDate        time.Time
	TransactionID           string
	ChangeType              string        // "CREATED", "UPDATED", "DELETED"
	ChangeUser              string        // user ID who performed the change
	ChangeUserKind          PrincipalKind // kind of the attributed ChangeUser; empty on legacy rows
	ChangeExecutor          Principal     // the actual caller that performed the change, independent of attribution
	TransitionForLatestSave string
}

type EntityStore interface {
	Save(ctx context.Context, entity *Entity) (int64, error)
	// CompareAndSave saves the entity only if expectedTxID equals the
	// entity's current transaction ID as the caller's own transaction sees
	// it: a same-transaction Delete or Save IS the current state, not the
	// pre-transaction one, so comparing against a stale ID — including the
	// transaction's own prior write — conflicts and returns ErrConflict.
	//
	// expectedTxID MUST be non-empty. An empty expectedTxID is a contract
	// violation and the implementation MUST return an error rather than
	// comparing it — it is a caller bug, not a domain outcome, so it carries
	// no sentinel (the same treatment Search gives Limit <= 0). The empty
	// string is not a usable expectation: a missing entity, a deleted one,
	// and an entity written outside any transaction all carry an empty
	// EntityMeta.TransactionID — a non-transactional write may stamp none,
	// and EntityVersionMeta.TransactionID shows the same empty value on the
	// audit row — so "" cannot tell the three apart, and an "expect no
	// entity" reading of it would silently overwrite an entity that exists.
	//
	// For a non-empty expectedTxID the rule is a literal string comparison
	// against the entity's current EntityMeta.TransactionID. There are no
	// synonyms and no existence test; every other case follows from the
	// literal rule:
	//
	//   - A missing or deleted entity carries the empty transaction ID and
	//     so matches no non-empty expectedTxID. CompareAndSave therefore
	//     can never create, and never resurrect a deleted entity; Save is
	//     the way to create or to re-create.
	//   - Once a Delete is staged in the caller's own transaction, the
	//     entity's current ID is empty in that transaction's view, so no
	//     CompareAndSave can succeed against it for the rest of the
	//     transaction. Save unstages the delete.
	//
	// This agrees with GetVersionByTransaction below: neither treats an
	// empty transaction ID as a matchable value. There it is a lookup key
	// that matches nothing and returns ErrNotFound; here it is rejected
	// outright as a caller error.
	CompareAndSave(ctx context.Context, entity *Entity, expectedTxID string) (int64, error)
	// SaveAll saves multiple entities, returning versions in iteration order.
	// Backends may execute saves concurrently. On error, returns the first
	// error encountered; partially-saved entities within an uncommitted
	// transaction are invisible to readers.
	SaveAll(ctx context.Context, entities iter.Seq[*Entity]) ([]int64, error)
	Get(ctx context.Context, entityID string) (*Entity, error)
	// GetAsAt returns entityID as of asAt. Like every point-in-time read in
	// this SPI it is COMMITTED-ONLY: it ignores any ambient transaction and
	// never surfaces that transaction's own uncommitted writes — an entity
	// the transaction created is ErrNotFound, and one it updated comes back
	// at its committed payload. A backend whose ordinary reads join the
	// caller's transaction must route this read off it; bounding the query on
	// a timestamp is not sufficient, because a transaction-stable clock makes
	// the transaction's own writes fall inside every window it can compute.
	GetAsAt(ctx context.Context, entityID string, asAt time.Time) (*Entity, error)
	Delete(ctx context.Context, entityID string) error
	DeleteAll(ctx context.Context, modelRef ModelRef) error
	Exists(ctx context.Context, entityID string) (bool, error)
	Count(ctx context.Context, modelRef ModelRef) (int64, error)
	// CountByState returns the count of non-deleted entities grouped by state
	// for the given model. If states is non-nil, only the listed states are
	// included in the result. If states is nil, all states are returned.
	// An empty (non-nil) states slice returns an empty map without querying
	// the storage layer.
	//
	// Unknown model: returns an empty map with no error, matching Count's
	// behavior (no model-registry check at this layer).
	//
	// The returned map is always non-nil on success. Every zero-count
	// result — unknown model, empty model, an empty (non-nil) states slice,
	// or a transaction whose own view holds no entities (after DeleteAll,
	// say) — is an empty map, never nil.
	//
	// Implementations MUST push the state filter down to the storage layer
	// when feasible. Callers may invoke this from inside a transaction; the
	// returned counts MUST reflect the transactional view (uncommitted writes
	// from the current tx are visible, writes from other in-flight txs are not),
	// matching the semantics of Count.
	CountByState(ctx context.Context, modelRef ModelRef, states []string) (map[string]int64, error)

	// GetPage returns a page of modelRef's entities in the engine's
	// canonical per-engine entity-ID order (see OrderSpec's doc comment —
	// this is the same order Search/Iterate use for an empty/id-only
	// OrderBy, not guaranteed identical across backends).
	//
	// limit >= 1 && offset >= 0 is REQUIRED; either violation is a contract
	// violation and the implementation MUST return an error rather than
	// substituting a default. Implementations fail fast on any row-level
	// error rather than returning a partial page.
	//
	// A page with no rows — an empty model, or an offset past the end — MUST
	// be a non-nil, empty slice with a nil error, never a nil slice. Callers
	// distinguish "no rows" from "no page" without a nil check, so the
	// idiomatic `return nil, nil` is a contract violation here.
	//
	// asAt == nil reads the live, in-transaction overlay: with an ambient
	// transaction, the committed page is merged with the transaction's own
	// write-set, and — unconditionally, unlike Search's and Iterate's opt-in
	// TrackingRead — every entity on the returned page is recorded in the
	// transaction's read-set. asAt != nil ignores any ambient transaction
	// and reads committed-only state as of that instant.
	GetPage(ctx context.Context, modelRef ModelRef, limit, offset int, asAt *time.Time) ([]*Entity, error)

	// GetVersionByTransaction returns the earliest version of entityID
	// written by transaction txID. A transaction that saved the same
	// entity more than once before committing (e.g. two Save calls inside
	// one commit) may produce more than one matching version; the
	// earliest (lowest Version) is returned.
	//
	// Versions with no entity payload — DELETED tombstones — never match,
	// even when txID is the deleting transaction's own ID: this method
	// surfaces entity content, and a tombstone has none. Use
	// GetVersionMetadata to read a tombstone's metadata instead.
	//
	// An empty txID never matches a stored-empty TransactionID
	// (non-transactional writes carry one); it always returns ErrNotFound.
	// CompareAndSave above takes the same line on the empty transaction ID
	// — never a matchable value — and rejects it as a caller error.
	GetVersionByTransaction(ctx context.Context, entityID, txID string) (*EntityVersion, error)

	// GetVersionMetadata returns entityID's version metadata — no entity
	// payload, just the audit trail — newest first, ties broken by
	// Version DESC. opts.From/opts.Until bound the window inclusively; a
	// nil side is unbounded. opts.Limit caps the returned row count; 0
	// means all, bounded only by this one entity's own version history —
	// a deliberate divergence from GetPage's limit>=1 requirement, since
	// a single entity's history can never be an unbounded model-wide scan.
	//
	// Returns ErrNotFound ONLY when entityID has no version history at all;
	// an existing entity whose versions all fall outside opts.From/opts.Until
	// yields an empty slice and a nil error, never ErrNotFound.
	//
	// Deleted is true only on the DELETED tombstone row, and Version is
	// populated on every returned row, including the tombstone.
	GetVersionMetadata(ctx context.Context, entityID string, opts VersionMetadataOptions) ([]EntityVersionMeta, error)

	// Search is the bounded-or-fail predicate read: SearchOptions.Limit >= 1
	// is REQUIRED and caps the matched set; more matches than Limit MUST be
	// ErrSearchResultLimitExceeded, never a truncated prefix; exactly at the
	// limit succeeds; Limit <= 0 is a contract violation and MUST error.
	// Search honours an active transaction (read-your-own-writes) unless
	// PointInTime is set, in which case it is committed-only. With a
	// transaction active the implementation overlays the transaction's
	// write-set, so the result is identical to a committed-plus-buffer merge
	// for the same transaction state — the merge MergeBounded computes.
	// Returned entities enter the read-set only when
	// SearchOptions.TrackingRead is set. See SearchOptions.
	Search(ctx context.Context, filter Filter, opts SearchOptions) ([]*Entity, error)

	// Iterate is the streamed predicate read: entities matching filter, one
	// at a time, in bounded memory. See IterateOptions and Iterator.
	//
	// Semantics:
	//   - Plugins push pushable parts of the filter into storage (SQL WHERE,
	//     CQL index lookup); residual is applied inside Next() before
	//     yielding.
	//   - A zero-value Filter means "yield all entities for the model"
	//     (subject to opts).
	//   - IterateOptions.OrderBy: empty means order is unspecified. A backend
	//     whose async search is engine-executed MUST honour a non-empty
	//     OrderBy. A backend whose async search is self-executing MAY reject a
	//     non-empty OrderBy with a plain error — there is no refusal sentinel,
	//     callers see whatever error the plugin returns. A non-empty OrderBy
	//     with an ambient transaction is unsupported; Iterate MUST return an
	//     error rather than silently ignoring the order.
	//   - Overlay semantics: with an ambient transaction, the merged
	//     (committed ∪ transaction write-set) view is snapshotted at Iterate()
	//     call time. Mutating the transaction while its iterator is open is
	//     forbidden — the visibility of entities such a mutation would add,
	//     remove, or change is unspecified for that already-open iterator.
	//   - Implementations MUST NOT hold a global write-blocking lock for the
	//     lifetime of the iterator (e.g. by holding only short-lived row
	//     locks, or by paging through a cursor).
	//   - The iterator MUST observe ctx cancellation: the underlying driver
	//     surfaces an error; the iterator reports it via Err() and Next()
	//     returns false.
	//   - No retry on transient driver errors — the plugin surfaces the first
	//     error and ends iteration.
	//   - Err() returns that error stickily; subsequent Next() calls return
	//     false.
	//   - Close() is idempotent.
	//
	// ModelRef is a first-class argument because iteration is always scoped
	// to exactly one model; IterateOptions carries only knobs that vary
	// across calls against the same model.
	//
	// Every engine path that reads more than one entity — direct search on
	// a store, async search, delete-all, conditional delete, grouped stats —
	// consumes Search or Iterate. There is no whole-model read on this
	// interface and no in-process fallback in the engine.
	Iterate(ctx context.Context, model ModelRef, filter Filter, opts IterateOptions) (Iterator, error)
}

type EntityVersion struct {
	Entity     *Entity
	ChangeType string
	User       string
	Timestamp  time.Time
	Version    int64
	Deleted    bool
	// AttributedKind is the kind of the attributed User above; empty on
	// legacy rows. Populated independently of Entity — GetVersionByTransaction,
	// EntityVersion's sole producer, contractually never returns a DELETED
	// tombstone (see its doc comment), so Entity is populated on every
	// EntityVersion in circulation today; AttributedKind is nonetheless
	// stamped as an independent field rather than derived from Entity, for
	// symmetry with EntityVersionMeta.
	AttributedKind PrincipalKind
	// Executor is the actual caller that performed the change, independent
	// of attribution. Populated independently of Entity for the same reason
	// as AttributedKind.
	Executor Principal
}

type EntityVersionMeta struct {
	Version    int64
	ChangeType string
	Timestamp  time.Time
	// User is the attributed user ID for this version's change.
	User string
	// AttributedKind is the kind of User above; empty on legacy rows.
	AttributedKind PrincipalKind
	// Executor is the actual caller that performed the change, independent
	// of attribution.
	Executor Principal
	// TransactionID may be empty for non-transactional writes.
	TransactionID string
	// Deleted is canonical: derived from ChangeType == "DELETED", not a
	// separately-stamped flag. True only on the tombstone row.
	Deleted bool
}

type ExecutionResult struct {
	State      string
	Success    bool
	StopReason string
	Error      error
}

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

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

type FactoryOption func(*factoryConfig)

type FieldDescriptor struct {
	// Path is the leaf's key in the flattened field view, in the model
	// tree's JSONPath convention: a "$." prefix, and array hops rendered as
	// "[*]" (e.g. "$.name", "$.items[*].price"). The convention is
	// load-bearing, not cosmetic — a lookup that misses yields empty Types,
	// which the kernel treats as described on [ConditionToFilter].
	Path string

	// Types is the declared type set for the leaf — what [Filter.Declared]
	// carries and what the kernel dispatches on. Empty is meaningful and
	// dangerous: see [ConditionToFilter].
	Types []DataType

	// IsArray marks a leaf reached directly as an array's element type.
	IsArray bool
}

type FieldSource string

type Filter struct {
	Op FilterOp

	// Path addresses the leaf field this predicate applies to. It is BARE:
	// there is no "$." prefix and no JSONPath syntax. [ConditionToFilter]
	// strips the "$." at the wire boundary (see stripDollarDot, where the
	// leader is mandatory on the way in) and [lifecycleToFilter] emits
	// canonical meta names directly, so by the time a Filter reaches a storage
	// plugin the prefix is already gone. A "$."-prefixed path is therefore
	// malformed, not a tolerated alias.
	//
	// The two forms are opposites and must not be conflated: the wire jsonPath
	// REQUIRES the leader, this plugin-facing Path FORBIDS it.
	//
	// # Grammar
	//
	//	path      = segment ( "." segment )*
	//	segment   = name subscript*
	//	name      = 1*( ALPHA / DIGIT / "_" / "-" )   ; ASCII only
	//	subscript = "[" ( "*" / 1*DIGIT ) "]"
	//
	// This is the wire jsonPath grammar with the "$." leader removed. A
	// bracket is an array subscript; a dotted numeric segment is a field
	// whose name is that digit string. The two address different values and
	// a backend MUST NOT collapse them — see docs/cloud-parity/path-grammar.md.
	//
	// The grammar is deliberately narrower than any backend's native JSON
	// path syntax. It is the intersection every backend can serve, and on
	// SQL backends it is also the injection guard: every character that could
	// terminate a quoted JSON-path literal is outside it. A backend needing a
	// wider form must widen this grammar, not bypass its own validator.
	//
	// An EMPTY Path is legal ONLY for a tree operator (FilterAnd, FilterOr):
	// those carry no leaf condition of their own, Children hold the real
	// leaves. It is NOT a way for a LEAF to say "addresses no field" — every
	// leaf addresses exactly one field, on either FieldSource, and an empty
	// Path on one is rejected: spi.Prepare fails it with ErrUnevaluableLeaf
	// rather than treating it as a match against the whole document or as an
	// unconditional non-match. See prepared_filter.go.
	//
	// Parse it with ParseFilterPath and validate it with ValidateFilterPath.
	// A second, independent spelling of the grammar is how a backend admits a
	// form no resolver serves. This grammar and these two parse helpers are
	// for Source=SourceData; a Source=SourceMeta Path is not a data path at
	// all — it names one of a closed set of canonical meta field names
	// directly (a superset of [MetaFieldNames] that also carries storage-key
	// aliases such as "entity_id"), and spi.Prepare rejects a Path that is
	// empty or outside that set the same way (ErrUnevaluableLeaf).
	//
	// # Rejection is mandatory
	//
	// Both FieldSource values are held to the same grammar, and the check is
	// on the whole tree — a malformed path nested under an and/or branch is
	// still malformed.
	//
	// A backend MUST reject a malformed non-empty Path with an error. It MUST
	// NOT answer with an empty result set: a path the caller mistyped and a
	// predicate that genuinely matched nothing are different answers, and a
	// backend that conflates them makes a client error indistinguishable from
	// a legitimate empty page on that backend alone. Backends name this
	// sentinel ErrInvalidFilterPath. The in-process kernel (spi.Prepare)
	// enforces the same rejection — of an empty or malformed SourceData path,
	// and of an empty or non-vocabulary SourceMeta path — via
	// ErrUnevaluableLeaf, ahead of any backend-specific validation.
	Path string

	Source   FieldSource
	Value    any
	Values   []any
	Children []Filter
	Coercion FilterCoercion // temporal comparison routing (zero = CoerceNone)
	// Declared holds the leaf field's declared model DataTypes, stamped by the
	// domain layer from the model schema; the kernel uses them for
	// type-directed comparison. Empty for as-yet-unstamped or non-typed leaves.
	Declared []DataType
}

type FilterCoercion int

type FilterOp string

type GroupExpr struct {
	Kind GroupExprKind
	// Path is the JSONPath; only meaningful when Kind == GroupExprDataPath.
	Path string
}

type GroupExprKind int

type GroupKeyEntry struct {
	Path string
	// Value is the JSON-typed value: string for scalar/state values, nil
	// for missing/literal-null/non-scalar extracted values. Carried as any
	// rather than *string to leave room for non-string scalar key types in
	// future GroupExpr variants without breaking the SPI surface.
	Value any
}

type GroupedAggregateBucket struct {
	// GroupKey is ordered, matching the request groupBy order.
	GroupKey []GroupKeyEntry
	Count    int64
	// Aggregations maps alias to float64 or nil. nil means the bucket had
	// zero numeric samples for that field. Carried as any rather than
	// *float64 to leave room for future non-numeric aggregations (mode,
	// percentile_bucket, etc.) without breaking the SPI surface.
	Aggregations map[string]any
}

type GroupedAggregationsOptions struct {
	PointInTime *time.Time
	// MaxBuckets is the result cardinality ceiling. MUST be > 0; the SPI
	// does not define semantics for zero or negative values, and the
	// caller (typically the service layer) is responsible for applying a
	// default when the user omits the value. Implementations MUST return
	// ErrGroupCardinalityExceeded if the result would exceed this count.
	MaxBuckets   int
	Aggregations []AggregateExpr
}

type GroupedAggregator interface {
	GroupedAggregate(
		ctx context.Context,
		model ModelRef,
		groupBy []GroupExpr,
		filter Filter,
		opts GroupedAggregationsOptions,
	) ([]GroupedAggregateBucket, error)
}

type IterateOptions struct {
	// PointInTime, when non-nil, requests a historical snapshot at the
	// given instant. Semantics match the rest of the SPI (read-committed
	// snapshot): the read is COMMITTED-ONLY and ignores any ambient
	// transaction, so it never yields that transaction's own uncommitted
	// writes — see EntityStore.GetAsAt for the full statement, and note that
	// bounding the query on a timestamp is not sufficient to achieve it.
	PointInTime *time.Time

	// OrderBy specifies the sort keys applied to yielded entities. Empty
	// means order is unspecified — this differs from EntityStore.Search,
	// where an empty OrderBy still yields the engine's canonical entity-ID
	// order. See EntityStore.Iterate for which backends must honour a
	// non-empty OrderBy, and why a non-empty OrderBy with an ambient
	// transaction is an error.
	OrderBy []OrderSpec

	// TrackingRead, when true and a transaction is active, records the
	// entities this iteration yields into the transaction's read-set, so
	// commit-time first-committer-wins validates them. Default false: a
	// plain snapshot read that records nothing. No-op when no transaction
	// is active. Same rule as SearchOptions.TrackingRead.
	//
	// Yielded, not scanned: a row the filter excludes is never handed to the
	// caller and MUST NOT be recorded, whichever layer excluded it — a
	// storage predicate or the residual re-check inside Next(). See
	// SearchOptions.TrackingRead, which states the same rule for the matched
	// set it returns.
	TrackingRead bool
}

type Iterator interface {
	// Next advances the iterator. Returns false on end or sticky error.
	Next() bool
	// Entity returns the current row. Valid only after Next() == true.
	Entity() *Entity
	// Err returns the first error encountered. Sticky.
	Err() error
	// Close releases server resources. Idempotent.
	Close() error
}

type KeyValueStore interface {
	Put(ctx context.Context, namespace string, key string, value []byte) error
	Get(ctx context.Context, namespace string, key string) ([]byte, error)
	Delete(ctx context.Context, namespace string, key string) error
	List(ctx context.Context, namespace string) (map[string][]byte, error)
}

type MessageHeader struct {
	Subject         string
	ContentType     string
	ContentLength   int64
	ContentEncoding string
	MessageID       string // custom message ID from X-Message-ID header
	UserID          string
	Recipient       string
	ReplyTo         string
	CorrelationID   string
}

type MessageMetaData struct {
	Values        map[string]any
	IndexedValues map[string]any
}

type MessageStore interface {
	Save(ctx context.Context, id string, header MessageHeader, metaData MessageMetaData, payload io.Reader) error
	Get(ctx context.Context, id string) (MessageHeader, MessageMetaData, io.ReadCloser, error)
	Delete(ctx context.Context, id string) error
	DeleteBatch(ctx context.Context, ids []string) error
}

type MetaField struct {
	Source FieldSource
	Path   string
	Kind   OrderKind
}

type ModelDescriptor struct {
	Ref         ModelRef
	State       ModelState
	ChangeLevel ChangeLevel
	UpdateDate  time.Time
	Schema      []byte
	// UniqueKeys are the model's composite unique-key definitions. Additive;
	// persisted inside the descriptor by each model store. Empty = none.
	UniqueKeys []UniqueKey
}

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

type ModelRef struct {
	EntityName   string
	ModelVersion string
}

type ModelState string

type ModelStore interface {
	Save(ctx context.Context, desc *ModelDescriptor) error
	Get(ctx context.Context, modelRef ModelRef) (*ModelDescriptor, error)
	GetAll(ctx context.Context) ([]ModelRef, error)
	Delete(ctx context.Context, modelRef ModelRef) error
	Lock(ctx context.Context, modelRef ModelRef) error
	Unlock(ctx context.Context, modelRef ModelRef) error
	IsLocked(ctx context.Context, modelRef ModelRef) (bool, error)
	SetChangeLevel(ctx context.Context, modelRef ModelRef, level ChangeLevel) error
	// ExtendSchema appends a schema delta for the model at ref. The
	// delta is an opaque, plugin-agnostic blob that the plugin stores
	// verbatim in its extension log; folding the log into the current
	// schema is done on read via a plugin-injected ApplyFunc.
	//
	// Contract:
	//   - Success (nil return) means the extension is durably committed
	//     and visible to subsequent reads on this node.
	//   - A non-nil error means no persisted effect — no log entry,
	//     no savepoint, no partial state.
	//   - Plugins with a native conflict surface (sqlite SQLITE_BUSY,
	//     cassandra LWT applied:false) retry transparently up to a
	//     configurable budget. On exhaustion without ctx cancellation,
	//     return ErrRetryExhausted.
	//   - Context cancellation between retry attempts returns ctx.Err()
	//     (wrapped with attempt count), not ErrRetryExhausted. Mid-attempt
	//     cancellation follows backend-native behavior.
	//   - Plugins without a conflict surface (memory, postgres) commit
	//     immediately or fail with the backend's native error.
	//
	// Empty or nil deltas are a no-op and return nil.
	ExtendSchema(ctx context.Context, ref ModelRef, delta SchemaDelta) error
}

type NodeKind int

type NumericSubCondition struct {
	Type    DataType
	Value   Decimal
	Op      FilterOp
	NotNull bool
}

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

type OrderKind int

type OrderSpec struct {
	Path   string
	Source FieldSource
	Desc   bool
	Kind   OrderKind
}

type PathHop struct {
	Name string
	Subs []PathSub
}

type PathSub struct {
	Wildcard bool
	Index    int
}

type Plugin interface {
	Name() string
	NewFactory(ctx context.Context, getenv func(string) string, opts ...FactoryOption) (StoreFactory, error)
}

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

type Principal struct {
	ID   string        `json:"id"`
	Kind PrincipalKind `json:"kind"`
}

type PrincipalKind string

type ProcessorConfig struct {
	AttachEntity         bool   `json:"attachEntity,omitempty"`
	CalculationNodesTags string `json:"calculationNodesTags,omitempty"`
	ResponseTimeoutMs    int64  `json:"responseTimeoutMs,omitempty"`
	RetryPolicy          string `json:"retryPolicy,omitempty"`
	Context              string `json:"context,omitempty"`
	// StartNewTxOnDispatch, when true and ExecutionMode is COMMIT_BEFORE_DISPATCH,
	// causes the cascade engine to open a fresh transaction before dispatching
	// the processor (so the processor may perform transactional work via that
	// tx's token). When false (default) the processor runs with no transaction
	// context and the connection is released entirely during dispatch.
	// Ignored for any other ExecutionMode.
	StartNewTxOnDispatch *bool `json:"startNewTxOnDispatch,omitempty"`

	// AsyncResult, when true, requests that the cascade engine suspend
	// the transaction at processor dispatch and resume only when the
	// processor's result eventually arrives via the async-result
	// delivery slot. The runtime that implements this — durable
	// suspend state, work-stealing recovery, distributed timer
	// coordination — is gated on storage-engine primitives not
	// available in every backend. Consuming engines that do not
	// implement async-result semantics MUST reject this field at
	// import (or the equivalent configuration-boundary) rather than
	// silently degrade to synchronous dispatch.
	//
	// Pointer so that nil (absent) and &false (explicit no-async) are
	// distinguishable on the wire and round-trip byte-equivalent.
	AsyncResult *bool `json:"asyncResult,omitempty"`

	// CrossoverToAsyncMs is the timer, in milliseconds, after which
	// the engine crosses over from sync-wait to async-result delivery
	// for an AsyncResult=true processor. Effective only when
	// AsyncResult is true. Consuming engines that do not implement
	// async-result semantics MUST reject any non-nil value at import.
	CrossoverToAsyncMs *int64 `json:"crossoverToAsyncMs,omitempty"`
}

type ProcessorDefinition struct {
	// Type is the execution-location axis. Recognised values are defined
	// by the cyoda-go engine package; canonical values are "externalized"
	// (dispatched via gRPC to a calculation node selected by
	// Config.CalculationNodesTags) and "internalized" (reserved for an
	// in-process execution location, currently rejected at engine
	// dispatch as not yet implemented). Empty is treated as "externalized".
	// Any value other than "internalized" falls through to the
	// ExecutionMode dispatch path; import-time validation does not
	// constrain this field.
	Type          string          `json:"type"`
	Name          string          `json:"name"`
	ExecutionMode string          `json:"executionMode,omitempty"`
	Config        ProcessorConfig `json:"config,omitempty"`
	// Annotations is arbitrary client-owned metadata, stored and
	// round-tripped verbatim and never interpreted by the engine.
	// Well-known renderer keys (displayName, description) are a documented
	// convention only — the engine validates object-shape and size, not
	// the value types.
	Annotations json.RawMessage `json:"annotations,omitempty"`
}

type ReconcileRequest struct {
	TenantID     TenantID
	EntityID     string
	CurrentState string
	Arm          []ScheduledTask // tasks to Upsert (current state's schedules)
	// Cancel lists task IDs to delete for this transaction regardless of
	// SourceState, e.g. born-expired scheduled transitions computed by a
	// ScheduleFunction whose result already lies in the past. Audited
	// separately from the SourceState-mismatch cancels.
	Cancel []string
}

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

type ScheduleFunction struct {
	Name                 string `json:"name"`
	ResultKind           string `json:"resultKind"` // must be "Schedule"
	CalculationNodesTags string `json:"calculationNodesTags"`
	AttachEntity         bool   `json:"attachEntity"`
	Context              string `json:"context,omitempty"`
	ResponseTimeoutMs    int64  `json:"responseTimeoutMs,omitempty"`
}

type ScheduledTask struct {
	// ID is deterministic and engine-defined: the same
	// (tenant, entity, source state, transition) always derives the same
	// ID, so re-arming a still-scheduled transition upserts the existing
	// row in place instead of creating a duplicate. Tenant and entity are
	// incorporated so IDs can never collide across tenants or entities.
	// The exact derivation (hash inputs, encoding) is an engine-internal
	// detail, not part of this SPI's contract — stores must treat ID as
	// an opaque, stable key.
	ID       string            `json:"id"`
	TenantID TenantID          `json:"tenantId"`
	Type     ScheduledTaskType `json:"type"`
	// ScheduledTime is unix-millis; due when <= now.
	ScheduledTime int64 `json:"scheduledTime"`
	// TimeoutMs is the lateness tolerance in ms; nil = never expires.
	TimeoutMs *int64 `json:"timeoutMs,omitempty"`
	// RedispatchAfter is a unix-millis best-effort throttle; the scan
	// excludes rows still inside it. Not a lease, not conditional.
	RedispatchAfter *int64 `json:"redispatchAfter,omitempty"`

	// --- fire-transition payload ---
	EntityID     string `json:"entityId,omitempty"`
	ModelName    string `json:"modelName,omitempty"`
	ModelVersion int    `json:"modelVersion,omitempty"`
	Transition   string `json:"transition,omitempty"`
	SourceState  string `json:"sourceState,omitempty"`

	ArmedAt      int64 `json:"armedAt,omitempty"`
	AttemptCount int   `json:"attemptCount,omitempty"`

	// ArmedBy is the arming principal (chain origin at arm time, per the
	// follow-on-action attribution design); zero on legacy rows — fire
	// treats zero as the system principal. omitempty does not omit a zero
	// struct; readers rely on the zero-value check, never field absence.
	ArmedBy Principal `json:"armedBy,omitempty"`
}

type ScheduledTaskStore interface {
	Upsert(ctx context.Context, task ScheduledTask) error
	Get(ctx context.Context, id string) (task *ScheduledTask, found bool, err error)
	// ScanDue returns up to limit tasks with ScheduledTime <= nowMs AND
	// (RedispatchAfter is null OR <= nowMs), ordered by ScheduledTime, across tenants.
	ScanDue(ctx context.Context, nowMs int64, limit int) ([]ScheduledTask, error)
	// MarkRedispatch sets RedispatchAfter = redispatchAfterMs (plain write) and bumps AttemptCount.
	MarkRedispatch(ctx context.Context, id string, redispatchAfterMs int64) error
	// Delete removes the task, returning whether a row was actually removed
	// (delete-gated terminal audit relies on this).
	Delete(ctx context.Context, id string) (removed bool, err error)
	// ReconcileForEntity upserts req.Arm, deletes the entity's other-state
	// pending tasks, and additionally deletes the tasks listed in req.Cancel
	// (audited distinctly from the SourceState-mismatch cancels); returns
	// the deleted (cancelled) tasks.
	ReconcileForEntity(ctx context.Context, req ReconcileRequest) (cancelled []ScheduledTask, err error)
}

type ScheduledTaskType string

type SchemaDelta []byte

type SearchJob struct {
	ID       string
	TenantID TenantID
	Status   string // RUNNING, SUCCESSFUL, FAILED, CANCELLED
	ModelRef ModelRef

	// Condition is the client's predicate in the DOMAIN wire syntax
	// ([predicate.Condition] as JSON), deliberately NOT translated to a
	// [Filter]. It is the one plugin-facing field that carries domain syntax;
	// every other predicate surface here (EntityStore.Search,
	// EntityStore.Iterate, GroupedAggregate) takes a Filter.
	//
	// For a store the engine executes, this field is OPAQUE: persist it and
	// return it unchanged. The engine reads it back and translates it itself.
	//
	// For a [SelfExecutingSearchStore] it is the input to execution, and the
	// obligations on that interface apply — translate it with
	// [ConditionToFilter], do not parse or evaluate it independently.
	//
	// The shape is settled and permanent. Carrying a translated Filter here
	// instead was considered and rejected: [ConditionToFilter] and
	// [FieldsMapFromSchema] already live in this module, so a self-executing
	// store can translate with the kernel's own code, which is what actually
	// prevents divergence. Moving the translation to submission time would
	// also have to define what happens when a condition does not translate,
	// at the one point the engine has already stepped out.
	Condition json.RawMessage

	PointInTime time.Time
	SearchOpts  json.RawMessage
	ResultCount int
	Error       string
	CreateTime  time.Time
	FinishTime  *time.Time
	CalcTimeMs  int64

	// HeartbeatTime is the last liveness stamp from the owning executor.
	// nil means never stamped, in which case staleness is measured from
	// CreateTime (the baseline).
	HeartbeatTime *time.Time

	// Epoch is the claim/attempt counter. CreateJob persists 1 regardless
	// of the value set on the input job; ClaimStale increments it on each
	// successful claim. Callers fence writes (UpdateJobStatus, SaveResults,
	// Heartbeat) against the Epoch they were claimed with.
	Epoch int64

	// StaleClaims counts how many times ClaimStale took this job because
	// its heartbeat went stale — an executor lost without releasing. A
	// claim of a released job (see Release) does NOT count. CreateJob
	// persists 0 regardless of the value on the input job; ClaimStale
	// increments it, atomically with the claim, only for a staleness claim.
	// The engine's attempt cap bounds this counter, not Epoch, so a graceful
	// handoff (Release then claim) never advances a job toward being failed.
	StaleClaims int64
}

type SearchOptions struct {
	ModelName    string
	ModelVersion string
	PointInTime  *time.Time

	// Limit is a bounded-or-fail cap on the matched set. Limit >= 1 is
	// REQUIRED; Limit <= 0 is a contract violation and the implementation
	// MUST return an error. See EntityStore.Search's doc comment — the full
	// contract is load-bearing.
	Limit   int
	OrderBy []OrderSpec

	// TrackingRead, when true and a transaction is active, records the
	// entities this search returns into the transaction's read-set, so
	// commit-time first-committer-wins validates them (a FOR-SHARE / locking
	// read, implemented optimistically). Default false: a plain snapshot
	// predicate read that records nothing. No-op when no transaction is
	// active. In-transaction search never prevents phantoms regardless of
	// this flag (see cyoda-go's docs/CONSISTENCY.md).
	//
	// Returned, not scanned: a row the filter excludes is never handed to the
	// caller and MUST NOT be recorded, whichever layer excluded it — a
	// storage predicate or an in-process re-check. Recording a
	// scanned-but-excluded row aborts the transaction on a concurrent commit
	// it never had a reason to conflict with. IterateOptions.TrackingRead
	// carries the identical rule, per yielded row.
	TrackingRead bool
}

type SelfExecutingSearchStore interface {
	AsyncSearchStore
	SelfExecuting()
}

type Startable interface {
	Start(ctx context.Context) error
}

type StateDefinition struct {
	Transitions []TransitionDefinition `json:"transitions,omitempty"`
	// Annotations is arbitrary client-owned metadata, stored and
	// round-tripped verbatim and never interpreted by the engine.
	Annotations json.RawMessage `json:"annotations,omitempty"`
}

type StateMachineAuditStore interface {
	Record(ctx context.Context, entityID string, event StateMachineEvent) error
	GetEvents(ctx context.Context, entityID string) ([]StateMachineEvent, error)
	GetEventsByTransaction(ctx context.Context, entityID string, transactionID string) ([]StateMachineEvent, error)
}

type StateMachineEvent struct {
	EventType     StateMachineEventType `json:"eventType"`
	EntityID      string                `json:"entityId"`
	TimeUUID      string                `json:"timeUuid"`
	State         string                `json:"state,omitempty"`
	TransactionID string                `json:"transactionId,omitempty"`
	Details       string                `json:"details"`
	Data          map[string]any        `json:"data,omitempty"`
	Timestamp     time.Time             `json:"timestamp"`
}

type StateMachineEventType string

type StoreFactory interface {
	EntityStore(ctx context.Context) (EntityStore, error)
	ModelStore(ctx context.Context) (ModelStore, error)
	KeyValueStore(ctx context.Context) (KeyValueStore, error)
	MessageStore(ctx context.Context) (MessageStore, error)
	WorkflowStore(ctx context.Context) (WorkflowStore, error)
	StateMachineAuditStore(ctx context.Context) (StateMachineAuditStore, error)
	AsyncSearchStore(ctx context.Context) (AsyncSearchStore, error)
	// ScheduledTaskStore accesses durable scheduled tasks. Unlike the
	// per-tenant stores, its ScanDue is cross-tenant (obtain with a
	// background/tenant-less context); Upsert/Delete/Reconcile carry the
	// tenant on the task/request. Participates in the entity write's
	// transaction so arm/cancel are atomic with the state change.
	ScheduledTaskStore(ctx context.Context) (ScheduledTaskStore, error)
	TransactionManager(ctx context.Context) (TransactionManager, error)
	Close() error
}

type TemporalSubCondition struct {
	Type   DataType
	Millis int64
	Op     FilterOp
}

type TemporalValue struct {
	// Type is the subtype this value currently represents.
	Type DataType
	// contains filtered or unexported fields
}

type Tenant struct {
	ID   TenantID
	Name string
}

type TenantID string

type TransactionManager interface {
	// Begin starts a new transaction in the caller's tenant. Returns the
	// txID and a child context carrying the new TransactionState. After
	// Begin returns, the TransactionState's immutable fields (ID,
	// TenantID, SnapshotTime) are safe to read without locks.
	Begin(ctx context.Context) (txID string, txCtx context.Context, err error)

	// Commit closes the transaction and applies its buffered writes to
	// the underlying store. Commit acquires tx.OpMu.Lock for its
	// duration, so it waits for any in-flight tx-path operation on the
	// same tx (any SPI method invocation that holds OpMu.RLock) to drain
	// before mutating or closing tx state. Implementations must verify
	// that the caller's tenant matches tx.TenantID and reject
	// mismatched-tenant calls.
	Commit(ctx context.Context, txID string) error

	// Rollback closes the transaction and discards its buffered writes.
	// Acquires tx.OpMu.Lock; same tenant verification as Commit.
	Rollback(ctx context.Context, txID string) error

	// Join returns a context carrying the TransactionState for an existing
	// active transaction. Multiple goroutines may participate in the same
	// tx, but only one operation at a time per transaction:
	// application-side serialisation is required, per the Application
	// contract below and [TransactionState]'s concurrency contract
	// (cyoda-go serialises through its per-transaction gate).
	//
	// Two distinct contracts apply to a joined tx:
	//
	//   - Plugin contract (enforced by [TransactionState.OpMu]): the
	//     plugin's tx-path SPI methods hold OpMu.RLock; the plugin's
	//     closure SPI methods (Commit, Rollback, RollbackToSavepoint)
	//     hold OpMu.Lock. So closure waits for any in-flight SPI-method
	//     invocation to return before mutating or closing tx state. This
	//     contract covers SPI-method invocations only — application code
	//     that mutates tx state directly (e.g. through a [GetTransaction]
	//     handle) is outside the OpMu protection.
	//
	//   - Application contract (NOT enforced by the plugin): the
	//     application must serialise its own concurrent in-flight ops on
	//     the same tx. OpMu.RLock allows multiple readers concurrently;
	//     two RLock-holding ops (e.g. two Save calls from different
	//     goroutines) will trigger Go's "concurrent map writes" runtime
	//     fatal because both write to tx.Buffer / tx.WriteSet / tx.Deletes
	//     without mutual exclusion. RLock does not protect map writes from
	//     each other regardless of key overlap. The plugin does not detect
	//     or recover from this contract violation.
	//
	// Implementations must verify that the caller's tenant matches
	// tx.TenantID and reject mismatched-tenant joins. Implementations must
	// read tx.RolledBack and tx.Closed under tx.OpMu.RLock (not under the
	// manager mutex) — Commit's deferred Closed-write runs outside the
	// manager-mutex region.
	Join(ctx context.Context, txID string) (txCtx context.Context, err error)

	GetSubmitTime(ctx context.Context, txID string) (time.Time, error)

	// Savepoint creates a named savepoint within the given transaction by
	// snapshotting tx.Buffer / tx.ReadSet / tx.WriteSet / tx.Deletes, with
	// tx.DeleteAttribution snapshotted paired with tx.Deletes.
	//
	// Locking discipline: read-only on tx state. Implementations must
	// acquire tx.OpMu.RLock for the snapshot read so the operation is
	// serialised against Commit/Rollback (which take tx.OpMu.Lock)
	// without blocking other in-flight readers.
	//
	// Tenant isolation: implementations must reject calls whose
	// UserContext tenant does not match tx.TenantID.
	Savepoint(ctx context.Context, txID string) (savepointID string, err error)

	// RollbackToSavepoint rolls back all work done since the savepoint was
	// created by replacing tx.Buffer / tx.ReadSet / tx.WriteSet /
	// tx.Deletes with the snapshot taken at Savepoint time, restoring
	// tx.DeleteAttribution paired with tx.Deletes.
	//
	// Locking discipline: write on tx state — exclusive against every
	// other tx-path op. Implementations must acquire tx.OpMu.Lock (write
	// lock, not RLock) for the duration of the field replacement.
	//
	// Tenant isolation: implementations must reject mismatched-tenant
	// callers — RollbackToSavepoint is destructive on tx-state.
	RollbackToSavepoint(ctx context.Context, txID string, savepointID string) error

	// ReleaseSavepoint releases a savepoint, merging its work into the
	// parent transaction. The work done since the savepoint already lives
	// in tx.Buffer / tx.ReadSet / tx.WriteSet / tx.Deletes / tx.DeleteAttribution
	// — Release only removes the snapshot record from manager-side state.
	//
	// Locking discipline: does not touch any field of TransactionState
	// (only manager-side savepoint records). Implementations need only
	// the manager mutex; tx.OpMu is not required.
	//
	// Tenant isolation: implementations must reject mismatched-tenant
	// callers — manager-side savepoint state is tenant-scoped.
	ReleaseSavepoint(ctx context.Context, txID string, savepointID string) error
}

type TransactionState struct {
	ID           string
	TenantID     TenantID
	SnapshotTime time.Time
	Origin       Principal          // attribution root for the tx; immutable after Begin (see godoc above)
	ReadSet      map[string]bool    // entity IDs read; access under OpMu (see godoc)
	WriteSet     map[string]bool    // entity IDs written; access under OpMu
	Buffer       map[string]*Entity // staged writes; access under OpMu
	// Deletes and DeleteAttribution are the buffering mechanism: backends
	// that stage deletes in TransactionState (e.g. memory, sqlite) use
	// these maps to carry staging + attribution through to the commit-time
	// flush, and populate them at delete-stage time; access under OpMu.
	// Backends whose delete staging/visibility is instead governed by the
	// underlying store (e.g. postgres, via immediate DML under a SQL
	// SAVEPOINT) stamp attribution directly at delete time and MAY leave
	// these maps unpopulated — that is not a bug. The conformance contract
	// is the committed outcome (GetVersionMetadata's tombstone row), never
	// these maps' contents; do not assert on them from backend-agnostic tests.
	Deletes           map[string]bool             // staged deletes; access under OpMu
	DeleteAttribution map[string]WriteAttribution // entityID → actors for staged deletes; same OpMu posture as Deletes
	RolledBack        bool                        // closure flag; written under OpMu.Lock, read under OpMu.RLock
	OpMu              sync.RWMutex                // see TransactionState godoc above for full contract
	Closed            bool                        // closure flag; written under OpMu.Lock, read under OpMu.RLock
}

type TransitionDefinition struct {
	Name       string                `json:"name"`
	Next       string                `json:"next"`
	Manual     bool                  `json:"manual"`
	Disabled   bool                  `json:"disabled,omitempty"`
	Criterion  json.RawMessage       `json:"criterion,omitempty"`
	Processors []ProcessorDefinition `json:"processors,omitempty"`
	Schedule   *TransitionSchedule   `json:"schedule,omitempty"`
	// Annotations is arbitrary client-owned metadata, stored and
	// round-tripped verbatim and never interpreted by the engine.
	Annotations json.RawMessage `json:"annotations,omitempty"`
	// CriterionAnnotations is client-owned metadata describing this
	// transition's guard Criterion as a whole. Sibling to Criterion;
	// engine-ignored. See WorkflowDefinition.CriterionAnnotations.
	CriterionAnnotations json.RawMessage `json:"criterionAnnotations,omitempty"`
}

type TransitionSchedule struct {
	// DelayMs is the delay between source-state entry and the
	// scheduled execution time, in milliseconds. Must be > 0.
	DelayMs int64 `json:"delayMs"`

	// TimeoutMs is the late-tolerance window past the scheduled
	// execution time, in milliseconds. Nil means no timeout — the
	// task fires whenever the scheduler eventually picks it up.
	// Non-nil zero is the strictest setting — drop on any lateness.
	// Non-nil positive N drops the task if it picks up more than N
	// milliseconds after scheduledTime. Independent of DelayMs; the
	// two measure different quantities.
	TimeoutMs *int64 `json:"timeoutMs,omitempty"`

	// Function configures a Function callout that computes the firing
	// time (and optional expiry) per entity instead of a static DelayMs.
	// Mutually exclusive with DelayMs (enforced by the engine at import).
	Function *ScheduleFunction `json:"function,omitempty"`
}

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

type UUIDGenerator interface {
	NewTimeUUID() [16]byte
}

type UniqueClaim struct {
	KeyID     string
	Signature string
}

type UniqueKey struct {
	ID     string
	Fields []string
}

type UserContext struct {
	UserID   string
	UserName string
	Kind     PrincipalKind
	Tenant   Tenant
	Roles    []string
}

type VersionMetadataOptions struct {
	// From, Until bound the returned window inclusively; a nil side is
	// unbounded.
	From, Until *time.Time
	// Limit caps the number of returned rows. 0 means all — unlike
	// GetPage, 0 is a valid "unbounded" value here, deliberately: the
	// result is bounded by one entity's own version history, not an
	// unbounded model-wide scan. See GetVersionMetadata's doc comment.
	Limit int
}

type WorkflowDefinition struct {
	Version      string                     `json:"version"`
	Name         string                     `json:"name"`
	Description  string                     `json:"desc,omitempty"`
	InitialState string                     `json:"initialState"`
	Active       bool                       `json:"active"`
	Criterion    json.RawMessage            `json:"criterion,omitempty"`
	States       map[string]StateDefinition `json:"states"`
	// Annotations is arbitrary client-owned metadata, stored and
	// round-tripped verbatim and never interpreted by the engine.
	Annotations json.RawMessage `json:"annotations,omitempty"`
	// CriterionAnnotations is client-owned metadata describing the
	// workflow-selection Criterion as a whole (a sibling to Criterion,
	// because the criterion value is opaque and round-trips verbatim).
	// Same bag shape as Annotations; engine-ignored.
	CriterionAnnotations json.RawMessage `json:"criterionAnnotations,omitempty"`
}

type WorkflowStore interface {
	Save(ctx context.Context, modelRef ModelRef, workflows []WorkflowDefinition) error
	Get(ctx context.Context, modelRef ModelRef) ([]WorkflowDefinition, error)
	Delete(ctx context.Context, modelRef ModelRef) error
}

type WriteAttribution struct {
	Attributed Principal
	Executor   Principal
}