persis

type Backend interface {
	// Collection returns the collection with the given name.
	// Multiple calls with the same name return the same logical namespace.
	Collection(name string) Collection

	// Close releases all resources held by the backend (file handles,
	// connection pools, etc.). No Collection method may be called after Close.
	Close() error
}

type Collection interface {
	// Get returns the record identified by id.
	// Returns [ErrNotFound] if no record with that id exists.
	Get(ctx context.Context, id string) (*Record, error)

	// Put creates or replaces a record.
	Put(ctx context.Context, rec *Record) error

	// Create atomically inserts rec. Returns [ErrConflict] when a record with
	// rec.ID already exists. Backends must guarantee the check-and-insert is
	// atomic with respect to concurrent Put, CompareAndSwap, and Create calls.
	Create(ctx context.Context, rec *Record) error

	// Delete removes the record with the given id.
	// Returns nil if the record does not exist.
	Delete(ctx context.Context, id string) error

	// CompareAndDelete atomically removes expected.ID only when the current
	// record still matches expected. Returns [ErrConflict] when it does not.
	CompareAndDelete(ctx context.Context, expected *Record) error

	// List returns a page of records matching q, ordered by CreatedAt ascending.
	List(ctx context.Context, q ListQuery) (*Page, error)

	// CompareAndSwap atomically replaces record id only when its current Data
	// bytes equal expected. Returns [ErrConflict] when they do not match.
	// Used for optimistic concurrency on DAGRunStatus updates.
	CompareAndSwap(ctx context.Context, id string, expected, next []byte) error
}

type ListQuery struct {
	// Prefix filters records whose ID starts with this string.
	// An empty Prefix returns all records in the collection.
	Prefix string

	// Since and Until bound results by Record.CreatedAt.
	Since *time.Time
	Until *time.Time

	// Cursor resumes a previous [Page] iteration.
	// Pass [Page.NextCursor] from the prior call; empty starts from the beginning.
	Cursor string

	// Limit caps the number of records returned. 0 = backend default.
	Limit int
}

type Page struct {
	Records    []*Record
	NextCursor string // empty when no further records exist
}

type Record struct {
	ID        string
	Data      []byte
	CreatedAt time.Time
	UpdatedAt time.Time
}