@lssm-tech/lib.gamification-runtime
Deterministic, immutable evaluation and replay for campaigns declared with
@lssm-tech/lib.gamification-spec.
The runtime expands cadence slots, evaluates conditions, streaks and capped XP, scores leaderboards, groups leagues, applies wallet actions, reduces activities, and canonically replays event streams. It performs no I/O and uses only explicit timestamps, seeds, entropy receipts, and host-authorized participant references.
Determinism and receipts
reduceCampaignEvent rejects duplicate and out-of-order activities without mutating the input snapshot; it also rejects campaign-version mismatches, unknown mission slots, activity outside a slot window, and finalization before a slot closes. replayCampaign sorts by (occurredAt, eventId).- Mission XP is awarded only when an event newly completes that mission in the active slot. Explicit
xpRuleId activity remains available for host-declared awards, and a decision exposes every receipt when one event completes several missions or unlocks rewards.
- XP is evaluated as base, bonuses, priority-ordered basis-point modifiers, rule cap, then event/source/slot/day/period/campaign caps. All rounding is integer half-up and each receipt reports the rule ID plus raw, applied, rule-capped, and later-scope-rejected XP.
- XP usage is keyed by the caller's explicit source, slot, day, period, campaign, and rule identifiers. Boost inventory is consumed only for a positive applied delta after caps.
- Slot expiry resolves completion, scheduled protection, approved excuse, available shield, then miss. Only completion increments a streak.
- State snapshots contain append-only XP receipts and canonical
gamification.* decision events suitable for host persistence and audit.
- Recurring event/count quests evaluate against their current slot or period, so activity from an earlier recurrence cannot unlock a later one.
The package also exports transparent leaderboard scoring and built-in stable tie-breakers, promotion/demotion, host/seeded/entropy-recorded matchmaking, group streak and cooperative quest helpers, nudge cooldown decisions, and atomic wallet grants, consumption, and transfers. Participant IDs may identify individuals or host-authorized teams, so the same transparent scoring function supports personal and team leaderboards.
The optional posting-streak surface projects unique calendar posting days with an explicit IANA timezone and clock. Yesterday retains the active streak until the current day ends; future posts do not count. The projection is read-only and awards no XP or compensation. It includes a Sunday–Saturday strip with active-streak day numbering.
Posting timestamps and the clock require explicit ISO offsets; offset-free values are not interpreted using the server's ambient timezone. Native Hirly compatibility can be rechecked with scripts/check-creator-streak-compatibility.ts --source-root <checkout>. The comparison excludes future/offset-free inputs, which deliberately receive stricter handling in the shared projection.
