# iOS Prefetch Glossary

**Purpose:** Shared terminology definitions for iOS prefetch testing and implementation

**Last Updated:** 2025-11-15  
**Status:** 🎯 **ACTIVE** - Reference glossary for iOS prefetch documentation

---

## Core Terms

**BGTaskScheduler** – iOS framework for scheduling background tasks (BGAppRefreshTask / BGProcessingTask). Provides heuristic-based background execution, not exact timing guarantees.

**BGAppRefreshTask** – Specific BGTaskScheduler task type for background app refresh. Used for prefetch operations that need to run periodically.

**UNUserNotificationCenter** – iOS notification framework for scheduling and delivering user notifications. Handles permission requests and notification delivery.

**T-Lead** – The lead time between prefetch and notification fire, e.g., 5 minutes. Prefetch is scheduled at `notificationTime - T-Lead`.

**earliestBeginDate** – The earliest time iOS may execute a BGTask. This is a hint, not a guarantee; iOS may run the task later based on heuristics.

**UTC** – Coordinated Universal Time. All internal timestamps are stored in UTC to avoid DST and timezone issues.

---

## Behavior Classification

**Bucket A/B/C** – Deterministic vs heuristic classification used in Behavior Classification:

- **Bucket A (Deterministic):** Test in Simulator and Device - Logic correctness
- **Bucket B (Partially Deterministic):** Test flow in Simulator, timing on Device
- **Bucket C (Heuristic):** Test on Real Device only - Timing and reliability

**Deterministic** – Behavior that produces the same results given the same inputs, regardless of when or where it runs. Can be fully tested in simulator.

**Heuristic** – Behavior controlled by iOS system heuristics (user patterns, battery, network, etc.). Timing is not guaranteed and must be tested on real devices.

---

## Testing Terms

**Happy Path** – The expected successful execution flow: Schedule → BGTask → Fetch → Cache → Notification Delivery.

**Negative Path** – Failure scenarios that test error handling: Network failures, permission denials, expired tokens, etc.

**Telemetry** – Structured metrics and counters emitted by the plugin for observability (e.g., `dnp_prefetch_scheduled_total`).

**Log Sequence** – The ordered sequence of log messages that indicate successful execution of a prefetch cycle.

---

## Platform Terms

**Simulator** – iOS Simulator for testing logic correctness. BGTask execution can be manually triggered.

**Real Device** – Physical iOS device for testing timing and reliability. BGTask execution is controlled by iOS heuristics.

**Background App Refresh** – iOS system setting that controls whether apps can perform background tasks. Must be enabled for BGTask execution.

**Low Power Mode** – iOS system mode that may delay or disable background tasks to conserve battery.

---

## References

- **Testing Guide:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
- **Test App Requirements:** `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md`
- **Main Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md`

---

**Status:** 🎯 **READY FOR USE**  
**Maintainer:** Matthew Raymer