history

type Action string

type CRUD[T any, ID comparable] struct {
	// contains filtered or unexported fields
}

type ChangeRecord struct {
	// ID is the unique identifier for this change record (UUID).
	ID string `json:"id" db:"id,pk" bson:"_id"`

	// RecordType is the type name of the entity (e.g. "orders", "campaigns").
	// Derived automatically from the struct type or set explicitly via options.
	RecordType string `json:"record_type" db:"record_type" bson:"record_type"`

	// RecordID is the primary key of the entity, stringified.
	RecordID string `json:"record_id" db:"record_id" bson:"record_id"`

	// Action is the type of mutation (create, update, patch, delete, revert).
	Action Action `json:"action" db:"action" bson:"action"`

	// ActorID identifies who performed the change (e.g. user ID, API key ID).
	// It is a first-class, indexable column — resolved from r3.GetActor(ctx) —
	// so the activity log can be filtered/grouped by actor ("show everything
	// user 7 did") without reaching into the Metadata JSON blob. Empty for the
	// system/anonymous actor.
	ActorID string `json:"actor_id,omitempty" db:"actor_id" bson:"actor_id,omitempty"`

	// ActorType categorizes the actor (e.g. "user", "system", "api_key", "cron").
	// First-class column alongside ActorID; resolved from r3.GetActor(ctx).
	ActorType string `json:"actor_type,omitempty" db:"actor_type" bson:"actor_type,omitempty"`

	// Version is a monotonically increasing counter per (record_type, record_id).
	// Version 1 is always the initial create. This enables ordered history
	// and "revert to version N" functionality.
	Version int64 `json:"version" db:"version" bson:"version"`

	// Changes contains the field-level diff for this mutation.
	// For create: each field appears with OldValue=nil and NewValue=<value>.
	// For delete: each field appears with OldValue=<value> and NewValue=nil.
	// For update/patch: only changed fields appear.
	// For revert: the diff between pre-revert state and the reverted-to state.
	//
	// State reconstruction (Reverter.Reconstruct) works purely from diffs:
	// version 1 (create) always contains every field, so replaying from v1
	// forward reconstructs any historical state without needing snapshots.
	//
	// Stored as a JSON blob in SQL databases via JSONColumn.
	Changes r3.JSONColumn[[]FieldChange] `json:"changes" db:"changes" bson:"changes"`

	// ParentType is the record type of the parent entity (for tree queries).
	// Empty if this entity has no parent. Example: "campaigns" for an adset.
	ParentType string `json:"parent_type,omitempty" db:"parent_type" bson:"parent_type,omitempty"`

	// ParentID is the primary key of the parent entity, stringified.
	// Empty if this entity has no parent.
	ParentID string `json:"parent_id,omitempty" db:"parent_id" bson:"parent_id,omitempty"`

	// EventType, when non-empty, marks this entry as a domain or synthetic
	// *event* on the entity's timeline (Action is ActionEvent) rather than a
	// field-level mutation — e.g. "activity_logging_started", "comment_added".
	// Changes is usually empty for events; EventData carries any structured
	// payload. This makes the activity log a single timeline of changes AND
	// events, queried and ordered together.
	EventType string `json:"event_type,omitempty" db:"event_type" bson:"event_type,omitempty"`

	// EventData is an optional structured payload for an event (e.g. the comment
	// text, the signer). Stored as a JSON blob via JSONColumn.
	EventData r3.JSONColumn[map[string]any] `json:"event_data" db:"event_data" bson:"event_data,omitempty"`

	// Synthetic marks a record that was reconstructed rather than observed — e.g.
	// a backfilled "create" inferred from an entity's CURRENT state because
	// tracking began after the entity already existed. Its Changes are
	// best-effort, not the values at the original mutation.
	Synthetic bool `json:"synthetic,omitempty" db:"synthetic" bson:"synthetic,omitempty"`

	// Note is an optional human remark shown alongside the entry (e.g. why a
	// record is synthetic).
	Note string `json:"note,omitempty" db:"note" bson:"note,omitempty"`

	// Metadata carries contextual information about who made the change and why.
	// Stored as a JSON blob in SQL databases via JSONColumn.
	Metadata r3.JSONColumn[Metadata] `json:"metadata" db:"metadata" bson:"metadata"`

	// CreatedAt is the timestamp when this change was recorded.
	CreatedAt time.Time `json:"created_at" db:"created_at" bson:"created_at"`
}

type DiffFunc[T any] func(old, cur T) []FieldChange

type FieldChange struct {
	// Field is the column/field name that changed (dot-notation for nested structs).
	Field string `json:"field"`

	// OldValue is the previous value (nil for create).
	OldValue any `json:"old_value"`

	// NewValue is the new value (nil for delete).
	NewValue any `json:"new_value"`
}

type IDFunc[T any, ID comparable] func(entity T) ID

type Metadata struct {
	// Source describes where the change originated (e.g. "api", "admin_ui", "worker").
	Source string `json:"source,omitempty"`

	// Extra holds arbitrary key-value pairs for additional context
	// (e.g. request_id, ip_address, user_agent).
	Extra map[string]string `json:"extra,omitempty"`
}

type MetadataFunc func(ctx context.Context) Metadata

type Option[T any, ID comparable] func(*Options[T, ID])

