onairos/docs/INCIDENT_ENABLETRAINING_PIN_WEB_8.1.9.md

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

# Incident: `ReferenceError: enableTraining is not defined` (web, PIN confirm)

**Status:** Fixed in **8.1.10** (removes stale identifier usage; see `CHANGELOG.md`).  
**Build guard:** `scripts/verify-removed-props.cjs` runs after `verify-package-entries` in `npm run build` to block reintroducing `enableTraining` under `src/`.

---

## Symptom

In the browser (web bundle `onairos.bundle.js`), after the user taps **Confirm** on the **PIN** screen, the console shows:

```text
Uncaught (in promise) ReferenceError: enableTraining is not defined
```

This is a **host-app–independent** SDK error: the identifier is not a missing prop from the integrator; it was **not declared anywhere** in the v8 `OnairosButton` prop list.

---

## Root cause

1. **v8.0.0** removed the public prop `enableTraining` in favor of `trainingScreenMode` (and related props). See `docs/ONAIROS_BUTTON_PROPS.md` and the breaking-change notes in `CHANGELOG.md`.

2. A **later** change added new branches in `src/onairosButton.jsx` that still **referenced** `enableTraining` as if it were a variable in scope. After the prop was removed, that name is a **free identifier** → **ReferenceError** the first time that branch runs.

So the failure is not “8.1.9 regressed the API” in isolation; it is **stale code** that referenced a **removed** API, combined with a **rare code path** (see below).

---

## Git history (who, when, purpose)

### Commit that removed the API (intentional breaking change)

| Field | Detail |
|--------|--------|
| **Hash** | `42a2693` |
| **Date** | 2026-04-30 20:12 +0400 |
| **Author / committer** | joyalkenus |
| **Purpose** | v8.0.0: consolidate training props — remove `enableTraining`; introduce `trainingScreenMode` (`mock` \| `fast` \| `real` \| `none`). |

### Commit that reintroduced the identifier in new logic (accidental)

| Field | Detail |
|--------|--------|
| **Hash** | `625d270` |
| **Land date (committer)** | 2026-05-02 (merge/rebase timing; author date on patch may be earlier) |
| **Author** | joyalkenus |
| **Committer** | Anushka Jogalekar |
| **Purpose** | `fix(web): minimal backgroundLoadData handoff flow` — PIN/onboarding handoff, silent training when `trainingScreenMode === 'none'`, `backgroundLoadData` behaviour, etc. |

**Important:** `42a2693` is an **ancestor** of `625d270` on `main`. So the handoff work landed **after** `enableTraining` was removed from props; the new branches should have used `trainingScreenMode` / `resolvedTrainingMode` only. The review did not catch the leftover symbol.

---

## Why QA saw this on **8.1.9** / PIN only, not “every” v8 test before

Several factors stack; **mobile vs desktop browser is not the primary explanation** (same JS, same bundle logic).

1. **Path-specific:** The bad references lived in flows that run only after **PIN completion** (and similar onboarding-return logic), for **non–special-app** integrations (`webpageName` does not match wrapped / Valentine / Lunar / Ascend shortcuts). Other flows never executed those branches → **no error**.

2. **Same bug may exist across patch versions:** If **8.1.8** and **8.1.9** were built from the same `main` lineage after `625d270`, the **source bug can be identical**. Seeing it only on **8.1.9** often reflects **which scenario was exercised** (fresh signup → PIN → confirm) rather than a unique regression in the patch number.

3. **Session / user state:** Returning users with **`pinCreated` already true** often **never hit** the PIN confirm handler the same way as a **first-time PIN** flow.

4. **Special-app detection:** `getAppFlags()` depends on **`webpageName`** substrings (e.g. wrapped / lunar / valentine / ascend). Those paths **skip** the broken branch earlier → **no ReferenceError** even on PIN.

5. **Coverage gap:** “Tested all of v8” without a **full** pass of **normal web app → create PIN → confirm** can miss this entirely.

---

## Resolution

- **Code:** Remove all references to `enableTraining` in `onairosButton.jsx`; express behaviour with `trainingScreenMode` / resolved mode and existing platform-change flags (**8.1.10**).
- **Prevention:** `scripts/verify-removed-props.cjs` fails the build if `enableTraining` appears under `src/`.

---

## References

- `CHANGELOG.md` — **[8.1.10]**
- `docs/ONAIROS_BUTTON_PROPS.md` — v8 migration off `enableTraining`
- `scripts/verify-removed-props.cjs` — regression guard