Kudos accounting reference¶

Topics: accounting, kudos

The maintainer contract for kudos mutation and consumption: the authoritative events, the materialized targets, the producers and consumers, the locks, and the tests that hold each rule. For design rationale, read Kudos accounting, projection, and concurrency. For deployment and incident procedures, follow Kudos ledger operations.

Source of truth by mode¶

The existing balance at first deployment is the opening position. The ledger contains deltas from deployment onward, not a fabricated history of older movements.

Vocabulary¶

Data model¶

Accounting tables¶

The mapped accounting models use SQLAlchemy 2 Mapped/mapped_column attributes. Runtime dialect operations are confined to typed helpers: advisory locks and isolation in horde/database/kudos_db.py, counter upserts in horde/database/kudos_counters.py, and legacy mode behavior in horde/database/kudos_legacy_projection.py. Raw DDL belongs in the versioned migration file, not request code. The SQLAlchemy mypy plugin checks the accounting model surface in CI.

KudosLedger fields¶

KudosStatEvent fields¶

event_id, entry_type, job_id, wp_type, amount, detail, and applied have the same correlation/audit meaning as their currency counterparts. The remaining fields define a counter projection:

Stable enums and audit keys¶

Do not add an untyped string discriminator when one of these axes describes it. Add or extend the enum and teach the projector and tests about the new value together.

Entry-type catalogue¶

An entry type answers “why did this posting exist?” The sign and target answer “what did it do?”

Mutation contract¶

All new or modified kudos code must obey these rules.

1. Use the public producer surface. User currency enters through User.modify_kudos or User.modify_evaluating_kudos; derived events enter through emit_kudos_stat_event. Do not assign a materialized accounting column in a business path. Narrow exceptions are listed under excluded kudos-like state.
2. Group a logical event. Wrap a settlement, transfer, activation tax, or other multi-posting mutation in kudos_event. Include job_id and wp_type where available.
3. Make external retries explicit. If an API mutation can be retried independently of locked business state, accept a stable idempotency key, derive the event ID from it, and reject reuse with different parameters. A random event UUID provides correlation only.
4. Commit business state and postings together. Do not commit part of an event, perform network work, and append the rest later. Emission helpers flush by default so the caller owns the transaction boundary.
5. One currency row, one user balance. Worker/team IDs and counter units never belong in KudosLedger. Emit separate debit and credit rows; do not encode a transfer as an opaque net amount.
6. Reserve before authorizing eventual spend. Under acquire_payer_lock, call reserve_kudos with a stable business_id. Attach that reservation ID to matching debit metadata. Never use effective_kudos to authorize a spend.
7. Do not fund from pending credits. available_kudos deliberately ignores them. Changing that rule requires a proof covering credit rollback, event ordering, and projector failure.
8. Preserve mode ownership. Business code emits events in both modes and delegates temporary inline behavior to kudos_legacy_projection. Do not add mode branches to endpoints or settlement methods.
9. Record non-linear compatibility behavior. If a rule floors, caps, forgives, or otherwise changes the requested signed delta, emit the difference as its own typed posting so replay matches the projection.
10. Capture historical dimensions at emission. Team membership and similar attribution must be stamped on the event. The projector must not infer past ownership from mutable current relationships.
11. Use decimal accounting values. Convert through Decimal(str(value)) and round/quantize at the existing two-decimal boundary. Never fold currency through binary-float accumulation.
12. Keep the archive immutable. Do not update old amounts, retarget postings, delete applied history, or toggle applied as a repair. Emit a compensating posting.
13. Add producer, fold, retry, and recovery tests. At minimum pin the emitted rows and materialized result. A new spend path also needs concurrent overspend coverage; a new retryable path needs replay/conflict coverage.

Direct materialized assignments are allowed only for initial data/bootstrap before an accounting movement exists, or inside the shadow/projector/reconciliation implementation described here. A test fixture that needs an opening balance should assign it directly and commit rather than creating misleading ledger history.

Producer inventory¶

This is the current inventory of paths that create user currency or kudos-derived projection events.

User.modify_kudos also emits the matching per-action user-kudos statistics event. WorkerTemplate.modify_kudos emits worker display/stat events, not currency. Producer wrappers should retain that distinction.

Two interrogation contracts in that table correct behaviour the inline implementation had:

• An interrogation uptime crossing grants an untrusted owner exactly one reward, routed wholly to the spendable balance by the alchemist bypass and minting no escrow, where the inline path credited both the balance and escrow for the same crossing (pinned by tests/unit/test_kudos_invariants.py::test_interrogation_uptime_grants_untrusted_owner_exactly_one_reward).
• Cancelling an interrogation form a worker is still processing settles it like a submission, crediting the worker and owner and debiting the requester the form kudos plus burn, where the inline path moved the form to CANCELLED ahead of the settle check and so settled nothing (pinned by tests/unit/test_kudos_invariants.py::test_cancelling_in_flight_interrogation_form_settles_like_a_submit).

Projection target inventory¶