type Options[T any, ID comparable] struct {
	// RecordType is the name used to identify this entity type in change records.
	// If empty, it is derived automatically from the struct type T
	// (e.g. Order -> "orders", CampaignAdset -> "campaign_adsets").
	RecordType string

	// MetadataFunc extracts surrounding-context metadata (Source, Extra) from the
	// request context. The actor is always recorded independently as the
	// first-class ChangeRecord.ActorID/ActorType fields, resolved from
	// r3.GetActor(ctx) — MetadataFunc does not affect it.
	MetadataFunc MetadataFunc

	// FixedActor, when set, attributes every change recorded by this decorator to
	// the given actor, ignoring r3.GetActor(ctx). Use it for a repository whose
	// writes are always one identity — e.g. a system/worker repo where mutations
	// run on background contexts that carry no principal. When nil (default), the
	// actor is resolved from the context per-call.
	FixedActor *r3.Actor

	// DiffFunc provides a custom diff implementation.
	// If nil, the default reflection-based Diff[T] is used.
	DiffFunc DiffFunc[T]

	// IDFunc extracts the primary key from an entity.
	// This is required — the decorator needs to know how to get the ID
	// from an entity for fetching the old state before updates.
	IDFunc IDFunc[T, ID]

	// ParentRef links this entity to a parent for tree queries.
	// If nil, change records will not include parent information.
	ParentRef *ParentRef

	// SnapshotRules defines conditions under which full entity snapshots
	// are taken and stored in a separate SnapshotStore. Snapshots are
	// completely decoupled from change records — they have their own
	// storage (separate table/collection) and custom trigger conditions.
	//
	// Example: snapshot a BenefitSheet when status changes from "draft" to "published".
	SnapshotRules []SnapshotRule[T]

	// Async when true records history in a background goroutine.
	// The CRUD operation returns immediately; history recording errors are
	// reported via ErrorHandler but never affect the CRUD result (FailOnError is
	// ignored in async mode). Default: false (synchronous).
	Async bool

	// ErrorHandler is invoked when writing a change record fails. It makes the
	// handling of a failed audit write explicit and overridable. If nil, the
	// failure is logged via slog. It does not control whether the operation
	// fails — see FailOnError.
	ErrorHandler func(error)

	// FailOnError, in synchronous mode, makes a failed change-record write return
	// its error from the CRUD operation instead of only being reported. This
	// surfaces audit gaps to the caller.
	//
	// NOTE: history is recorded after the underlying mutation succeeds, so when
	// this fires the entity change has ALREADY been applied; the returned error
	// signals that the change could not be audited, not that the mutation was
	// rolled back. For atomic audit, run the operation inside a transaction.
	// Ignored in async mode. Default: false.
	FailOnError bool
}

type ParentRef struct {
	// ParentType is the RecordType of the parent entity (e.g. "campaigns").
	ParentType string

	// FKField is the Go struct field name on the child that holds the parent's ID
	// (e.g. "CampaignID"). The decorator reads this field via reflection to populate
	// ParentID on each change record.
	FKField string
}

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

type RetentionPolicy struct {
	// MaxAge is the maximum age of change records. Records older than this
	// are deleted during enforcement. Zero means no age-based retention.
	MaxAge time.Duration

	// MaxVersions is the maximum number of versions to keep per entity.
	// When exceeded, the oldest versions are deleted first.
	// Zero means no version-based limit.
	MaxVersions int64
}

type Reverter[T any, ID comparable] struct {
	// contains filtered or unexported fields
}

type Snapshot struct {
	// ID is the unique identifier for this snapshot.
	ID string `json:"id" db:"id,pk" bson:"_id"`

	// RecordType is the type name of the entity (e.g. "benefit_sheets").
	RecordType string `json:"record_type" db:"record_type" bson:"record_type"`

	// RecordID is the primary key of the entity, stringified.
	RecordID string `json:"record_id" db:"record_id" bson:"record_id"`

	// Version is the change record version that triggered this snapshot.
	Version int64 `json:"version" db:"version" bson:"version"`

	// RuleName identifies which SnapshotRule triggered this snapshot.
	// Useful when multiple rules exist for the same entity type.
	RuleName string `json:"rule_name,omitempty" db:"rule_name" bson:"rule_name,omitempty"`

	// ActorID / ActorType identify who triggered the snapshot, mirrored from the
	// change record that produced it (resolved from r3.GetActor(ctx)).
	ActorID   string `json:"actor_id,omitempty"   db:"actor_id"   bson:"actor_id,omitempty"`
	ActorType string `json:"actor_type,omitempty" db:"actor_type" bson:"actor_type,omitempty"`

	// Data is the full serialized state of the entity at snapshot time.
	// Stored as JSON bytes for portability across storage backends.
	Data json.RawMessage `json:"data" db:"data" bson:"data"`

	// Metadata carries contextual information (same as on the change record).
	// Stored as a JSON blob in SQL databases via JSONColumn.
	Metadata r3.JSONColumn[Metadata] `json:"metadata" db:"metadata" bson:"metadata"`

	// CreatedAt is the timestamp when the snapshot was taken.
	CreatedAt time.Time `json:"created_at" db:"created_at" bson:"created_at"`
}

type SnapshotConditionFunc[T any] func(action Action, old, cur T) bool

type SnapshotRule[T any] struct {
	// Name identifies this rule (for logging and the RuleName field on Snapshot).
	Name string

	// Store is where snapshots triggered by this rule are persisted.
	// Only [r3.Commander] is required — snapshots are only written, never read back
	// through this interface. Any r3.CRUD also satisfies Commander.
	Store r3.Commander[Snapshot, string]

	// Condition determines whether a snapshot should be taken.
	// If nil, the rule never triggers (effectively disabled).
	Condition SnapshotConditionFunc[T]
}

type TreeScope struct {
	// RecordType is the entity type to match (e.g. "campaigns", "adsets").
	RecordType string

	// RecordID limits to a specific entity instance. Empty means all of this type.
	RecordID string

	// ParentType scopes to children of a specific parent type.
	// Empty means this is a root scope (match by RecordType/RecordID only).
	ParentType string

	// ParentID scopes to children of a specific parent instance.
	// Empty with a non-empty ParentType means all children of that parent type.
	ParentID string
}