The top-up only appended, so a rule changed in the seed never reached a program an earlier seed made (production's github-badge was still once per repo). A seed rule that exists at Version 1 has not been edited since it was seeded; if its content differs from the seed's, the seed's replaces it at Version stored+1. A rule at Version 2 or more is staff's and is never touched. The embedded seedVersion is 2, so a program already topped up to 1 runs this on its next mount. The program.seeded record counts rulesCorrected, and Mount logs it. Claude-Session: https://claude.ai/code/session_015XYKLnBbrbajqj1GpRydF8
26 KiB
reward — LLM.md
The rewards rules engine. github.com/hanzoai/reward, public, MIT OR Apache-2.0.
admin.hanzo.ai configures it; cloud feeds it events and mounts it as the reward
capability at /v1/reward (singular, like referral). It began as a package in
hanzoai/commerce and moved out by owner decision; commerce keeps the one credit path
and nothing else of it.
Layers (each imports only those above it)
| Package | Is |
|---|---|
refuse |
the one error for input the engine will not take (HTTP 400) |
catalog |
the typed events a rule may read, under five pillars (use, share, community, contribute, expert); Event and its validation |
rule |
Rule, Condition, Action, Limits; Program (rules, budget, upline, founding cutoff, levels, badges, templates) |
claim |
Claim and Step; Fold turns steps into a status |
ledger |
Entry (the append-only ledger), Standing (balances, level, badges), Trail (staff acts), Past (legacy backfill rows) |
sponsor |
Link: who brought a member in, one per member |
profile |
a subject's handle, public flag, links |
emblem |
the SVG README badge, a pure function of a card and its options |
engine |
Evaluate, Simulate, Approve, Reject, Reverse, Backfill, program configuration, Seed, Show, Explore |
credit |
Client: engine.Credits over commerce's POST /v1/billing/credit |
http |
the routes (native zip, Raw handlers, gates read inside each handler) |
reward (root) |
Mount(app, Config) (*engine.Engine, error) |
Everything is written once
Storage is hanzoai/orm (Model[T], a JSON document store; orm.DB is SQLite
locally and the shared SQL over ZAP in production). orm has CreateIfAbsent
(first-writer-wins, race-safe on both) and no compare-and-swap update, so there is no
read-modify-write on any claim, step, ledger row or badge row.
- A claim id is
hash(event id, rule id, rule version). The same event twice is one claim. A claim for the same event under a newer version of the rule is also the same happening (Origin=hash(event id, rule id)), so an edit between two deliveries cannot award twice. - A claim row never changes. What is decided is a Step row, id
hash(claim, act), inserted byCreateIfAbsent:decision(approve|reject),award(everything written),reversal. Exactly one writer wins each, so approve and reject racing have one winner.claim.Fold(steps)is the status. TheStatuscolumn on the claim only lets the queue be listed; it is healed to the fold whenever the claim is read for a decision (engine.read). - Ledger rows (
Entry): idhash(claim, slot, act). Points and badges are written byApproveafter the decision step; a retry rewrites the same ids. A reversal is more rows (Act=reversal, negative points,Reverses= the row it undoes), never an edit. Credit goes throughCredits.Grantwith keyreward:<claim>:<action index>. - Ids live in one column for all kinds (
_entities.idis a bare PK), so every kind has its own id space:prg:program,clm_claim,stp_step,ent_entry,p:profile,h:handle,s:sponsor link. A subject named alice and a handle named alice are two rows. Never use a bare string as an id. - Filters use the camelCase of the Go field name (
Subject=is$.subject), so a filtered field's JSON tag must equal it. - Configuration (programs, rules) is edited by people in admin, one at a time:
last save wins, every save is on the trail. A rule's
Versionis the store's and rises only when the rule's content changes. - Not atomic across replicas: the check-then-claim of limits and budget is
serialized by a process mutex (
engine.reserve). Two replicas can both pass a limit that only one fits; staff reject the extra in the queue. Do not "fix" this with a second mutex; fix it with a guard row if it ever matters.
State machine
pending --Approve--> approved --(ledger, badge, credit written)--> awarded --Reverse--> reversed
pending --Reject--> rejected
approved is a decision made whose effects are still being written (a failed credit
leaves a claim here; Approve again finishes it, and Reject is refused). Auto rules
approve as they are claimed (reviewer auto). Every rule is manual unless an admin
sets auto. A claim that granted credit cannot be reversed here (no debit path is
built); the rest can. Rejected and reversed claims free their limits and budget.
Rules
{id, name, pillar, active, version, approval: manual|auto, when:{event}, if:[{field,op,value}], then:[action], limits:{once, keyField, perDay, perMonth}}
- Ops:
eq ne in gte lte contains, checked against the field's kind (containsis a substring on text, membership on lists; both ignore case). - Actions:
points(amount,redeemable),badge,credit(cents; only through commerce's credit path),email(template of the program). Norevshareorpayoutaction, by decision, until the owner sets the money terms. - Limits count claims per subject that are pending, approved or awarded.
onceissubjectorsubject+key(withkeyField);perDay/perMonthare UTC calendar day/month counts of claims, not points. - Program:
budget{pointsPerMonth, creditCentsPerMonth}(0 = no bound),upline(see Upline),foundingCutoff(see Founding cutoff),levels(see Levels; 100 in bands of ten in the seed),badges(each with a pillar and a rarity, common by default; the rarity is written empty for common),templates. - A rule may be badge-only: its
thenis onebadgeaction and nopointsaction (the tenure, streak and referral milestone rules of the seed). An approved claim of it writes the badge row and no points row, pays no upline and counts nothing toward the budget. - Pillar is on every rule (defaults to its event's) and every badge.
Catalog
catalog.events is THE list; an event is a typed addition there. Ingest refuses any
event that is not exactly the listed fields. usage.tokens.tokens is the subject's
lifetime verified total when the event was emitted, so a milestone is a gte rule
with once: subject. model.used.model is the canonical id; aliases never arrive.
github.fork {repo, forker} and github.badge {repo, owner, badge: profile|built|rank|deploy} are
contribute events; cloud emits github.badge only after its verifier confirmed the
repo is public, owned by the subject's linked GitHub identity, and carries the badge.
Five events say a count was reached; none carries evidence, and the host emits each
when its own count crosses the number, so a rule is if <field> eq N:
| Event | Pillar | Fields | Is |
|---|---|---|---|
tenure.reached |
use | months (whole) |
a person's account reached that many months since first sign-up |
streak.reached |
use | days (whole) |
a person was active on that many consecutive days |
founder.eligible |
community | reason (choice beta, alpha, early) |
a person qualifies as a Founding Developer (see Founding cutoff) |
referral.network |
share | referee (text) |
the subject is the sponsor of the person who made a referral (depth 2); referee names the referred org |
referral.milestone |
share | count (whole) |
the subject's count of activated referrals reached a multiple of 5 |
Evidence
An event that takes place on someone else's site (social.post.verified, github.*,
bounty.completed, submission.video, deploy.button; the
catalog marks them evidence: true) is refused without evidence:
{source, url, needs_review?, checks?: [{fetched_at, status, public, ref_found?, author_match}], recheck?: {at, result}}
source is the network or site, url its canonical https URL. checks is the host's
history of automated looks, oldest first (a post is looked at every day of its week);
author_match is yes, no or unknown; ref_found is stated only where a ref code
is expected. recheck is the last look a held post waited for (ok or removed). A
source the host cannot read arrives needs_review: true with no checks and no recheck;
a host never claims a check it did not run. The claim keeps the evidence verbatim, and
GET /v1/admin/reward/claims shows it beside the claim it decides. Every rule stays
manual: the evidence is for the staff member, not a substitute for one.
Limits.KeyField may name several fields joined by + (network+week): the key is
their values together, so a subject earns once per network per week.
referral.welcomed {sponsor} (about the referred person) is the thanks to the person a
referral brought in, stated with referral.activated when they run their first real
task; the seed's welcome-bonus pays it +10, once per person. The engine refuses a
person welcoming themselves.
Seed (engine/seed/rewards.json, program hanzo-rewards)
Created once on first mount (Seed), never overwritten: after that admin owns it, except
for the top-up below. Active rules are only the values in the owner-approved 2026-10-26 spec plus the owner's
later values; everything else is inactive at 0 points. All are manual.
-
Spec: token milestones 100K +10, 1M +20, 5M +30, 10M +40, 100M +75, 1B +100, 10B +150, 100B +200, 1T +300 (not redeemable); referral activated +25, retained +25 (redeemable); merged PR +50, fix +75, docs +30, translation +30, accepted issue +10, bounties +75/+150/+300 (redeemable). The spec's caps are seeded as per-rule claim counts (referral
perMonth4; PR kindsperDay300/points). The spec states them as point caps across rules, whichLimitscannot express; each rule alone respects the cap, together they may not. Levels as above. Credit ceiling $500/month. -
Owner's later values: stars, forks, follows +1 each,
onceper subject+repo (or +target), no list and no cap; README badgegithub.badge+10, once per subject, repo and badge kind (repo+badge). These override the spec's "star/follow 0, badge only". -
Inactive, 0 points, staff set the value: a post per product and per model family,
weekly-share(a verified post, once per subject, network and ISO week, so a later week's post earns again), a demo video per app, a test report per core product and beta, benchmark added, tests PR merged, "try" badges per product (18) and model family (Zen, Enso, Kai), and four expert rules. -
Known gap: "five jobs delivered" and "try 3 / 5 / 10 / 25 models" are counts over many events;
Limitscannot count. The seed ruleexpert-five-jobs-deliveredfires on a delivered job rated 4.5 or more, once per subject; the emitter must send it on the fifth. -
The owner's later tenure, streak, founder and referral rules are the one exception to "everything else is inactive at 0": they are active, manual, badge only or +1. Each is
once: subject+keywith its keyField named (so a number is earned once), exceptfounding-developer:- Tenure,
if months eq N(pillar use, badge only): One Month 1 (common), Six Months 6 (uncommon), Yearling 12 (rare), Two Years 24 (epic), Three Years 36 (legendary); rule idstenure-1...tenure-36. - Streak,
if days eq N(use, badge only): Week Streak 7 (common), Month Streak 30 (rare), Hundred Days 100 (epic);streak-7,streak-30,streak-100. founding-developer: onfounder.eligible, the Founding Developer badge (legendary, community),once: subjectwhatever the reason.referral-network: onreferral.network, +1 point (not redeemable), once perreferee; a second referee is a second +1 (share).- Referral milestones,
if count eq N(share, badge only), idsreferral-milestone-N: 5 Spark and 10 Signal (common), 15 Beacon and 20 Current (uncommon), 25 Catalyst and 30 Amplifier (rare), 35 Orbit, 40 Constellation and 45 Nova (epic), 50 Supernova (legendary), then Cosmos I to Cosmos X (legendary) at 100, 150 ... 550. Badge ids are the slugs of the names (spark,cosmos-i). The badge art comes later; the emblem renderer keeps its default look for them. The seed test lists them by id (countedinengine/seed_test.go) and the engine testengine/seed_events_test.gosends each one an event.
- Tenure,
Seed top-up
The seed has its own seedVersion (2 today); a program has SeedVersion (json
seedVersion, set by the engine only: admin PUT and POST bodies ignore it, it is not part of
the header). A program an unversioned seed made (v0.1.5 and before) has 0. Seed runs on every
mount; when the stored program's SeedVersion is below the embedded one it tops the program
up, once, and returns Seeded{Created, Rules, Badges, Corrected, Levels, Upline} (Mount logs the counts):
- every seed rule whose id is absent is appended at version 1, exactly as seeded, and every seed badge whose id is absent is appended. A badge that exists is never touched. A rule staff deleted comes back when its id is in the seed: an absent id cannot be told from one never added.
- a rule that follows the seed: the store raises a rule's
Versionon every content change, so a seed rule that exists atVersion1 has never been edited since it was seeded. If its content (everything butVersion, after settling empty fields) differs from the seed's, the seed's replaces it atVersionstored+1 (Seeded.Corrected, trailrulesCorrected). A claim already made keeps theThenandRuleVersionit was made under, and its event is not claimed again. A rule atVersion2 or more is staff's, active or not, and is never touched. (A rule staff deleted and wrote anew under a seed id is at version 1 and looks unedited; it follows the seed too.) Unlike an addition, a changed seed rule only reaches a program whenseedVersionis raised: raise it with the change. levelsis replaced with the seed's only if the stored table is still exactly the first seed's five levels (firstLevelsinengine/seed.go: Hacker 0, Builder 100, Shipper 500, Core 2500, Legend 10000, no band). Any other table is staff's and stays.uplineis set from the seed only if the stored one is empty; a stored one stays.foundingCutoff, the budget, the name and the templates are not touched.
Then Version rises, SeedVersion becomes the seed's, and one program.seeded trail record
(actor seed) names the counts (rules, badges, rulesCorrected) and whether levels and upline were set. A program already at
the seed's version is untouched, so a second mount does nothing. The program is read, changed
and written in one pass with ids checked against the document being written: two replicas
mounting together each write a whole document with every id once (a staff edit made between
that read and write is lost, as with any last-save-wins admin save); a top-up that fails
before its write leaves SeedVersion behind and the next mount repeats it. A fresh store
is created at the seed's version, with the program.created record and no program.seeded.
To ship more seed content later, add it and raise the embedded seedVersion.
Seed 2 added the correction; a program at seedVersion 1 (topped up by v0.1.6, which only
appended) runs it on its next mount. The tests start from earlier seeds kept in engine/testdata,
each from git show <tag>:engine/seed/rewards.json: seed-v0.1.4.json (v0.1.4 and v0.1.5 seeded
the same document) and seed-v0.1.2.json (whose github-badge is once per repo, not per repo
and badge).
Levels
Program.Levels is the table of standings: {level, name, band, minLifetimePoints}. The
numbers run in order from 0 or from 1 (a program written before bands starts at 1 and
keeps working); the first level starts at 0 lifetime points and each next one above the
one before. band is the named run of levels a level belongs to; empty means its name,
settled when a level is read (Program.LevelOf), never written into the table.
The seed has 100 levels, 0 to 99: level n needs 10*n*n lifetime points (0, 10, 40 ...
1,000 at 10, 25,000 at 50, 98,010 at 99). Bands of ten: 0-9 Photon, 10-19 Wave, 20-29
Focus, 30-39 Flare, 40-49 Comet, 50-59 Pulsar, 60-69 Nebula, 70-79 Quasar, 80-89
Magnetar, 90-99 Singularity. A level's name is <Band> <n> (Photon 0, Flare 37),
its band is <Band>. 999 points is level 9 Photon 9; 1,000 is level 10 Wave 10.
Admin edits the table with the rest of the program; nothing about bands is special there.
A program already stored keeps its table, unless it is still the first seed's five levels,
which the top-up replaces (see Seed top-up); a table staff changed stays.
GET /v1/reward/me returns per program level ({level, name, band, minLifetimePoints}),
next (the same shape) and, beside them, band (the level's). The public profile returns
level (the number), levelName and band. The README badge draws the level's name only.
Founding cutoff
Program.FoundingCutoff (foundingCutoff in the program body) is the date a Founding
Developer signed up before: an RFC 3339 timestamp (2026-01-01T00:00:00Z) or a date
(2026-01-01, the start of that day in UTC); empty is no cutoff. It is edited in admin
with the program header (a program PUT or POST carries it; a PUT that leaves it out
clears it, like the other header fields) and refused with 400 when it does not parse.
The seed sets none: the owner picks the date. The engine decides nothing by it; the host
reads it with Engine.Program (Program.Cutoff() parses it) when it decides to emit
founder.eligible.
Upline
Points only, never money. A member has one sponsor, set once and never changed:
the row reward-sponsor (sponsor.Link), id s:<subject>, written by CreateIfAbsent
so the first writer wins. It is made by the catalog event referral.linked
(pillar share, field sponsor, no evidence; the event's subject is the new member),
which Evaluate handles before the rules run, so a staff-priced rule may read it like
any event. It is refused (400) when the sponsor is the member or when the member is
already above the sponsor in the chain (a cycle; the climb is 64 links). A second
referral.linked for a member who has a sponsor changes nothing and is not an error;
the event id still dedupes claims. The check-then-link is under engine.reserve, like
limits: two replicas can still link a cycle at the same instant, and an award climbs
only three links, so it ends.
Program.Upline (upline) is the percentage for levels 1, 2 and 3 (1 = the member's
sponsor, 2 = theirs, 3 = one more), at most three entries, each 0 to 100, refused
otherwise when the program is saved; admin edits it with the header like budget and
levels. Empty pays nothing. The seed is [10, 5, 2].
When Approve writes a claim with points P > 0, each level with a sponsor gets one
ledger row, Act=upline, Level 1 to 3, on the sponsor, for floor(P * pct / 100)
points (a share of 0 writes nothing), Redeemable false, id EntryID(claim, level, "upline"), carrying the claim. Retries rewrite the same ids. The chain and the
percentages are read when the claim is written. Only claims pay: upline rows are not
claims and pay none, and legacy backfill rows make no claims. The rows count toward
lifetime points, levels and rank and never toward redeemable (the fold ignores the
flag on them, as on legacy rows).
Reverse undoes them with the claim's own rows: Act=reversal, negative points,
Reverses the upline row, Level copied. GET /v1/reward/me adds per program
network: {level1, level2, level3, points}: the members one, two and three links
below the caller (each level counted from the previous level's members, stopping at
10,000), and the caller's upline rows less their reversals. It is for the caller only;
the public profile and the badge never show it.
Legacy backfill
Backfill(ctx, program, rows, by): rows {subject, source, points, evidence},
source one of ledger.Sources (usage.tokens, referral.signup, referral.paying,
github.star, github.follow, github.fork, bounty). Entry Act=legacy, id
hash(program, subject, source): idempotent per (subject, source), the first count
stands. Counts toward lifetime points, levels and rank; never redeemable (the fold
ignores the flag on a legacy row). One call is one ledger.backfilled trail record
naming who ran it, however many rows (max 5000 per call); it makes no claims. The
beta-board scoring cloud applies: +1 per 100K tokens, +1 per referred signup, +20 per
referred org with spend, +1 per star, +1 per follow, +1 per fork, bounty points.
Profile, explore, badge
profile is private until its owner turns it on (PUT /v1/reward/me/profile). The
public view (GET /v1/reward/profile/:handle) is level, level name, band, lifetime points,
badges {id, name, pillar, rarity, earnedAt}, claim counts per pillar, links (https
only). Never an email, org, subject id or redeemable balance; a private profile and an
unknown handle are the same 404. Handles are unique by the conditional insert of an
h: row. GET /v1/reward/me/explore is the active rules the caller has no live claim
under, by pillar in order.
GET /v1/reward/badge/:handle.svg draws the same standing as an SVG for a README
(package emblem renders a pure Card, package http serves it). Options, all in
the query and all typed; anything else is a 400 (the usual refusal body):
| Option | Grammar | Default |
|---|---|---|
theme |
dark, light (an empty value is the default) |
dark |
style |
flat (one line), card (an empty value is the default) |
flat |
fields |
comma list of level, points, tokens, badges: lowercase, in the order drawn, each at most once; sent empty, unknown, repeated or with an empty or padded name is a 400 |
level,points |
label |
the left label (the card's corner label): 1 to 24 characters counted as runes, one line (no control character, newline, or Unicode line/paragraph separator), valid UTF-8; sent empty is a 400 | Hanzo |
level is the level's name; points the lifetime points; tokens is the NAME of the
highest token milestone badge held (Public.Tier: First 100K, Million Token Club, Five
Million, Ten Million, Century, Billionaire, Titan, Colossus, Trillion Club, the seed's
usage.tokens badges; tiers in engine/profile.go is that order and a test ties it
to the seed), never a token count; badges is the top three by rarity (legendary down to
common), then the most recently earned (Public.Top). A field with nothing to show is
left out, not drawn empty; with nothing at all to show a flat picture is the label alone.
A flat picture says every field on one line in order, badge names joined by commas; a
card says level, points and tokens under the handle and draws badges as a row of pills
(no row, and a shorter card, when it has none), so on a card the place of badges in
the list does not matter.
Options are read before the handle: a bad option is the same 400 for a public profile,
a private one and a handle nobody holds, so it cannot be used to ask whether a handle
exists; a private profile and an unknown handle are the same 404. Headers are
no-cache, max-age=0 with an ETag over the drawn bytes (so any option that changes
the picture changes the tag) and a 304 on a matching If-None-Match; all text is
escaped; goldens in emblem/testdata, one per look (go test ./emblem -update
rewrites them).
Routes
Public/self under /v1/reward, admin under /v1/admin/reward (cloud's convention:
/v1/admin/<capability>):
GET /v1/reward/health
GET /v1/reward/catalog public
POST /v1/reward/events platform: ingest
GET /v1/reward/me caller (balances, level, band, badges, network)
GET /v1/reward/me/claims caller
GET /v1/reward/me/explore caller
GET|PUT /v1/reward/me/profile caller
GET /v1/reward/profile/:handle public once turned on
GET /v1/reward/badge/:handle.svg public once turned on
GET|POST /v1/admin/reward/programs SuperAdmin
GET|PUT|DELETE /v1/admin/reward/programs/:program
PUT|DELETE /v1/admin/reward/programs/:program/rules/:rule
POST /v1/admin/reward/programs/:program/backfill
GET /v1/admin/reward/claims the queue (?status= ?program= ?subject= ?limit= ?offset=)
POST /v1/admin/reward/claims/:claim/approve|reject|reverse (reject, reverse need {"note"})
POST /v1/admin/reward/simulate a dry run
Delete is refused (400) once any claim or ledger row names the program or rule; retire
with active=false.
Auth
IAM owns it; this module checks no token and holds no secret. It reads the identity
headers the edge writes (authz.Header*, stripped from clients at the edge):
X-User-IsAdmin: true (exactly) with a subject is the platform principal (the edge's
SuperAdmin verdict, owner admin; an org admin or an admin-org application is not
one); X-User-Id is the subject. The gate runs inside every handler. There is no
service token. The brief said the ingest uses commerce's service token, but
commerce deleted COMMERCE_SERVICE_TOKEN ("commerce doing IAM's job with a secret of
its own"); cloud's in-process transport states the platform principal itself, and
ingest and the admin routes accept that one principal. Run it behind the edge: with
none, the headers are forgeable.
Credit
credit.Client{Base, Doer, Max} posts {org, amountCents, reason, tag, idempotencyKey}
to POST {Base}/v1/billing/credit and treats 200 and 201 as granted. Doer is the
host's transport (in cloud, the in-process one that carries the platform principal).
The event must name the org to credit; a credit rule with no org on the event is
skipped. Rules above Ceiling() are refused when saved.
Not built
Redemption (points for credit) needs the owner's conversion terms and the $20/member
cap; Entry is shaped for it (lifetime never falls by redeeming), but nothing writes
it. No revshare or payout. No debit of granted credit.
Test and release
go vet ./... && go test -count=1 ./... (a SQLite file per test, no service). Release
is a v* tag; the module ships from the tag and builds no image.