Currency rows and statistic rows are each claimed in a bounded batch. A single event may cross a batch boundary; therefore any event-wide side effect must query for remaining unapplied rows rather than assuming a batch contains the whole event.

Consumer and read-model inventory¶

Choosing the correct read is part of the mutation contract. A blanket replacement of every .kudos access is wrong because account currency, queue priority, worker attribution, job price, and shared-key quota have different meaning.

User currency consumers¶

The two legacy materialized reads in worker scheduling are documented rather than hidden. If they are changed, the maintainer must decide the intended policy: available_kudos is conservative spend capacity; effective_kudos includes queued income; the materialized value is a cheap, lagging priority/display projection. They are not interchangeable.

Derived-stat consumers¶

All of these can lag in ledger mode. Consumers that need transaction-local proof of an accepted event should inspect the event/result they just created, not force the projector or assume a refreshed aggregate.

Excluded kudos-like state¶

The following kudos-adjacent state is not a user currency projection and must not be routed through KudosLedger without a separate design decision:

Reservation lifecycle¶

business_id uniqueness supplies retry stability. Reactivation may not change payer. Reservation mutation uses row locks only after payer-scoped admission serialization; release functions are idempotent and return zero when no active hold remains. available_kudos reads the balance, active holds, and queued debits in one statement so all terms come from a single database snapshot; a fold or release committing mid-read cannot hide a debit from every term.

Concurrency and lock reference¶

Required accounting lock order is applier lock before exclusive mode-gate lock. Projection targets are visited in stable ID order. Code that needs another accounting lock must document where it fits before it is merged. The legacy USE_SQLITE runtime mode short-circuits PostgreSQL advisory locks and therefore cannot validate these concurrency properties.

Failure and recovery invariants¶

• A projector cycle commits both target updates and exact applied flags, or neither.
• Deterministically malformed statistic events are quarantined by business-event ID; unrelated events in the batch continue, while infrastructure failures still roll back the whole cycle.
• A row is selected by applied = false, never by id > watermark.
• A stopped projector is a lag incident, not lost work; restore it and drain in ledger mode.
• A transfer hold remains active until both sides of the event are materialized, even when a batch splits the event.
• A trusted user's positive escrow with no in-flight promotion pair is self-healed by a later projector cycle.
• Minimum-balance flooring creates an explicit FLOOR_ADJUSTMENT so snapshot replay equals projection.
• A snapshot records both opening columns and the applied totals visible at that instant.
• Reconciliation excludes prior RECONCILIATION entries from its movement baseline and emits one deterministic repair event per snapshot/user.
• Ledger-to-shadow transition owns the applier lock, waits for ledger-mode writers, drains the final tail, and changes mode in one transaction.
• Applied currency and statistic history is permanent. prune_applied_kudos_ledger is intentionally a no-op.

Never recover by deleting ledger/stat rows, editing old amounts or targets, changing applied, or directly assigning a production balance. Preserve evidence and emit compensation. See the operations guide for the executable procedure.

Observability contract¶

kudos_applier_health reports:

The background task runs every three seconds and keeps folding within a tick while full batches drain, up to a bounded number of catch-up cycles, so a backlog clears at many batches per tick while each fold stays a small transaction. Health is sampled once per tick, before the fold loop, and exported as current-value gauges. The combined queue and oldest-age gauges have currency/stat splits, while the quarantine gauges distinguish permanent evidence from the age of the newest incident. Phase histograms, cycles-per-tick and configured batch/catch-up gauges explain capacity limits. These metrics are recorded on the quorum node only; the per-node /api/v2/status/heartbeat endpoint deliberately excludes them, because a load balancer health check fed a shared-database signal would remove every node from rotation at once. Operators should alert on queue age and reservation age from the quorum telemetry, not only row count: a steady queue can be healthy under load, while one old row or hold can indicate a poisoned path.

Code map¶

Regression-test map¶

The unit suite provisions PostgreSQL through testcontainers, so the advisory-lock and concurrent-projector tests exercise the real primitives. The legacy USE_SQLITE runtime mode short-circuits those locks and is not covered by the suite. Before cutover or a recovery rehearsal, run the safety and integration suites as required by the operations guide.

Review checklist for a new kudos change¶

• Is the value currency, a display attribution, a counter, a price, or a quota?
• What is the business event boundary, and which postings share its event_id?
• Is the operation externally retryable? If so, what stable key and parameter-conflict rule make it idempotent?
• Can it authorize spend? If so, where is the payer lock and stable reservation?
• Which projection owns the read, what lag can its consumer tolerate, and should the consumer use materialized, available, or effective balance?
• Does the producer capture mutable attribution such as team membership at event time?
• Does the change introduce another lock? Where does it fit in the documented order?
• Can a batch split the event, and does any event-wide side effect handle that case?
• Is every non-linear adjustment represented by a posting?
• Can the change be rolled back through the supported mode transition without running old code against new holds?
• Do tests cover emission, fold, concurrency/retry behavior, and recovery, not merely the final number?
• Have this reference, the explanation, and the operations guide been updated when the contract changed?