contributor

type Adjustment struct {
	// Kind is the deduction category.
	Kind AdjustmentKind
	// AmountCents is the deducted amount in cents. Always non-negative;
	// it is subtracted from the gross.
	AmountCents int64
	// Description optionally explains the adjustment.
	Description string
}

type AdjustmentKind string

type Award struct {
	// ID is the award's identifier, assigned by the store on creation.
	ID string

	// Splits assigns the award's credits to one or more recipients.
	Splits []Split

	// Activation is the first round in which the credits are active.
	Activation Month

	// Expiration is the first round in which the credits are no longer
	// active (exclusive bound), normally derived from the policy's
	// credit duration via Program.ExpirationMonth.
	Expiration Month

	// Evidence lists public URLs backing the award, e.g. merged pull
	// requests. At least one is required.
	Evidence []string

	// Description summarizes the contribution being awarded.
	Description string

	// PolicyVersion is the Program.Version under which the award was
	// proposed.
	PolicyVersion string

	// Status is the award's review status.
	Status AwardStatus

	// ProposedBy identifies who proposed the award.
	ProposedBy string
	// ProposedAt is when the award was proposed.
	ProposedAt time.Time

	// DecidedBy identifies who approved or rejected the award.
	DecidedBy string
	// DecidedAt is when the award was approved or rejected.
	DecidedAt time.Time
	// DecisionNote optionally explains the decision.
	DecisionNote string

	CreatedAt time.Time
	UpdatedAt time.Time
}

type AwardStatus string

type AwardStore interface {
	// CreateAward stores a new award and returns its assigned ID.
	CreateAward(context.Context, Award) (string, error)

	// GetAward returns the award with the given ID.
	GetAward(ctx context.Context, id string) (Award, error)

	// SetAward overwrites the award identified by Award.ID.
	SetAward(context.Context, Award) error

	// ListAwards lists awards with the given status, or all awards if
	// status is empty.
	ListAwards(ctx context.Context, status AwardStatus) (
		iterator.Iterator[Award], error)
}

type Entitlement struct {
	// Account is the participant's account reference.
	Account string
	// Credits is the participant's active credits in the round —
	// a frozen input of the calculation.
	Credits int64
	// AmountCents is the resulting entitlement in cents.
	AmountCents int64
}

type HandleSplit struct {
	// GitHubHandle is the recipient's public GitHub username. It is
	// matched against enrolled participants case-insensitively.
	GitHubHandle string

	// Credits is the credit quantity assigned to the recipient.
	Credits int64
}

type Ledger struct {
	Programs     ProgramStore
	Participants ParticipantStore
	Awards       AwardStore
	Receipts     ReceiptStore
	Rounds       RoundStore
	Obligations  ObligationStore
}

type Month string

type Obligation struct {
	// Account is the recipient participant's account reference.
	Account string

	// Month is the round that produced the obligation.
	Month Month

	// AmountCents is the gross amount owed in cents.
	AmountCents int64

	// Currency is the ISO 4217 currency code.
	Currency string

	// DueDate is when the obligation becomes due under the payment
	// timetable.
	DueDate time.Time

	// State is the current lifecycle state.
	State ObligationState

	// ProviderTransferRef is an opaque reference to the payout
	// provider's transfer, set once a transfer is initiated.
	ProviderTransferRef string

	// History records every state transition.
	History []ObligationEvent

	CreatedAt time.Time
	UpdatedAt time.Time
}

type ObligationEvent struct {
	From ObligationState
	To   ObligationState
	At   time.Time
	Note string
}

type ObligationState string

type ObligationStore interface {
	// CreateObligation stores a new obligation. It returns
	// document.ErrAlreadyExists if it was already created.
	CreateObligation(context.Context, Obligation) error

	// GetObligation returns the obligation for month m and account.
	GetObligation(ctx context.Context, m Month, account string) (
		Obligation, error)

	// SetObligation overwrites the obligation record.
	SetObligation(context.Context, Obligation) error

	// ListAccountObligations lists all obligations of an account.
	ListAccountObligations(ctx context.Context, account string) (
		iterator.Iterator[Obligation], error)

	// ListStateObligations lists all obligations in the given state.
	ListStateObligations(ctx context.Context, state ObligationState) (
		iterator.Iterator[Obligation], error)
}

type Participant struct {
	// Account is an opaque reference to the participant's user account
	// in the embedding system. It is the Participant's identity.
	Account string

	// GitHubHandle is the participant's public GitHub username.
	GitHubHandle string

	// AgreementVersion is the contributor agreement version accepted at
	// enrollment.
	AgreementVersion string

	// AgreementAcceptedAt is when the agreement was accepted.
	AgreementAcceptedAt time.Time

	// AgreementEvidence is an opaque reference to evidence of the
	// acceptance, e.g. a request audit log entry.
	AgreementEvidence string

	// Status is the participant's eligibility status.
	Status ParticipantStatus

	// PayoutProviderRef is an opaque reference to the participant's
	// account at the payout provider. Empty until payment onboarding
	// completes; enrollment never requires it.
	PayoutProviderRef string

	// PayoutReady reports whether the payout provider accepted the
	// participant's onboarding and transfers can be initiated.
	PayoutReady bool

	CreatedAt time.Time
	UpdatedAt time.Time
}

type ParticipantStatus string

