Files
zeekay 9ed07f3e65 reward: top up a program an earlier seed made
Seed never touched an existing program, so rules, badges and levels added
to the seed never reached a store seeded by v0.1.4. The seed now carries a
seedVersion (1) and a program a SeedVersion (engine-only, ignored in admin
input; 0 for one the first seed made). On every mount, a program below the
embedded version is topped up once: seed rules and badges whose ids are
absent are appended as seeded, existing ones untouched; levels are replaced
only when still the first seed's five-level table; upline is set only when
empty. Version rises, SeedVersion advances, one program.seeded trail record
names the counts. Seed returns Seeded{Created, Rules, Badges, Levels,
Upline} and Mount logs them.

Claude-Session: https://claude.ai/code/session_015XYKLnBbrbajqj1GpRydF8
2026-11-08 15:59:54 -08:00

284 lines
9.0 KiB
Go

package rule
import (
"cmp"
"slices"
"strings"
"time"
"github.com/hanzoai/orm"
"github.com/hanzoai/reward/catalog"
"github.com/hanzoai/reward/refuse"
)
// Kind is the program's kind in the store.
const Kind = "reward-program"
func init() { orm.Register[Program](Kind, orm.WithStringKey[Program]()) }
// Budget bounds what a program spends in one UTC calendar month, counted from the
// claims made in it that are not rejected or reversed. 0 is no bound.
type Budget struct {
PointsPerMonth int64 `json:"pointsPerMonth"`
CreditCentsPerMonth int64 `json:"creditCentsPerMonth"`
}
// UplineDepth is how many sponsors above a member an award pays: their sponsor, that
// sponsor's sponsor, and one more.
const UplineDepth = 3
// Level is a standing, reached at MinLifetimePoints.
type Level struct {
// Level is the standing's number: from 0 or from 1, then one more each.
Level int `json:"level"`
Name string `json:"name"`
// Band is the named run of levels this one belongs to. Empty is Name.
Band string `json:"band"`
MinLifetimePoints int64 `json:"minLifetimePoints"`
}
// Rarity is how rare a badge is, for the page that shows it.
type Rarity string
const (
Common Rarity = "common"
Uncommon Rarity = "uncommon"
Rare Rarity = "rare"
Epic Rarity = "epic"
Legendary Rarity = "legendary"
)
// Rarities lists the five, commonest first.
var Rarities = []Rarity{Common, Uncommon, Rare, Epic, Legendary}
// Rank is the rarity's place in Rarities; an unknown rarity ranks as common.
func (r Rarity) Rank() int {
for i, x := range Rarities {
if x == r {
return i
}
}
return 0
}
// Badge is a badge a program can award.
type Badge struct {
ID string `json:"id"`
Name string `json:"name"`
Pillar catalog.Pillar `json:"pillar"`
// Rarity is empty for common.
Rarity Rarity `json:"rarity,omitempty"`
}
// Program is the set of rules that decide who earns what, the budget they spend,
// the levels points reach, the badges they award and the share of an award that goes
// up the sponsor chain. The store holds one document per program, under its slug as
// the id; admin.hanzo.ai edits it, and the seed only creates it.
type Program struct {
orm.Model[Program]
Name string `json:"name"`
// Active programs are evaluated; an inactive one awards nothing.
Active bool `json:"active"`
// Version starts at 1 and is raised each time the program or one of its rules
// changes.
Version int `json:"version"`
// SeedVersion is the version of the embedded seed this program was last brought
// up to: 0 for one created before seeds had versions. Only the engine sets it;
// admin input never carries it.
SeedVersion int `json:"seedVersion"`
Budget Budget `json:"budget"`
// Upline is the percentage of a claim's points paid, as points that count
// toward lifetime and never toward redeemable, to the sponsor at each level
// above the member: [0] their sponsor, [1] that sponsor's sponsor, [2] one more.
// At most UplineDepth entries, each 0 to 100; empty pays no upline.
Upline []int `json:"upline"`
// FoundingCutoff is the date a Founding Developer signed up before: an RFC 3339
// timestamp, or a date taken as that day's start in UTC. Empty is no cutoff. The
// host reads it; the engine decides nothing by it.
FoundingCutoff string `json:"foundingCutoff"`
Levels []Level `json:"levels"`
Badges []Badge `json:"badges"`
Templates []Template `json:"templates"`
Rules []Rule `json:"rules"`
}
// ProgramID is the store id of the program slug. Every kind keeps ids in a keyspace
// of its own, because the store's id column is one key for all kinds.
func ProgramID(slug string) string { return "prg:" + slug }
// View is a program as callers see it: its slug as the id, not the store's.
type View struct {
ID string `json:"id"`
Name string `json:"name"`
Active bool `json:"active"`
Version int `json:"version"`
// SeedVersion is as on Program.
SeedVersion int `json:"seedVersion"`
Budget Budget `json:"budget"`
Upline []int `json:"upline"`
// FoundingCutoff is as on Program.
FoundingCutoff string `json:"foundingCutoff"`
Levels []Level `json:"levels"`
Badges []Badge `json:"badges"`
Templates []Template `json:"templates"`
Rules []Rule `json:"rules"`
CreatedAt time.Time `json:"createdAt,omitzero"`
UpdatedAt time.Time `json:"updatedAt,omitzero"`
}
// View is p as callers see it.
func (p *Program) View() View {
return View{ID: p.Slug(), Name: p.Name, Active: p.Active, Version: p.Version, SeedVersion: p.SeedVersion, Budget: p.Budget, Upline: nonNil(p.Upline),
FoundingCutoff: p.FoundingCutoff, Levels: nonNil(p.Levels), Badges: nonNil(p.Badges), Templates: nonNil(p.Templates), Rules: nonNil(p.Rules),
CreatedAt: p.CreatedAt, UpdatedAt: p.UpdatedAt}
}
func nonNil[T any](s []T) []T {
if s == nil {
return []T{}
}
return s
}
// Slug is the program's id as callers know it.
func (p *Program) Slug() string { return strings.TrimPrefix(p.Id_, "prg:") }
// Find returns the rule with id, or nil.
func (p *Program) Find(id string) *Rule {
for i := range p.Rules {
if p.Rules[i].ID == id {
return &p.Rules[i]
}
}
return nil
}
// Badge returns the badge with id, or nil.
func (p *Program) Badge(id string) *Badge {
for i := range p.Badges {
if p.Badges[i].ID == id {
return &p.Badges[i]
}
}
return nil
}
// Template returns the template with id, or nil.
func (p *Program) Template(id string) *Template {
for i := range p.Templates {
if p.Templates[i].ID == id {
return &p.Templates[i]
}
}
return nil
}
// LevelOf is the highest level that lifetime points reach, and the next one. A level
// with no Band comes back with its Name as the Band.
func (p *Program) LevelOf(lifetime int64) (Level, *Level) {
var at Level
var next *Level
for i, l := range p.Levels {
if lifetime < l.MinLifetimePoints {
next = &p.Levels[i]
break
}
at = l
}
at.Band = cmp.Or(at.Band, at.Name)
if next != nil {
n := *next
n.Band = cmp.Or(n.Band, n.Name)
next = &n
}
return at, next
}
// Cutoff is FoundingCutoff as a time: the zero time for none, an error for text that
// is neither an RFC 3339 timestamp nor a date.
func (p *Program) Cutoff() (time.Time, error) {
if p.FoundingCutoff == "" {
return time.Time{}, nil
}
if t, err := time.Parse(time.RFC3339, p.FoundingCutoff); err == nil {
return t, nil
}
return time.Parse(time.DateOnly, p.FoundingCutoff)
}
// Validate reports why p is not a program: its header and every rule in it.
func (p *Program) Validate() error {
if !Slug.MatchString(p.Slug()) {
return refuse.New("program id %q must be 1-64 of a-z, 0-9, '.', '_' and '-'", p.Slug())
}
if strings.TrimSpace(p.Name) == "" {
return refuse.New("program %s needs a name", p.Slug())
}
if p.Budget.PointsPerMonth < 0 || p.Budget.CreditCentsPerMonth < 0 {
return refuse.New("a budget must not be negative; 0 is no bound")
}
if len(p.Upline) > UplineDepth {
return refuse.New("upline takes at most %d percentages, one for each level above a member; %d were given", UplineDepth, len(p.Upline))
}
for i, pct := range p.Upline {
if pct < 0 || pct > 100 {
return refuse.New("upline level %d is %d; a percentage is from 0 to 100", i+1, pct)
}
}
if _, err := p.Cutoff(); err != nil {
return refuse.New("foundingCutoff %q must be an RFC 3339 timestamp or a date such as 2026-01-01", p.FoundingCutoff)
}
for i, l := range p.Levels {
switch {
case i == 0 && l.Level != 0 && l.Level != 1, i > 0 && l.Level != p.Levels[0].Level+i:
return refuse.New("levels must be numbered in order, from 0 or 1; %q is %d", l.Name, l.Level)
case strings.TrimSpace(l.Name) == "":
return refuse.New("level %d needs a name", l.Level)
case i == 0 && l.MinLifetimePoints != 0:
return refuse.New("the first level starts at 0 lifetime points")
case i > 0 && l.MinLifetimePoints <= p.Levels[i-1].MinLifetimePoints:
return refuse.New("level %d must start above level %d", l.Level, i)
}
}
seen := map[string]bool{}
for _, b := range p.Badges {
switch {
case !Slug.MatchString(b.ID):
return refuse.New("badge id %q must be 1-64 of a-z, 0-9, '.', '_' and '-'", b.ID)
case seen[b.ID]:
return refuse.New("badge %s is listed twice", b.ID)
case strings.TrimSpace(b.Name) == "":
return refuse.New("badge %s needs a name", b.ID)
case !b.Pillar.Valid():
return refuse.New("badge %s: %q is not a pillar", b.ID, b.Pillar)
case b.Rarity != "" && !slices.Contains(Rarities, b.Rarity):
return refuse.New("badge %s: %q is not a rarity", b.ID, b.Rarity)
}
seen[b.ID] = true
}
seen = map[string]bool{}
for _, t := range p.Templates {
if seen[t.ID] {
return refuse.New("template %s is listed twice", t.ID)
}
seen[t.ID] = true
if err := t.validate(); err != nil {
return err
}
}
seen = map[string]bool{}
for i := range p.Rules {
r := &p.Rules[i]
if seen[r.ID] {
return refuse.New("rule %s is listed twice", r.ID)
}
seen[r.ID] = true
if err := r.Validate(p); err != nil {
return err
}
}
return nil
}