history

type Action string

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

type ChangeRecord struct {
	// ID uniquely identifies this record (UUID).
	ID string `json:"id" db:"id,pk" bson:"_id"`

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

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

	// Action is the mutation type.
	Action Action `json:"action" db:"action" bson:"action"`

	// ActorID identifies who made the change (resolved from r3.GetActor(ctx)). A
	// first-class indexable column, not part of Metadata, so the log can be
	// filtered/grouped by actor. 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"); first-class column
	// alongside ActorID.
	ActorType string `json:"actor_type,omitempty" db:"actor_type" bson:"actor_type,omitempty"`

	// Version is a monotonic counter per (record_type, record_id); version 1 is
	// always the create. Enables ordered history and revert-to-version.
	Version int64 `json:"version" db:"version" bson:"version"`

	// Changes is the field-level diff: create -> every field with OldValue=nil;
	// delete -> every field with NewValue=nil; update/patch -> only changed fields;
	// revert -> pre-revert vs reverted-to. Reconstruction ([Reverter.Reconstruct])
	// works purely from diffs because v1 always carries every field. Stored as JSON.
	Changes r3.JSONColumn[[]FieldChange] `json:"changes" db:"changes" bson:"changes"`

	// ParentType is the parent entity's record type (for tree queries); empty if
	// no parent.
	ParentType string `json:"parent_type,omitempty" db:"parent_type" bson:"parent_type,omitempty"`

	// ParentID is the parent primary key, stringified; empty if no parent.
	ParentID string `json:"parent_id,omitempty" db:"parent_id" bson:"parent_id,omitempty"`

	// EventType, when non-empty, marks this entry as a timeline event (Action is
	// ActionEvent) rather than a field mutation - e.g. "comment_added". Changes is
	// usually empty; EventData carries the payload. Changes and events share one
	// ordered timeline.
	EventType string `json:"event_type,omitempty" db:"event_type" bson:"event_type,omitempty"`

	// EventData is an optional structured event payload. Stored as JSON.
	EventData r3.JSONColumn[map[string]any] `json:"event_data" db:"event_data" bson:"event_data,omitempty"`

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

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

	// Metadata carries surrounding context (source, request correlation). Stored as
	// JSON.
	Metadata r3.JSONColumn[Metadata] `json:"metadata" db:"metadata" bson:"metadata"`

	// CreatedAt is when the 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 changed column/field name (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 is where the change originated (e.g. "api", "admin_ui", "worker").
	Source string `json:"source,omitempty"`

	// Extra holds arbitrary context pairs (e.g. request_id, ip_address).
	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 identifies this entity type in change records. If empty, derived
	// from T (e.g. Order -> "orders", OrderItem -> "order_items").
	RecordType string

	// MetadataFunc extracts surrounding-context metadata; it does not affect the
	// actor, which is a first-class field resolved from r3.GetActor(ctx).
	MetadataFunc MetadataFunc

	// FixedActor, when set, attributes every change to this actor instead of
	// r3.GetActor(ctx). Use for a system/worker repo whose background contexts
	// carry no principal. Nil resolves the actor per-call from context.
	FixedActor *r3.Actor

	// DiffFunc overrides the default reflection-based Diff[T].
	DiffFunc DiffFunc[T]

	// IDFunc extracts the primary key. Required - needed to fetch old state before
	// updates.
	IDFunc IDFunc[T, ID]

	// ParentRef links this entity to a parent for tree queries; nil omits parent
	// info.
	ParentRef *ParentRef

	// SnapshotRules gate opt-in full-entity snapshots, stored separately from
	// change records with their own trigger conditions. See [SnapshotRule].
	SnapshotRules []SnapshotRule[T]

	// Async records history in a background goroutine; the CRUD op returns
	// immediately and recording errors go to ErrorHandler only (FailOnError is
	// ignored). Default false.
	Async bool

	// ErrorHandler is invoked on a failed change-record write, overriding the
	// default slog logging. It does not control whether the op fails - see
	// FailOnError.
	ErrorHandler func(error)

	// FailOnError (sync mode) returns a failed change-record write's error from the
	// CRUD op, surfacing audit gaps.
	//
	// NOTE: history is recorded AFTER the mutation succeeds, so when this fires the
	// change has already been applied; the error signals it could not be audited,
	// not that the mutation rolled back. For atomic audit, use a transaction.
	// Ignored in async mode. Default false.
	FailOnError bool
}

type ParentRef struct {
	// ParentType is the parent entity's RecordType (e.g. "cities").
	ParentType string

	// FKField is the child's Go struct field holding the parent ID (e.g.
	// "CityID"), read via reflection to populate ParentID.
	FKField string
}

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

type RetentionPolicy struct {
	// MaxAge deletes records older than this during enforcement.
	MaxAge time.Duration

	// MaxVersions caps versions kept per entity; the oldest are pruned first.
	MaxVersions int64
}

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

type Snapshot struct {
	// ID uniquely identifies this snapshot.
	ID string `json:"id" db:"id,pk" bson:"_id"`

	// RecordType is the entity type name.
	RecordType string `json:"record_type" db:"record_type" bson:"record_type"`

	// RecordID is the entity primary key, 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 is which SnapshotRule fired (disambiguates multiple rules per type).
	RuleName string `json:"rule_name,omitempty" db:"rule_name" bson:"rule_name,omitempty"`

	// ActorID / ActorType mirror the triggering change record.
	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 entity state at snapshot time, JSON bytes for portability.
	Data json.RawMessage `json:"data" db:"data" bson:"data"`

	// Metadata mirrors the change record's context. Stored as JSON.
	Metadata r3.JSONColumn[Metadata] `json:"metadata" db:"metadata" bson:"metadata"`

	// CreatedAt is 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 (logging and Snapshot.RuleName).
	Name string

	// Store persists snapshots from this rule. Only [r3.Commander] is required -
	// snapshots are write-only here.
	Store r3.Commander[Snapshot, string]

	// Condition gates the snapshot; nil disables the rule.
	Condition SnapshotConditionFunc[T]
}

type TreeScope struct {
	// RecordType is the entity type to match.
	RecordType string

	// RecordID limits to one instance; empty means all of this type.
	RecordID string

	// ParentType scopes to children of a parent type; empty means a root scope.
	ParentType string

	// ParentID scopes to children of a parent instance; empty with a set
	// ParentType means all children of that type.
	ParentID string
}