domain

type BasicTripleEvent struct {
	Subject   string `json:"subject"`
	Predicate string `json:"predicate"`
	Object    string `json:"object"`
	Original  int64  `json:"original"`
}

type Entity interface {
	// GetID returns the aggregate ID of the entity.
	GetID() string

	// GetSequenceNo returns the last event sequence number from when the entity was hydrated.
	GetSequenceNo() int

	// GetUncommittedEvents returns all uncommitted events that have been recorded but not yet persisted.
	GetUncommittedEvents() []EventEnvelope[any]

	// ClearUncommittedEvents removes all uncommitted events, typically called after successful persistence.
	ClearUncommittedEvents()
}

type Event interface {
	GetID() string
	GetSequenceNo() int
}

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

type EventEnvelope[T any] struct {
	ID            string                 `json:"id"`
	AggregateID   string                 `json:"aggregate_id"`
	EventType     string                 `json:"event_type"`
	Payload       T                      `json:"payload"`
	Created       time.Time              `json:"timestamp"`
	SequenceNo    int                    `json:"sequence_no"`
	TransactionID string                 `json:"transaction_id,omitempty"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`

	// Position is the event's place in the store's global, cross-aggregate
	// commit order. It is assigned by the event store at persistence time and
	// populated on reads; it is zero on envelopes that have not been persisted
	// (or that were stored before global ordering existed and have not been
	// backfilled). Positions are strictly increasing but not necessarily dense.
	Position int64 `json:"position,omitempty"`
}

type EventHandler[T any] func(ctx context.Context, env EventEnvelope[T]) error

type EventStore interface {
	// Append appends one or more events to the event store for a given aggregate.
	// It returns an error if the expected version doesn't match (optimistic concurrency control).
	// If expectedVersion is -1, no version check is performed.
	Append(ctx context.Context, aggregateID string, expectedVersion int, events ...EventEnvelope[any]) error

	// GetEvents retrieves all events for a given aggregate ID.
	// Returns an empty slice if no events are found.
	GetEvents(ctx context.Context, aggregateID string) ([]EventEnvelope[any], error)

	// GetEventsFromVersion retrieves events for an aggregate starting from a specific version.
	// Returns an empty slice if no events are found.
	GetEventsFromVersion(ctx context.Context, aggregateID string, fromVersion int) ([]EventEnvelope[any], error)

	// GetEventsRange retrieves events for an aggregate within a version range.
	// If fromVersion is -1, it defaults to version 1 (the first event).
	// If toVersion is -1, it retrieves all events from fromVersion to the end.
	// Returns an empty slice if no events are found in the range.
	GetEventsRange(ctx context.Context, aggregateID string, fromVersion, toVersion int) ([]EventEnvelope[any], error)

	// GetEventByID retrieves a specific event by its ID.
	// Returns ErrEventNotFound if the event doesn't exist.
	GetEventByID(ctx context.Context, eventID string) (EventEnvelope[any], error)

	// GetEventsByTransactionID retrieves all events that share the given transaction ID,
	// ordered by aggregate ID then sequence number.
	// transactionID must not be empty; implementations return ErrInvalidEvent if it is.
	// Returns an empty slice if no events are found.
	GetEventsByTransactionID(ctx context.Context, transactionID string) ([]EventEnvelope[any], error)

	// GetCurrentVersion returns the current version number for an aggregate.
	// Returns 0 if the aggregate doesn't exist.
	GetCurrentVersion(ctx context.Context, aggregateID string) (int, error)

	// ReadAfter returns committed events across all aggregates whose global
	// Position is greater than afterPosition, ordered by Position ascending.
	// At most limit events are returned; limit <= 0 means no limit.
	//
	// The result is safe to use as a resumable feed: once an event is
	// returned, no event with a smaller Position will ever appear in a later
	// call. Implementations backed by databases with concurrent writers must
	// withhold events whose positions are visible before an earlier-position
	// transaction has committed. The cost of that guarantee is liveness, not
	// correctness: a long-running write transaction anywhere in the database
	// delays the feed (an empty result can mean "caught up" or "withheld
	// behind an in-flight writer").
	//
	// Stores without a global ordering return ErrGlobalOrderingNotSupported.
	ReadAfter(ctx context.Context, afterPosition int64, limit int) ([]EventEnvelope[any], error)

	// HeadPosition returns the highest Position that ReadAfter could
	// currently deliver (0 when the store is empty). Feed consumers use it to
	// measure lag against their checkpoint.
	//
	// Stores without a global ordering return ErrGlobalOrderingNotSupported.
	HeadPosition(ctx context.Context) (int64, error)

	// Close closes the event store and releases any resources.
	Close() error
}