> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module — Loyalty (LOY)

> Programs, points ledger, rules engine, rewards, coupons, referrals and tiers. Schema loyalty. Depends on core; never on messaging or crm.

| Document                                                                                                         | Purpose                                                                    |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`prd.md`](/modules/loyalty/prd)                                                                                 | What the module is, for whom, non-goals, success, commercial shape, phases |
| [`spec.md`](/modules/loyalty/spec)                                                                               | The living technical shape: entities, invariants, events, endpoints        |
| [`features/`](https://github.com/softcrumlabs/softcrum-suite/tree/master/docs/internal/modules/loyalty/features) | The feature specs — the units of delivery                                  |

## Feature roadmap

Fourteen deliveries, cut along independently shippable increments rather than along tables.
Six of them make F1a.

| FS                                                                           | Feature                                          | Phase | Depends on | Status  |
| ---------------------------------------------------------------------------- | ------------------------------------------------ | ----- | ---------- | ------- |
| [FS-LOY-0001](/modules/loyalty/features/fs-loy-0001-programs-and-currencies) | Programs & point currencies                      | F1a   | —          | `draft` |
| [FS-LOY-0002](/modules/loyalty/features/fs-loy-0002-points-ledger)           | Points ledger & FIFO lots                        | F1a   | 0001       | `draft` |
| [FS-LOY-0003](/modules/loyalty/features/fs-loy-0003-balance-projection)      | Balance projection & drift reconciliation        | F1a   | 0002       | `draft` |
| [FS-LOY-0004](/modules/loyalty/features/fs-loy-0004-rules-engine)            | Rules engine — conditions and effects            | F1a   | 0002       | `draft` |
| [FS-LOY-0005](/modules/loyalty/features/fs-loy-0005-rewards-catalog)         | Rewards catalog                                  | F1a   | 0001       | `draft` |
| [FS-LOY-0006](/modules/loyalty/features/fs-loy-0006-redemptions)             | Redemptions — parent/child, idempotent, rollback | F1a   | 0002, 0005 | `draft` |
| [FS-LOY-0007](/modules/loyalty/features/fs-loy-0007-coupons)                 | Coupons & mass code generation                   | F1b   | 0004       | `draft` |
| [FS-LOY-0008](/modules/loyalty/features/fs-loy-0008-stacking-rules)          | Stacking rules                                   | F1b   | 0006, 0007 | `draft` |
| [FS-LOY-0009](/modules/loyalty/features/fs-loy-0009-referrals)               | Referrals — double-sided, anti-fraud             | F1b   | 0004       | `draft` |
| [FS-LOY-0010](/modules/loyalty/features/fs-loy-0010-tiers)                   | Tiers & qualification windows                    | F1b   | 0002       | `draft` |
| [FS-LOY-0011](/modules/loyalty/features/fs-loy-0011-expiring-points)         | Expiring points & retention scans                | F1b   | 0002       | `draft` |
| [FS-LOY-0012](/modules/loyalty/features/fs-loy-0012-gamification)            | Gamification — badges & challenges               | F2    | 0010       | `draft` |
| [FS-LOY-0013](/modules/loyalty/features/fs-loy-0013-apply-discount)          | `apply_discount` effect                          | F2    | 0004       | `draft` |
| [FS-LOY-0014](/modules/loyalty/features/fs-loy-0014-wallet-passes)           | Wallet passes                                    | F2    | 0010       | `draft` |

All fourteen are written, in English and Spanish, and every one is at `0.1.0` / `draft` with its
own open questions listed. None is `approved` yet: approval is a decision, and the open questions
are exactly the decisions that have to be made first.

Spanish mirror: [`../../es/modules/loyalty/`](/es/modules/loyalty/overview). English is authoritative.

## The cut, explained

The decomposition follows one test: **can this ship alone and be worth something?**

* Ledger and balances are separate (`0002`, `0003`) because the ledger is the source of truth and
  the projection is a performance decision. They fail differently and are verified differently.
* Rules engine (`0004`) is independent of rewards (`0005`): a program can award points long
  before it has a catalog to spend them on.
* Redemptions (`0006`) needs both, which is why it closes F1a.
* Stacking (`0008`) is deliberately *not* inside coupons — it is a policy layer over redemptions
  and coupons together, and forcing it into either one would have produced a spec nobody could
  approve.

## Extension points reserved in F1

Present from the first migration, deliberately unused, so enabling them later needs zero data
migration:

| Seam                                         | Reserved for                                                  | Decision |
| -------------------------------------------- | ------------------------------------------------------------- | -------- |
| ~~`program_id` + invisible default program~~ | **shipped in F1** — multi-program is a first-class capability | ADR-021  |
| `money_component` nullable on redemptions    | mixed points + money redemption                               | DEC-H3   |
| `rule_effect_types` open parametric catalog  | `apply_discount` in F2                                        | DEC-H4   |
| `badges` / `challenges` schema               | gamification in F2                                            | spec.md  |