capledger

type Config struct {
	// Store is the journal the ledger writes.
	Store Store
	// Encode maps a free-text name to a key segment that carries none of the characters run IDs are
	// built with (agent's encodeID).
	Encode func(string) string
	// Clock reads now. It is read at a first intent only.
	Clock func() time.Time
	// Bound is how many windows later than the newest recorded one a first intent's window may be
	// (default one).
	Bound int
	// MaxRetries bounds the lost slot inserts of one reservation or release (default 1000): a loser
	// reads again, so contention costs a retry, and past the bound the call fails closed.
	MaxRetries int
	// MaxViews bounds the ledger runs whose reads are cached (default 256): the least recently used is
	// dropped, and read again from the store when next needed. The cache is a hint, so dropping one costs a read.
	MaxViews int
}

type Intent struct {
	Attempt   string
	Namespace string
	Rule      string
	Currency  string
	Kind      Kind
	Key       string
	Amount    int64
	Marked    bool
	Window    string
	Floor     string
}

type Item struct {
	Seq  int64
	Name string
	Data []byte
}

type Kind string

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

type Outcome struct {
	Ledger string // the ledger run
	Window string
	Slot   Slot
	// Resumed says the attempt already held a live slot (a retry, a resume or a second driver).
	Resumed bool
}

type OverLimitError struct {
	Cum, Amount, Limit int64
}

type Release struct {
	Attempt string
	Why     string
}

type Request struct {
	Rule Rule
	// KeyDigest is KeyDigest of the normalized key the rule is by ("" digests as the unkeyed total).
	KeyDigest string
	// RunID is the run whose journal holds the attempt's cap-intent and cap-reserve: the run that made the call.
	RunID string
	// RootRunID is the root of the run's tree: the window id of a Run window.
	RootRunID string
	// ToolUseID and AttemptID identify the attempt with RootRunID. The ledger encodes and joins them
	// itself (AttemptKey), so no choice of the three can make one attempt's key another's. A retry of
	// the same attempt, a resume, a second driver and a middleware's second next carry the same three.
	ToolUseID string
	AttemptID string
	// Marked says the attempt has an exclusive claim (a tool that is not retry-safe). Only a marked
	// attempt is ever released.
	Marked bool
	// Amount is what the attempt reserves, in minor units: positive. Reserving zero counts nothing and
	// a negative amount would give room back, so both are refused (ErrInvalid); the call site treats an
	// amount it cannot assess as the rule's strictest action and never calls Reserve for zero.
	Amount int64
	// Limit is the rule's limit, not negative.
	Limit int64
	// Clock, if set, reads now for this request's first intent in place of the ledger's own clock: the
	// clock of the run being driven (WithClock). It is read at a first intent only.
	Clock func() time.Time
	// Waiver says the call carries an approved waiver for the rule: a reservation over the limit is
	// written, marked over.
	Waiver bool
	// contains filtered or unexported fields
}

type Reserve struct {
	Ledger string
	Slot   int
	Cum    int64
}

type Rule struct {
	Namespace string
	Name      string
	Currency  string
	Kind      Kind
}

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

type Slot struct {
	N        int    `json:"n"`
	Kind     string `json:"kind"` // "reserve" or "release"
	Attempt  string `json:"attempt"`
	Amount   int64  `json:"amount"`
	Currency string `json:"currency"`
	Ref      int    `json:"ref,omitempty"` // for a release, the slot it voids
	CumAfter int64  `json:"cum_after"`
	Limit    int64  `json:"limit"`
	Over     bool   `json:"over,omitempty"` // cum_after exceeds the limit, and a waiver covered it
	Marked   bool   `json:"marked,omitempty"`
	// Run, Tool and Att are the identity the Attempt joins, unencoded: the run whose journal holds the
	// call's attempt marker, the tool-use ID and the attempt ID, so a reconcile pass can find the marker.
	Run  string `json:"run,omitempty"`
	Tool string `json:"tool,omitempty"`
	Att  string `json:"att,omitempty"`
}

type Store interface {
	// Insert stores data under (run, name) if no entry has that name, and returns the entry the name
	// holds (the caller's, or the one already there) and whether this call stored it (A1).
	Insert(ctx context.Context, run, name string, data []byte) (stored []byte, inserted bool, err error)
	// Get returns the entry of run named name, if there is one.
	Get(ctx context.Context, run, name string) (data []byte, ok bool, err error)
	// Scan yields the entries of run whose Seq is greater than after (-1 for all), in ascending Seq:
	// a prefix of the run in commit order (A2). It yields an error at most once, as its last element.
	Scan(ctx context.Context, run string, after int64) iter.Seq2[Item, error]
}

type Target struct {
	Rule                 Rule
	KeyDigest            string
	RunID, RootRunID     string
	ToolUseID, AttemptID string
}