daily-notification-plugin/docs/improve-alarm-directives.md

✅ DIRECTIVE: Improvements to Alarm/Schedule/Notification Directives for Capacitor Plugin

Author: Matthew Raymer
Date: November 2025
Status: Active Improvement Directive

0. Goal of This Improvement Directive

Unify, refine, and strengthen the existing alarm-behavior directives so they:

1. Eliminate duplication between the Android Alarm Persistence Directive and the Plugin Exploration Directive.
2. Clarify scope and purpose (one is exploration/investigation; the other is platform mechanics).
3. Produce a single cohesive standard to guide future plugin improvements, testing, and documentation.
4. Streamline testing expectations into executable, check-box-style matrices.
5. Map OS-level limitations directly to plugin-level behavior so the JS/TS API contract is unambiguous.
6. Add missing iOS-specific limitations, guarantees, and required recovery patterns.
7. Provide an upgrade path from exploration → design decisions → implementation directives.

---

1. Structural Improvements to Apply

1.1 Split responsibilities into three documents (clear roles)

Your current directives mix exploration, reference, and design rules.

Improve by creating three clearly separated docs:

Document A — Platform Capability Reference (Android/iOS)

• Pure OS-level facts (no plugin logic).
• Use the Android Alarm Persistence Directive as the baseline.
• Add an equivalent iOS capability matrix.
• Keep strictly normative, minimal, stable.

Document B — Plugin Behavior Exploration (Android/iOS)

• Use the uploaded exploration directive as the baseline.
• Remove platform-mechanics explanations (moved to Document A).
• Replace vague descriptions with concrete, line-number-linked tasks.
• Add "expected vs actual" checklists to each test item.

Document C — Plugin Requirements & Improvements

• Generated after exploration.
• Defines the rules the plugin must follow to behave predictably.
• Defines recovery strategy (boot, reboot, missed alarms, force stop behavior).
• Defines JS API caveats and warnings.

This file you're asking for now (improvement directive) becomes the origin of Document C.

---

2. Improvements Needed to Existing Directives

2.1 Reduce duplication in Android section

The exploration directive currently repeats much of the alarm persistence directive.

Improve by:

• Referencing the Android alarm document instead of replicating content.
• Summarizing Android limitations in 5–7 lines in the exploration document.
• Keeping full explanation only in the Android alarm persistence reference file.

---

2.2 Add missing iOS counterpart to Android's capability matrix

You have a complete matrix for Android, but not iOS.

Add a parallel iOS matrix, including:

• Notification survives swipe → yes
• Notification survives reboot → yes (for calendar/time triggers)
• App logic runs in background → no
• Arbitrary code on trigger → no
• Recovery required → only if plugin has its own DB

This fixes asymmetry in current directives.

---

2.3 Clarify when plugin behavior depends on OS behavior

The exploration directive needs clearer labeling:

Label each behavior as:

• OS-guaranteed (iOS will fire pending notifications even when the app is dead)
• Plugin-guaranteed (plugin must reschedule alarms from DB)
• Not allowed (Android force-stop)

This removes ambiguity for plugin developers.

---

2.4 Introduce "Observed Behavior Table" in the exploration doc

Currently tests describe how to test but do not include space for results.

Add a table like:

Scenario	Expected (OS)	Expected (Plugin)	Actual Result	Notes
Swipe from recents	Fires	Fires
Device reboot	Does NOT fire automatically	Plugin must reschedule at boot

This allows the exploration document to be executable.

---

2.5 Add "JS/TS API Contract" section to both directives

A critical missing piece.

Define what JavaScript developers can assume:

Examples:

• "Notification will still fire if the app is swiped from recents."
• "Notifications WILL NOT fire after Android Force Stop until the app is opened again."
• "Reboot behavior depends on platform: iOS preserves, Android destroys."

This section makes plugin behavior developer-friendly and predictable.

---

2.6 Strengthen direction on persistence strategy

The exploration directive asks "what is persisted?" but does not specify what should be persisted.

Add:

Required Persistence Items

• alarm_id
• trigger time
• repeat rule
• channel/priority
• payload
• time created, last modified

And:

Required Recovery Points

• Boot event
• App cold start
• App warm start
• App returning from background fetch
• User tapping notification

---

2.7 Add iOS Background Execution Limits section

Currently missing.

Add:

• No repeating background execution APIs except BGTaskScheduler
• BGTaskScheduler requires minimum intervals
• Plugin cannot rely on background execution to reconstruct alarms
• Only notification center persists notifications

This is critical for plugin parity.

---

2.8 Integrate "missed alarm recovery" requirements

The exploration directive asks whether plugin detects missed alarms. The improvement directive must assert that it must.

Add requirement:

• If alarm time < now, and plugin is activated by reboot or user opening the app → plugin must generate a "missed alarm" event or notification.

---

3. Rewrite Testing Protocols into Standardized Formats

Replace long paragraphs with clear test tables, e.g.:

Android Reboot Test

Step	Action
1	Schedule alarm for 10 minutes later
2	Reboot device
3	Do not open app
4	Does alarm fire? (Expected: NO)
5	Open app
6	Does plugin detect missed alarm? (Expected: YES)

Same for iOS, force-stop, etc.

---

4. Add Missing Directive Sections

4.1 Policy Section

Define:

• Unsupported features
• Required permissions
• Required manifest entries
• Required notification channels

4.2 Versioning Requirements

Each change to alarm behavior is breaking and must have:

• MAJOR version bump
• Migration guide

---

5. Final Improvement Directive (What to Produce Next)

Here is your actionable deliverable list:

Produce Three New Documents

1. Platform Reference Document

   • Android alarm rules
   • iOS notification rules
   • Both in tabular form
   • (Rewrites + merges the two uploaded directives)

2. Exploration Results Template

   • Table format for results
   • Expected vs actual
   • Direct code references
   • Remove platform explanation duplication

3. Plugin Requirements + Future Implementation Directive

   • Persistence spec
   • Recovery spec
   • JS/TS API contract
   • Parity rules
   • Android/iOS caveats
   • Required test harness

Implement Major Improvements

• Strengthen separation of concerns
• Add iOS parity
• Integrate plugin-level persistence + recovery
• Add test matrices
• Add clear developer contracts
• Add missed-alarm handling requirements
• Add design rules for exact alarms and background restrictions

---

6. One-Sentence Summary

Rewrite the existing directives into three clear documents—platform reference, plugin exploration, and plugin implementation requirements—while adding iOS parity, recovery rules, persistence requirements, and standardized testing matrices, removing duplicated Android content, and specifying a clear JS/TS API contract.

---

Related Documentation

• Android Alarm Persistence Directive - Source material for Document A
• Explore Alarm Behavior Directive - Source material for Document B
• Boot Receiver Testing Guide - Testing procedures
• App Startup Recovery Solution - Recovery mechanisms

---

Next Steps

1. Create Document A: Platform Capability Reference (Android/iOS)
2. Create Document B: Plugin Behavior Exploration Template
3. Create Document C: Plugin Requirements & Implementation Directive
4. Execute exploration using Document B
5. Update Document C with findings from exploration
6. Implement improvements based on Document C

---

Status Tracking

• Document A created
• Document B created
• Document C created
• Exploration executed
• Findings documented
• Improvements implemented