Reward and Currency Domain

RewardRule  (when and how much to award)
      │
      └──▶ VirtualTransaction  (a ledger entry: credit or debit)
                │
                └──▶ VirtualBalance  (the user's current balance per currency)

VirtualCurrency  (defines a currency: XP, credits, tokens, etc.)

// Only reward when progress changes to COMPLETE
{
  "and": [
    { "===": [{ "var": "event.progress" }, "COMPLETE"] },
    { "!==": [{ "var": "previousEvent.progress" }, "COMPLETE"] }
  ]
}

// Only reward successful quizzes
{ "===": [{ "var": "event.outcome" }, "SUCCESS"] }

// Static: always award 100 points
100

// Dynamic: award based on quiz difficulty
{
  "if": [
    { "===": [{ "var": "event.difficulty" }, "HARD"] }, 20,
    { "===": [{ "var": "event.difficulty" }, "MEDIUM"] }, 10,
    5
  ]
}

{
  "rewards": [
    {
      "rewardType": "VIRTUAL_CURRENCY",
      "virtualCurrencyId": "vc-xp",
      "redemptionMode": "AUTO",
      "expression": 100
    },
    {
      "rewardType": "BADGE",
      "badgeConfigurationId": "bc-mission-master"
    }
  ]
}

### Event Remapping

Source events are remapped to their parent entity types before rule matching:

| Source Event | Maps To |
|-------------|---------|
| `ActivityLog` | `Activity` |
| `LearningPathLog` | `LearningPath` |
| `LearningGroupLog` | `LearningGroup` |
| `SlideLog` | `Slide` |

This means rules are defined against the parent entity (e.g., `matchEntity: "Activity"`), not against the log entity.

## Virtual Currency

A **Virtual Currency** defines a type of point, credit, or token within a workspace. Each workspace can have multiple currencies serving different purposes.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `virtualCurrencyId` | nanoid | Unique identifier |
| `name` | string | Display name |
| `icon` | URL? | Optional icon for UI |
| `minAllowedBalance` | number? | Optional floor for user balances |
| `maxAllowedBalance` | number? | Optional ceiling for user balances |
| `origin` | `CATALOG` \| `CUSTOM` | Creation source |
| `defaultLang` | lang | Default language code |
| `langs` | lang[] | Supported languages (1–10) |

### Typical Configurations

| Currency | Purpose | Balance Constraints |
|----------|---------|-------------------|
| Experience Points (XP) | Drives leaderboard rankings and levels | No cap (min: 0) |
| Credits | Earned and spent on rewards | Min: 0, optional max |
| Streak Tokens | Spent to freeze streaks | Min: 0 |

A common setup uses two currencies: **XP** for progression (cannot be spent) and **credits** for rewards (earned and redeemable). Clients can define any number of currencies.

## Virtual Transaction

A **Virtual Transaction** is a ledger entry recording a credit or debit to a user's virtual currency balance.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `virtualTransactionId` | nanoid | Unique identifier |
| `virtualTransactionGroupId` | nanoid | Groups related transactions together |
| `redemptionGroupId` | nanoid? | Groups redemptions |
| `userId` | nanoid | The user whose balance is affected |
| `virtualCurrencyId` | nanoid | Which currency |
| `direction` | `CREDIT` \| `DEBIT` | Adding or removing |
| `amount` | number | The amount (must not be zero) |
| `state` | `PENDING` \| `COMPLETED` \| `EXPIRED` \| `REJECTED` | Lifecycle state |
| `redemptionMode` | `AUTO` \| `MANUAL` | How finalization works |
| `initiatorType` | enum | What caused this transaction (see below) |
| `initiator` | string | Identifier of the initiator (e.g., `"rewardRuleId#rr-123"`) |
| `counterpartType` | `USER` \| `SYSTEM` | The other party |
| `counterpart` | string | Identifier of the counterpart |
| `expiresAt` | ISO datetime? | Optional expiration date |
| `redeemedAt` | string? | When the transaction was redeemed |
| `additionalData` | record? | Custom metadata |

### Initiator Types

| Initiator Type | Description |
|---------------|-------------|
| `USER` | Direct user action (e.g., spending credits) |
| `REWARD_RULE` | Automatic payout from a reward rule evaluation |
| `STREAK_RULE` | Deduction for streak freeze |
| `SYSTEM` | Automated system process |
| `ADMIN` | Administrator manual action |

### Transaction Lifecycle

- **PENDING**: The transaction exists but has not been applied to the balance yet.
- **COMPLETED**: The transaction is finalized and reflected in the balance.
- **EXPIRED**: The transaction was not redeemed before `expiresAt`. Terminal state.
- **REJECTED**: The transaction was denied (e.g., insufficient balance for a debit). Terminal state.

For `AUTO` redemption mode, the transaction transitions directly to COMPLETED upon creation. For `MANUAL`, it stays PENDING until the user or admin explicitly redeems it.

## Virtual Balance

A **Virtual Balance** tracks a user's current balance for a specific currency.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `userId` | nanoid | The user |
| `virtualCurrencyId` | nanoid | The currency |
| `amount` | number | Total balance (including pending transactions) |
| `availableAmount` | number | Balance available for spending (completed transactions only) |

### Amount vs. Available Amount

- **`amount`**: The total, including PENDING transactions. Represents what the user _will_ have if all pending transactions complete.
- **`availableAmount`**: Only COMPLETED transactions. Represents what the user _can spend right now_.

For `AUTO` redemption mode, `amount` and `availableAmount` are always equal (since transactions complete immediately). The difference only matters for `MANUAL` mode, where a reward might be pending user redemption.

## How Rewards Are Processed

When a user performs an action that might trigger rewards:

1. **Event arrives**: The source system (Activity, Quiz, LearningPath, etc.) publishes an event.
2. **Entity remapping**: `ActivityLog` → `Activity`, `LearningPathLog` → `LearningPath`, etc.
3. **Rule lookup**: The system queries for matching rules across all three rule types (INSTANCE, ENTITY, TAG) in parallel.
4. **ALWAYS/FALLBACK resolution**: If any ALWAYS rules match, use those. Otherwise, use FALLBACK rules.
5. **Condition evaluation**: Each rule's `matchCondition` is evaluated against `{ event, previousEvent }`.
6. **Transaction calculation**: For each matching rule, for each reward in the rule:
   - The reward `expression` is evaluated against `{ event }`.
   - If the result is a non-zero number, a transaction input is prepared.
   - If the result is zero or non-numeric, the reward is skipped.
7. **Transaction creation**: Virtual transactions are created in the database.
8. **Balance update**: For AUTO transactions, the user's balance is updated immediately.

### Example: Multi-Currency Reward Rule

A single rule that awards both XP and credits for completing a learning path:

```json
{
  "rewardRuleId": "rr-lp-complete",
  "ruleType": "ENTITY",
  "matchEntity": "LearningPath",
  "matchCondition": { "===": [{ "var": "event.progress" }, "COMPLETE"] },
  "applicationMode": "ALWAYS",
  "rewards": [
    {
      "virtualCurrencyId": "vc-xp",
      "redemptionMode": "AUTO",
      "expression": 50
    },
    {
      "virtualCurrencyId": "vc-credits",
      "redemptionMode": "AUTO",
      "expression": 100
    }
  ]
}

{
  "rewardRuleId": "rr-quiz-difficulty",
  "ruleType": "ENTITY",
  "matchEntity": "Quiz",
  "matchCondition": { "===": [{ "var": "event.outcome" }, "SUCCESS"] },
  "applicationMode": "ALWAYS",
  "rewards": [
    {
      "virtualCurrencyId": "vc-xp",
      "redemptionMode": "AUTO",
      "expression": {
        "if": [
          { "===": [{ "var": "event.difficulty" }, "HARD"] }, 20,
          { "===": [{ "var": "event.difficulty" }, "MEDIUM"] }, 10,
          5
        ]
      }
    }
  ]
}

// ALWAYS rule: 20 XP for any activity tagged "premium"
{
  "ruleType": "TAG",
  "matchEntity": "Tag",
  "matchEntityId": "premium",
  "matchCondition": { "===": [{ "var": "event.progress" }, "COMPLETE"] },
  "applicationMode": "ALWAYS",
  "rewards": [{ "virtualCurrencyId": "vc-xp", "redemptionMode": "AUTO", "expression": 20 }]
}

// FALLBACK rule: 5 XP for any activity (baseline)
{
  "ruleType": "ENTITY",
  "matchEntity": "Activity",
  "matchCondition": { "===": [{ "var": "event.progress" }, "COMPLETE"] },
  "applicationMode": "FALLBACK",
  "rewards": [{ "virtualCurrencyId": "vc-xp", "redemptionMode": "AUTO", "expression": 5 }]
}