type ParticipantStore interface {
	// CreateParticipant stores a new participant. It returns
	// document.ErrAlreadyExists if the account is already enrolled.
	CreateParticipant(context.Context, Participant) error

	// GetParticipant returns the participant with the given account.
	GetParticipant(ctx context.Context, account string) (Participant, error)

	// SetParticipant overwrites the participant record.
	SetParticipant(context.Context, Participant) error

	// ListParticipants lists all participants.
	ListParticipants(context.Context) (iterator.Iterator[Participant], error)
}

type Program struct {
	// Version identifies this policy revision, e.g. "2026-01".
	Version string

	// Currency is the ISO 4217 currency code all receipts, pools and
	// obligations are denominated in, e.g. "usd".
	Currency string

	// PoolBps is the share of covered net receipts allocated to the
	// monthly pool, in basis points (2000 = 20%).
	PoolBps int

	// CoveredReceipts is a human-readable definition of which receipts
	// are covered by the program.
	CoveredReceipts string

	// CreditDurationRounds is the number of monthly rounds an awarded
	// credit stays active, counted from its activation month.
	CreditDurationRounds int

	// PaymentTimetable is a human-readable description of when earned
	// entitlements become owed and are paid out.
	PaymentTimetable string

	// PayoutDueDays is the number of days after the end of the calendar
	// quarter containing a round in which its obligations become due.
	PayoutDueDays int

	// CalculationVersion is the allocation engine version this policy
	// was published against. Rounds refuse to close if it does not match
	// the engine's CalculationVersion.
	CalculationVersion int

	// EffectiveFrom is the first month this policy applies to.
	EffectiveFrom Month

	CreatedAt time.Time
	UpdatedAt time.Time
}

type ProgramStore interface {
	// PutProgram stores the program, keyed by Program.Version.
	PutProgram(context.Context, Program) error

	// GetProgram returns the program with the given version.
	GetProgram(ctx context.Context, version string) (Program, error)

	// ProgramFor returns the policy in effect for month m: the program
	// with the latest EffectiveFrom that is not after m. It returns
	// document.ErrNotFound if no program is effective.
	ProgramFor(ctx context.Context, m Month) (Program, error)

	// ListPrograms lists all program versions.
	ListPrograms(context.Context) (iterator.Iterator[Program], error)
}

type ProposeAwardRequest struct {
	// Splits assigns the award's credits to one or more recipients.
	Splits []HandleSplit

	// Activation is the first round in which the credits are active.
	Activation Month

	// Evidence lists public URLs backing the award. At least one is
	// required.
	Evidence []string

	// Description summarizes the contribution being awarded.
	Description string

	// ProposedBy identifies who proposed the award.
	ProposedBy string
}

type Receipt struct {
	// Source is the opaque, unique reference to the originating billing
	// record (e.g. an invoice identifier). It is the Receipt's identity.
	Source string

	// Month is the round the receipt is attributed to.
	Month Month

	// GrossCents is the gross amount in cents.
	GrossCents int64

	// Adjustments enumerates deductions from the gross amount.
	Adjustments []Adjustment

	// Currency is the ISO 4217 currency code, e.g. "usd". It must match
	// the program currency for the receipt to be covered.
	Currency string

	// Evidence is an opaque reference to supporting documentation.
	Evidence string

	CreatedAt time.Time
	UpdatedAt time.Time
}

type ReceiptStore interface {
	// CreateReceipt stores a new receipt. It returns
	// document.ErrAlreadyExists if a receipt with the same source was
	// already imported.
	CreateReceipt(context.Context, Receipt) error

	// GetReceipt returns the receipt with the given source reference.
	GetReceipt(ctx context.Context, source string) (Receipt, error)

	// ListMonthReceipts lists the receipts attributed to month m.
	ListMonthReceipts(ctx context.Context, m Month) (
		iterator.Iterator[Receipt], error)
}

type Round struct {
	// Month identifies the round.
	Month Month

	// PolicyVersion is the Program.Version applied.
	PolicyVersion string

	// CalculationVersion is the engine version used to compute the
	// round.
	CalculationVersion int

	// Currency is the program currency the round is denominated in.
	Currency string

	// NetReceiptsCents is the sum of covered net receipts of the month.
	NetReceiptsCents int64

	// CarryforwardCents is the unallocated balance carried in from the
	// previous round.
	CarryforwardCents int64

	// PoolCents is the allocatable pool:
	// CarryforwardCents + NetReceiptsCents × PoolBps / 10000.
	PoolCents int64

	// TotalCredits is the allocation denominator: the sum of all active
	// credits in the round.
	TotalCredits int64

	// Entitlements are the per-participant results, ordered by account.
	Entitlements []Entitlement

	// UnallocatedCents is the part of the pool not allocated in this
	// round; it is carried forward into the next round. It is the whole
	// pool when TotalCredits is zero and zero otherwise.
	UnallocatedCents int64

	// ClosedAt is when the round was closed.
	ClosedAt time.Time
	// ClosedBy identifies who closed the round.
	ClosedBy string

	CreatedAt time.Time
	UpdatedAt time.Time
}

type RoundStore interface {
	// CreateRound stores a closed round. It returns
	// document.ErrAlreadyExists if the month is already closed.
	CreateRound(context.Context, Round) error

	// GetRound returns the closed round for month m.
	GetRound(ctx context.Context, m Month) (Round, error)

	// ListRounds lists all closed rounds.
	ListRounds(context.Context) (iterator.Iterator[Round], error)
}

type Split struct {
	// Account is the recipient participant's account reference.
	Account string
	// Credits is the credit quantity assigned to the recipient.
	// Credits are allocation weights, not currency.
	Credits int64
}

type Statement struct {
	Program Program
	Round   Round
}